Window QML Type

创建新的顶级窗口。更多

Import Statement:	`import QtQuick`
In C++:	QQuickWindow
Inherited By:	ApplicationWindow

所有成员（包括继承成员）的列表

属性

active : bool
activeFocusItem : Item
color : color
contentItem : Item
contentOrientation : Qt::ScreenOrientation
data : list<QtObject>
flags : Qt::WindowFlags
height : int
maximumHeight : int
maximumWidth : int
minimumHeight : int
minimumWidth : int
modality : Qt::WindowModality
opacity : real
palette : Palette (since 6.0)
screen : Screen
title : string
transientParent : QWindow
visibility : QWindow::Visibility
visible : bool
width : int
x : int
y : int

附属物业

active : bool
activeFocusItem : Item
contentItem : Item
height : int
visibility : QWindow::Visibility
width : int
window : Window

信号

afterAnimating()
closing(CloseEvent close)
devicePixelRatioChanged()
frameSwapped()
sceneGraphError(SceneGraphError error, QString message)

方法

void alert(int msec)
void close()
void hide()
void lower()
void raise()
void requestActivate()
void show()
void showFullScreen()
void showMaximized()
void showMinimized()
void showNormal()
void startSystemMove() (since 6.8)
void startSystemResize(Qt::Edges edges) (since 6.8)

详细说明

Window 对象为Qt Quick 场景创建一个新的顶级窗口。它会自动设置窗口，以便与QtQuick 图形类型一起使用。

窗口可以在一个项目或另一个窗口内声明，在这种情况下，内部窗口将自动成为外部窗口的 "暂存 "窗口，外部窗口则作为其transientParent 。在这种情况下，大多数平台都会将窗口居中显示在外窗口上，可能还会有其他与平台相关的行为，这也取决于flags 。如果嵌套窗口打算在应用程序中用作对话框，则还应将flags 设置为Qt.Dialog ，因为某些窗口管理器不会在没有该标志的情况下提供居中行为。

您也可以在顶级QtObject 中声明多个窗口，在这种情况下，窗口之间没有瞬时关系。

另外，您也可以设置或绑定x 和y ，在屏幕上明确定位窗口。

当用户尝试关闭窗口时，将发出closing 信号。您可以通过编写onClosing 处理程序来强制窗口保持打开（例如提示用户保存更改），该处理程序会设置close.accepted = false ，除非关闭窗口是安全的（例如不再有未保存的更改）。

onClosing: (close) => {
    if (document.changed) {
        close.accepted = false
        confirmExitPopup.open()
    }
}

// The confirmExitPopup allows user to save or discard the document,
// or to cancel the closing.

样式

与Qt Quick 中的所有可视化类型一样，Window 支持palettes 。不过，与Text 等类型一样，Window 默认不使用调色板。例如，要在操作系统主题改变时更改窗口的背景颜色，必须设置color ：

Window {
    visible: true

    // here we use the Window.active and Window.palette ordinary properties
    color: active ? palette.active.window : palette.inactive.window

    Text {
        anchors.centerIn: parent
        // here we use the Window.active attached property and the Item.palette property
        color: Window.active ? palette.active.windowText : palette.inactive.windowText
        text: Window.active ? "active" : "inactive"
    }
}

使用Qt Quick Controls中的ApplicationWindow （和Label ）而不是 Window 来获得自动样式。

属性文档

active : bool `[read-only]`

窗口的活动状态。

Window {
    visible: true

    // here we use the Window.active and Window.palette ordinary properties
    color: active ? palette.active.window : palette.inactive.window
}

另请参阅 requestActivate()。

activeFocusItem : Item `[read-only]`

当前处于活动状态的项目，如果没有处于活动状态的项目，则null 。

color : color

窗口的背景颜色。

设置该属性比使用单独的矩形更有效。

注意： 如果将颜色设置为"transparent" 或具有 alpha 透明度的颜色，则还应设置合适的flags ，如flags: Qt.FramelessWindowHint 。否则，窗口半透明可能无法在所有平台上一致启用。

