Qt Quick 与 QML（二）qml中的顶级窗口

一**、前言******

在QML中，‌顶级窗口不是绝对必需的‌，但它在大多数应用场景中扮演着关键角色。

需要顶级窗口的典型场景：

1.独立桌面/移动应用‌

必须使用Window或ApplicationWindow作为根元素。

2.多窗口应用

每个独立窗口都需要一个顶级窗口实例。

不需要顶级窗口的情况‌

1.作为组件嵌入其他窗口

当QML文件被用作子组件时（通过Loader或直接嵌套）

2.嵌入式系统

在嵌入式Linux（如使用EGLFS插件）可直接用Item作根元素

二******、类型******

**1. Window（基础窗口）**‌

定位‌：轻量级通用窗口，类似传统 GUI 的 QWidget。

功能特性‌：

• 仅提供基础窗口属性（标题、尺寸、可见性等）
• ‌无预置框架‌：需手动实现标题栏、关闭按钮28
• 支持嵌套或独立使用（如弹窗）

适用场景‌：自定义弹窗、简单浮动窗口、轻量级应用

2.**ApplicationWindow（应用主窗口）**‌

定位‌：功能完整的应用框架，类似 QMainWindow。

功能特性‌：

• 内置应用框架结构：支持菜单栏（menuBar）、工具栏（header）、状态栏（footer）17
• 内容区域（contentItem）自动管理布局

适用场景‌：复杂桌面应用主窗口（需菜单/工具栏）

3.区别

特性‌	‌**Window**‌	‌**ApplicationWindow**‌
‌功能定位‌	轻量级基础容器	完整应用框架
‌内置组件‌	❌ 无标题栏/菜单栏	✅ 支持菜单栏/工具栏/状态栏
‌内容管理‌	手动布局子元素	提供 contentItem 自动布局区域
‌复杂度‌	低（适合简单场景）	高（适合复杂应用）
‌所属模块‌	QtQuick.Window	QtQuick.Controls

关键注意‌：所有顶级窗口必须显式设置 visible: true 和有效尺寸（如 width/height），否则会导致界面无法渲染

三******、******属性

1.**Window（基础窗口）**‌

需要导入模块

import QtQuick.Window 2.2

‌分类‌	‌属性‌	‌类型‌	‌说明‌	‌示例‌
‌窗口状态‌	visible	bool	控制窗口显示/隐藏（默认false）	visible: true
	active	bool（只读）	指示窗口是否为活动窗口	onActiveChanged: console.log(active)
	modality	Qt::WindowModality	窗口模态类型（非模态/窗口模态/应用模态）	modality: Qt.WindowModal
‌尺寸位置‌	width/height	int	窗口初始尺寸（像素）	width: 800; height: 600
	minimumWidth/minimumHeight maximumWidth/maximumHeight	int	窗口最小/最大尺寸限制	minimumWidth: 400; maximumHeight: 900
	x/y	int	窗口左上角屏幕坐标	x: 100; y: 200
‌内容布局‌	contentItem	Item（只读）	窗口内容根Item	Component.onCompleted: console.log(contentItem)
	activeFocusItem	Item（只读）	当前获得键盘焦点的子Item	onActiveFocusItemChanged: focusItem.color = "red"
	contentOrientation	Qt::ScreenOrientation	强制内容旋转方向（横屏/竖屏）	contentOrientation: Qt.LandscapeOrientation
‌视觉样式‌	color	color	窗口背景色	color: "#F0F0F0"
	opacity	real	透明度（0.0透明~1.0不透明）	opacity: 0.8
	title	string	窗口标题栏文字	title: "设置面板"
‌高级控制‌	flags	Qt::WindowFlags	窗口行为标志（如无边框/置顶）	flags: Qt.FramelessWindowHint
	transientParent	QWindow	关联父窗口（用于对话框归属）	transientParent: mainWindow
	screen	variant	绑定到特定显示器3	screen: Qt.application.screens
	visibility	QWindow::Visibility	窗口显示模式（全屏/最小化等）	visibility: Window.FullScreen
‌其他‌	data	list<Object>	动态存储子对象列表	通常自动管理

2.**ApplicationWindow（应用主窗口）**‌

分类‌	‌属性‌	‌类型‌	‌说明‌	‌示例‌
‌焦点控制‌	activeFocusControl	Control	当前获得键盘焦点的子控件（只读属性）	Text { focus: true } // 当该Text获得焦点时，父控件此属性指向它
‌背景装饰‌	background	Item	控件的背景元素，可覆盖默认样式	background: Rectangle { color: "lightblue" }
‌内容容器‌	contentData	list<Object>	动态添加子项的默认列表（自动成为contentItem的子项）	Component.onCompleted: contentData.push(Qt.createComponent("Button.qml"))
	contentItem	Item	内容项的根容器，用于布局子控件	contentItem: RowLayout { spacing: 5 }
‌文本样式‌	font	font	控件内文本的字体属性（可继承）	font { family: "Arial"; pixelSize: 16 }
‌结构布局‌	footer	Item	底部区域（如Page组件的页脚）	footer: ToolBar { Label { text: "Status" } }
	header	Item	顶部区域（如Page组件的标题栏）	header: TabBar { TabButton { text: "Home" } }
