Window QML Type

创建新的顶级窗口。更多

Import Statement:	`import QtQuick`
In C++:	QQuickWindow

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

属性

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 : variant
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)
frameSwapped()
sceneGraphError(SceneGraphError error, QString message)

方法

alert(int msec)
close()
hide()
lower()
raise()
requestActivate()
show()
showFullScreen()
showMaximized()
showMinimized()
showNormal()

详细说明

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"
    }
}

ApplicationWindow Label从 Qt Quick Controls而不是 Window 来获得自动样式。

属性文档

height : int

width : int

x : int

y : int

定义窗口的位置和大小。

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

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

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

minimumHeight : int

minimumWidth : int

定义窗口的最小尺寸。

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

maximumHeight : int

maximumWidth : int

定义窗口的最大尺寸。

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

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 示例 - 窗口和屏幕。

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 : variant

与窗口关联的屏幕。

如果在显示窗口之前指定该属性，将导致窗口显示在该屏幕上，除非已设置了明确的窗口位置。该值必须是 Qt.application.screens 数组中的元素。

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

另请参阅 QWindow::setScreen( )、QWindow::screen( )、QScreen 和Qt.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.height : int

Window.width : int

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

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.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 。

frameSwapped()

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

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

sceneGraphError(SceneGraphError error, QString message)

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

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

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

方法文档

alert(int msec)

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

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

close()

关闭窗口

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

hide()

隐藏窗口。

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

另请参阅 show()。

lower()

在窗口系统中降低窗口。

要求窗口降低到其他窗口下方。

raise()

提升窗口系统中的窗口。

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

requestActivate()

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

show()

显示窗口。

这相当于调用showFullScreen(),showMaximized(), 或showNormal(), 具体取决于平台对窗口类型和标志的默认行为。

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

showFullScreen()

全屏显示窗口。

相当于将visibility 设置为FullScreen 。

showMaximized()

显示窗口最大化。

相当于将visibility 设置为Maximized 。

showMinimized()

显示窗口最小化。

相当于将visibility 设置为Minimized 。

showNormal()

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

等同于将visibility 设置为Windowed 。

© 2025 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.