contentItem : Item `[read-only]`

场景的隐形根项目。

contentOrientation : Qt::ScreenOrientation

这是给窗口管理器的提示，以防它需要显示弹出窗口、对话框、状态栏等与窗口相关的附加内容。

推荐的方向是Screen.orientation ，但应用程序不必支持所有可能的方向，因此可以选择忽略当前屏幕方向。

窗口方向和内容方向之间的差值决定了内容的旋转幅度。

默认值为Qt::PrimaryOrientation 。

另请参见 Screen 。

data : list<QtObject> `[default]`

数据属性允许您在窗口中自由混合可视化子窗口、资源和其他窗口。

如果将另一个窗口分配给数据列表，嵌套窗口将成为外部窗口的 "暂存 "窗口。

如果将Item 指定给数据列表，它将成为窗口contentItem 的子窗口，从而显示在窗口内部。该项目的父项将是窗口的contentItem ，它是该窗口内项所有权树的根。

如果您指定了任何其他对象类型，它将作为资源添加。

一般情况下不需要引用data 属性，因为它是 Window 的默认属性，因此所有子项都会自动分配给该属性。

另请参阅 QWindow::transientParent().

flags : Qt::WindowFlags

窗口的窗口标志。

窗口标志控制窗口在窗口系统中的外观，如是对话框、弹出式窗口还是普通窗口，以及是否应有标题栏等。

如果请求的标志无法满足，从该属性读取的标志可能与设置的标志不同。

import QtQuick

Window {
    id: mainWindow
    title: "Main Window"
    color: "#456"
    property real defaultSpacing: 10

    property Splash splash: Splash {
        onTimeout: mainWindow.show()
    }

    component Splash: Window {
        id: splash

        // a splash screen has no titlebar
        flags: Qt.SplashScreen
        // the transparent color lets background behind the image edges show through
        color: "transparent"
        modality: Qt.ApplicationModal // in case another application window is showing
        title: "Splash Window" // for the taskbar/dock, task switcher etc.
        visible: true

        // here we use the Screen attached property to center the splash window
        x: (Screen.width - splashImage.width) / 2
        y: (Screen.height - splashImage.height) / 2
        width: splashImage.width
        height: splashImage.height

        property int timeoutInterval: 2000
        signal timeout

        Image {
            id: splashImage
            source: "images/qt-logo.png"
        }

        TapHandler {
            onTapped: splash.timeout()
        }

        Timer {
            interval: splash.timeoutInterval; running: true; repeat: false
            onTriggered: {
                splash.visible = false
                splash.timeout()
            }
        }
    }
}

另请参阅 Qt::WindowFlags 和Qt Quick 示例 - 窗口和屏幕。

height : int

width : int

x : int

y : int

定义窗口的位置和大小。

(x,y)位置相对于Screen （如果只有一个）或虚拟桌面（多个屏幕的排列）。

注意： 并非所有窗口系统都支持设置或查询顶层窗口位置。在此类系统中，通过编程移动窗口可能不会产生任何效果，当前位置可能会返回人为值，如QPoint(0, 0) 。

Window { x: 100; y: 100; width: 100; height: 100 }

maximumHeight : int

maximumWidth : int

定义窗口的最大尺寸。

这是给窗口管理器的提示，以防止调整大小超过指定的宽度和高度。

minimumHeight : int

minimumWidth : int

定义窗口的最小尺寸。

这是给窗口管理器的一个提示，以防止大小调整到低于指定的宽度和高度。

modality : Qt::WindowModality

窗口的模式。

模式窗口会阻止其他窗口接收输入事件。可能的值包括 Qt.NonModal（默认值）、Qt.WindowModal 和 Qt.ApplicationModal。

opacity : real

窗口的不透明度。

如果窗口系统支持窗口不透明度，该值可用于淡入淡出窗口，或使窗口半透明。

1.0 或以上的值被视为完全不透明，而 0.0 或以下的值被视为完全透明。介于两者之间的值表示介于两个极端之间的不同半透明程度。

默认值为 1.0。

palette : Palette `[since 6.0]`

