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.2Window {visible: truewidth: 400height: 300minimumWidth: 400title: "基础窗口"flags: Qt.Window | Qt.WindowStaysOnTopHintcolor: "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.6ApplicationWindow {visible: trueid: mainWindowtitle: "应用主窗口"width: 800height: 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: parentLabel {text: "Title"elide: Label.ElideRighthorizontalAlignment: Qt.AlignHCenterverticalAlignment: Qt.AlignVCenterLayout.fillWidth: true}ToolButton {text: qsTr("⋮")onClicked: menu.open()}}}// 主内容区域SplitView {anchors.fill: parentorientation: Qt.VerticalTextEdit {id: textEditorhorizontalAlignment: Text.AlignHCenterwrapMode: TextEdit.WrapSplitView.fillHeight: trueselectByMouse: true}TextEdit {id: textCopyhorizontalAlignment: Text.AlignHCenterwrapMode: TextEdit.Wraptext:"在此输入要复制的内容"color: "blue"SplitView.minimumWidth: 400selectByMouse: true}}// 业务逻辑处理对象QtObject {id: fileHandlerfunction createNew() {textEditor.text = "新建文件"console.log("新建文件逻辑")}function openFile() {textEditor.text = "打开文件"console.log("打开文件逻辑")}}
}

运行结果：