‌本地化‌	locale	Locale	区域设置（影响日期/数字格式）	locale: Qt.locale("zh_CN")
‌菜单系统‌	menuBar	Item	菜单栏容器（ApplicationWindow专用）	menuBar: MenuBar { Menu { title: "File" } }
‌颜色主题‌	palette	palette	控件的调色板（可覆盖系统主题）	palette { buttonText: "red" }

menuBar核心属性与方法

‌组件‌	‌属性/方法‌	‌类型‌	‌说明‌	‌示例‌
‌menuBar‌	delegate	Component	自定义菜单项渲染模板	delegate: MenuBarItem { text: model.title }
	menus	list<Menu>	包含所有子菜单的只读列表	onClicked: console.log(menuBar.menus.length)
	addMenu(Menu)	Method	动态添加菜单	menuBar.addMenu(Qt.createQmlObject('Menu{title:"Tools"}', menuBar))
	takeMenu(int)	Method	移除指定索引的菜单	menuBar.takeMenu(0).destroy()

header支持的组件类型‌

组件类型‌	‌说明‌	‌典型应用场景‌	‌示例代码‌
‌**ToolBar**‌	标准工具栏组件，通常包含操作按钮或导航控件	应用顶部导航栏	header: ToolBar {ToolButton { icon.source: "menu.svg" } Label { text: "应用标题" }}
‌**TabBar**‌	选项卡栏组件，用于页面切换	多页面应用的标签导航	header: TabBar {TabButton { text: "首页" } TabButton { text: "设置" }}
‌**Rectangle**‌	基础矩形容器，可自定义颜色/渐变	自定义背景的简单标题栏	header: Rectangle {color: "lightblue"; Label { anchors.centerIn: parent; text: "标题" }}
‌**Row/RowLayout**‌	水平布局容器，排列子控件	组合多个控件（图标+文字）	header: RowLayout { Image { source: "logo.png" } Label { text: "系统名称"; Layout.fillWidth: true }}
‌**Label**‌	文本标签	简易标题显示	header: Label {text: "欢迎页面";horizontalAlignment: Text.AlignHCenter}
‌**SwipeView**‌	滑动视图容器	可横向滑动的Banner区域	header: SwipeView {Image { source: "banner1.jpg" } Image { source: "banner2.jpg" }}
‌自定义组件‌	用户复合组件（如MyCustomHeader.qml）	复用复杂UI结构	header: MyCustomHeader { title: "仪表盘" showBackButton: true}

footer支持的组件类型

同上‌ ，把示例中的header换成footer

四******、代码示例******

1.**Window（基础窗口）**‌

import QtQuick 2.6
import QtQuick.Window 2.2

Window {
    visible: true
    width: 400
    height: 300
    minimumWidth: 400
    title: "基础窗口"
    flags: Qt.Window | Qt.WindowStaysOnTopHint
    color: "lightyellow"

    Text {
        text: qsTr("Hello, World!"); font.pixelSize: 24; anchors.centerIn: parent
    }
}

运行结果：

2.**ApplicationWindow（应用主窗口）**‌

import QtQuick 2.6
import QtQuick.Controls 2.14
import QtQuick.Layouts 1.6

ApplicationWindow {
    visible: true
    id: mainWindow
    title: "应用主窗口"
    width: 800
    height: 600

    // 菜单栏实现
    menuBar: MenuBar {
        Menu {
            title: "文件"
            Action {
                text: "新建"
                onTriggered: fileHandler.createNew()
            }
            Action {
                text: "打开"
                onTriggered: fileHandler.openFile()
            }
            MenuSeparator {}
            Action {
                text: "退出"
                onTriggered: Qt.quit()
            }
        }

        Menu {
            title: "编辑"
            MenuItem {
                text: "复制"
                onTriggered: {textCopy.selectAll(); textCopy.copy()}
            }
            MenuItem {
                text: "粘贴"
                onTriggered: textEditor.paste()
            }
        }
    }

    // 状态栏
    footer: Label {
        text: "就绪"
    }

    header: ToolBar {
        background: Rectangle {
            color: "lightyellow"
        }
        RowLayout {
            anchors.fill: parent
            Label {
                text: "Title"
                elide: Label.ElideRight
                horizontalAlignment: Qt.AlignHCenter
                verticalAlignment: Qt.AlignVCenter
                Layout.fillWidth: true
            }
            ToolButton {
                text: qsTr("⋮")
                onClicked: menu.open()
            }
        }
    }

    // 主内容区域
    SplitView {
        anchors.fill: parent
        orientation: Qt.Vertical

        TextEdit {
            id: textEditor
            horizontalAlignment: Text.AlignHCenter
            wrapMode: TextEdit.Wrap
            SplitView.fillHeight: true
            selectByMouse: true
        }
        TextEdit {
            id: textCopy
            horizontalAlignment: Text.AlignHCenter
            wrapMode: TextEdit.Wrap
            text:"在此输入要复制的内容"
            color: "blue"
            SplitView.minimumWidth: 400
            selectByMouse: true
        }
    }

    // 业务逻辑处理对象
    QtObject {
        id: fileHandler
        function createNew() {
            textEditor.text = "新建文件"
            console.log("新建文件逻辑")
        }
        function openFile() {
            textEditor.text = "打开文件"
            console.log("打开文件逻辑")
        }
    }
}

运行结果：