该属性包含当前为窗口设置的调色板。

默认调色板取决于系统环境。QGuiApplication 维护一个系统/主题调色板，作为所有应用程序窗口的默认调色板。您也可以在加载任何 QML 之前，通过向QGuiApplication::setPalette() 传递自定义调色板来设置窗口的默认调色板。

Window 将显式调色板属性传播给子项目和控件，并覆盖该属性的任何系统默认值。

import QtQuick
import QtQuick.Controls

Window {
    visible: true

    // here we use the Window.active and Window.palette ordinary properties
    color: active ? palette.active.window : palette.inactive.window

    // colors that are not customized here come from SystemPalette
    palette.active.window: "peachpuff"
    palette.windowText: "brown"

    Text {
        anchors.centerIn: parent
        // here we use the Window.active attached property and the Item.palette property
        color: Window.active ? palette.active.windowText : palette.inactive.windowText
        text: Window.active ? "active" : "inactive"
    }

    Button {
        text: "Button"
        anchors {
            bottom: parent.bottom
            bottomMargin: 6
            horizontalCenter: parent.horizontalCenter
        }
    }
}

该属性在 Qt 6.0 中引入。

另请参阅 Item::palette,Popup::palette,ColorGroup, 和SystemPalette 。

screen : Screen

与窗口相关联的屏幕。

如果在显示窗口前指定，除非已设置明确的窗口位置，否则窗口将显示在该屏幕上。该值必须是Application.screens 数组中的元素。

注意： 为确保在创建底层本地窗口时将窗口与所需屏幕关联起来，应尽早设置该属性，且其值的设置不能延迟。在没有窗口系统的嵌入式平台上，这一点尤为重要，因为在这种平台上，每个屏幕一次只能有一个窗口。如果新界面与旧界面属于同一虚拟桌面，则在窗口创建后设置屏幕不会移动窗口。

另请参阅 QWindow::setScreen(),QWindow::screen(),QScreen, 和Application 。

title : string

窗口系统中的窗口标题。

窗口标题可能出现在窗口装饰的标题区域，具体取决于窗口系统和窗口标志。窗口系统还可能使用该标题在其他上下文（如任务切换器）中标识窗口。

transientParent : QWindow

该窗口为暂存弹出窗口的窗口。

这是给窗口管理器的提示，即该窗口是代表暂存父窗口的对话框或弹出窗口。这通常意味着瞬态窗口在初始显示时将位于其瞬态父窗口的中心，最小化父窗口也将最小化瞬态窗口，等等；但不同平台的结果略有不同。

通过default property 或专用属性在一个项目或另一个窗口内声明一个窗口，将自动与包含的窗口建立暂存父窗口关系，除非明确设置了暂存父窗口属性。这也适用于通过Qt.createComponent 或Qt.createQmlObject 创建窗口项时，只要parent 参数传递的是项或窗口。

即使visible 属性为true ，在显示暂存父窗口之前，也不会显示具有暂存父窗口的窗口。这也适用于上述自动暂存父级关系。特别是，如果窗口的包含元素是一个项目，则在包含项目通过其可视化父级层次结构添加到场景之前，窗口不会显示。将 transientParent 设置为null 将覆盖这一行为：

Window {
    // visible is false by default
    Window {
        transientParent: null
        visible: true
    }
}

根据窗口管理器的不同，为了使窗口在默认情况下居中于其暂存父级元素之上，可能还需要将Window::flags 属性设置为合适的Qt::WindowType （如Qt::Dialog ）。

另请参阅 parent().

visibility : QWindow::Visibility

窗口的屏幕占用状态。

可见性是指窗口在窗口系统中的显示状态是正常、最小化、最大化、全屏还是隐藏。

将可见性设置为AutomaticVisibility 意味着给窗口一个默认的可见状态，根据平台的不同，可能是FullScreen 或Windowed 。不过，在读取可见性属性时，您将始终获得实际状态，而不是AutomaticVisibility 。

当窗口不是visible 时，其可见性为Hidden 。将可见性设置为Hidden 与将visible 设置为false 相同。

默认值为Hidden

import QtQuick
import QtQuick.Controls

Window {
    id: win
    flags: Qt.Window | Qt.WindowFullscreenButtonHint
    visibility: fullscreenButton.checked ? Window.FullScreen : Window.Windowed

    Button {
        id: fullscreenButton
        anchors {
            right: parent.right
            top: parent.top
            margins: 6
        }
        width: height
        checkable: true
        Binding on checked { value: win.visibility === Window.FullScreen }
        text: "⛶"
        ToolTip.visible: hovered
        ToolTip.delay: Qt.styleHints.mousePressAndHoldInterval
        ToolTip.text: win.visibility === Window.FullScreen ? qsTr("restore") : qsTr("fill screen")
    }
}

另请参阅 visible 和Qt Quick 示例 - 窗口和屏幕。

visible : bool

窗口在屏幕上是否可见。

将 visible 设置为 false 与将visibility 设置为Hidden 相同。

默认值是false ，除非通过设置visibility 来覆盖。

另请参阅 visibility 。

附加属性文档

Window.active : bool `[read-only]`

该附加属性显示窗口是否处于活动状态。窗口附加属性可以附加到任何项上。

下面是一个示例，通过更改标签来显示其所在窗口的活动状态：

import QtQuick

Text {
    text: Window.active ? "active" : "inactive"
}

Window.activeFocusItem : Item `[read-only]`

此附加属性保留当前处于活动焦点的项目，如果没有处于活动焦点的项目，则保留null 。窗口附加属性可附加到任何项目。

Window.contentItem : Item `[read-only]`

此附加属性包含场景的不可见根项目，如果项目不在窗口中，则包含null 。窗口附加属性可附加到任何项目。

Window.height : int

Window.width : int

这些附加属性用于保存项目窗口的大小。窗口附加属性可附加到任何项目。

Window.visibility : QWindow::Visibility `[read-only]`

此附加属性用于保存窗口当前在窗口系统中是以正常、最小化、最大化、全屏还是隐藏的方式显示。Window 附加属性可附加到任何项目。如果该项目未在任何窗口中显示，其值将为Hidden 。

另请参阅 visible 和visibility 。

Window.window : Window

该附加属性用于保存项目的窗口。窗口附加属性可附加到任何项目。

信号文档

afterAnimating()

在请求渲染线程执行场景图同步之前，GUI 线程会发出该信号。

您可以实现 onAfterAnimating，以便在每个动画步骤后进行额外处理。

注：相应的处理程序是onAfterAnimating 。

closing(CloseEvent close)

当用户试图关闭窗口时会发出该信号。

该信号包含一个close 参数。close.accepted 属性默认为 true，以便允许关闭窗口；但如果需要在关闭窗口前执行其他操作，则可以实现onClosing 处理程序并设置close.accepted = false 。

注：相应的处理程序是onClosing 。

devicePixelRatioChanged()

注：相应的处理程序是onDevicePixelRatioChanged 。

frameSwapped()

该信号在帧排队等待呈现时发出。启用垂直同步后，在连续动画场景中，每个 vsync 间隔最多发出一次信号。

注：相应的处理程序是onFrameSwapped 。

sceneGraphError(SceneGraphError error, QString message)

当场景图初始化过程中发生error 时，将发出该信号。

您可以实现 onSceneGraphError(error, message) 以自定义方式处理图形上下文创建失败等错误。如果没有处理程序连接到此信号，Quick 将打印message 或显示消息框，并终止应用程序。

注：相应的处理程序是onSceneGraphError 。

方法文档

void alert(int msec)

使警报显示msec 毫秒。如果msec 为0 （默认值），则警报将无限期显示，直到窗口再次处于活动状态。

在警报状态下，窗口会通过闪烁或跳动任务栏条目等方式表示需要注意。

void close()

关闭窗口。

调用此方法或用户试图通过标题栏按钮关闭窗口时，将发出closing 信号。如果没有处理程序，或处理程序没有撤销关闭权限，窗口随后将关闭。如果QGuiApplication::quitOnLastWindowClosed 属性为true ，且没有打开其他窗口，应用程序将退出。

void hide()

隐藏窗口。

相当于将visible 设置为false 或将visibility 设置为Hidden 。

另请参阅 show() 。

void lower()

降低窗口系统中的窗口。

要求降低窗口，使其显示在其他窗口下方。

void raise()

提升窗口系统中的窗口。

要求提升窗口，使其显示在其他窗口上方。

void requestActivate()

要求激活窗口，即接收键盘焦点。

void show()

显示窗口。

这等同于调用showFullScreen()、showMaximized() 或showNormal()，具体取决于平台对窗口类型和标记的默认行为。

另请参阅 showFullScreen()、showMaximized()、showNormal()、hide() 和QQuickItem::flags()。

void showFullScreen()

将窗口显示为全屏。

相当于将visibility 设置为FullScreen 。

void showMaximized()

显示窗口最大化。

相当于将visibility 设置为Maximized 。

void showMinimized()

将窗口显示为最小化。

相当于将visibility 设置为Minimized 。

void showNormal()

以正常方式显示窗口，即既不最大化，也不最小化，也不全屏。

相当于将visibility 设置为Windowed 。

`[since 6.8]` void startSystemMove()

启动特定于系统的移动操作。

使用平台支持在窗口上启动交互式移动操作。窗口会跟随鼠标光标移动，直至释放鼠标按钮。

使用此方法而不是setPosition ，因为它允许窗口管理器处理捕捉、平铺和相关动画。Wayland 不支持setPosition ，因此这是应用程序影响窗口位置的唯一方法。

此方法在 Qt 6.8 中引入。

`[since 6.8]` void startSystemResize(Qt::Edges edges)

启动特定于系统的调整大小操作。

使用平台支持在窗口上启动交互式调整大小操作。拖动时，指定的边缘会跟随鼠标指针移动。

使用此方法而不是setGeometry ，因为它允许窗口管理器在调整屏幕边缘大小时处理捕捉和调整动画。

edges 必须是单个边缘或两个相邻边缘（角）的组合。不允许使用其他值。

此方法在 Qt 6.8 中引入。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.

Window QML Type

属性

附属物业

信号

方法

详细说明

样式

属性文档

active : bool [read-only]

activeFocusItem : Item [read-only]

color : color

contentItem : Item [read-only]

contentOrientation : Qt::ScreenOrientation

data : list<QtObject> [default]

flags : Qt::WindowFlags

height : int

width : int

x : int

y : int

maximumHeight : int

maximumWidth : int

minimumHeight : int

minimumWidth : int

modality : Qt::WindowModality

opacity : real

palette : Palette [since 6.0]

screen : Screen

title : string

transientParent : QWindow

visibility : QWindow::Visibility

visible : bool

附加属性文档

Window.active : bool [read-only]

Window.activeFocusItem : Item [read-only]

Window.contentItem : Item [read-only]

Window.height : int

Window.width : int

Window.visibility : QWindow::Visibility [read-only]

Window.window : Window

信号文档

afterAnimating()

closing(CloseEvent close)

devicePixelRatioChanged()

frameSwapped()

sceneGraphError(SceneGraphError error, QString message)

方法文档

void alert(int msec)

void close()

void hide()

void lower()

void raise()

void requestActivate()

void show()

void showFullScreen()

void showMaximized()

void showMinimized()

void showNormal()

[since 6.8] void startSystemMove()

[since 6.8] void startSystemResize(Qt::Edges edges)

active : bool `[read-only]`

activeFocusItem : Item `[read-only]`

contentItem : Item `[read-only]`

data : list<QtObject> `[default]`

palette : Palette `[since 6.0]`

Window.active : bool `[read-only]`

Window.activeFocusItem : Item `[read-only]`

Window.contentItem : Item `[read-only]`

Window.visibility : QWindow::Visibility `[read-only]`

`[since 6.8]` void startSystemMove()

`[since 6.8]` void startSystemResize(Qt::Edges edges)