Window QML Type

创建一个新的顶级窗口。更多...

• 所有成员的列表，包括继承的成员

属性

• 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 图形类型配合使用。

Window 对象可以在 Item 内部或另一个 Window 内部声明；在后一种情况下，内部的 Window 将自动成为外部 Window 的“暂存窗口”，并将外部 Window 作为其transientParent 。 在此情况下，大多数平台会将该窗口居中显示在外层窗口内，此外还可能存在其他与平台相关的行为，具体也取决于flags 。如果该嵌套窗口在您的应用程序中被设计为对话框，您还应将flags 设置为Qt.Dialog ，因为某些窗口管理器在未启用该标志时不会提供居中显示功能。

您还可以在顶级QtObject 中声明多个窗口，在这种情况下，这些窗口之间不会存在临时关联。

或者，您可以设置或绑定x 和y 来显式地将窗口定位在屏幕上。

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

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 中的xml-ph-0000@deepl.internal（以及xml-ph-0001@deepl.internal），而非 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

窗口的背景颜色。

设置此属性比使用单独的 Rectangle 更高效。

contentItem : Item [read-only]

场景中不可见的根项。

contentOrientation : Qt::ScreenOrientation

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

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

窗口方向与内容方向之间的差异决定了内容应旋转多少角度。

默认值为Qt::PrimaryOrientation 。

另请参阅 Screen 。

data : list<QtObject> [default]

data 属性允许您在一个窗口中自由组合视觉子元素、资源和其他窗口。

如果您将另一个窗口分配给数据列表，该嵌套窗口将对外部窗口而言成为“临时窗口”。

如果您将一个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 示例——窗口与屏幕。

定义窗口的位置和大小。

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

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

定义窗口的最大尺寸。

这是向窗口管理器发出的提示，用于防止窗口被调整到超过指定宽度和高度的尺寸。

定义窗口的最小尺寸。

这是向窗口管理器提供的一条提示，用于防止窗口被调整到小于指定宽度和高度的大小。

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()` 传递自定义配色方案来设置窗口的默认配色方案。

窗口会将显式调色板属性传递给子项和控件，从而覆盖该属性对应的任何系统默认值。

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

该窗口所属的窗口，即此窗口作为其短暂弹出窗口的父窗口。

这是向窗口管理器提供的提示，表明该窗口是代表临时父窗口的对话框或弹出窗口。这通常意味着：临时窗口在初次显示时会居中显示在其临时父窗口上方；最小化父窗口时也会同时最小化临时窗口；等等；不过，具体效果在不同平台上可能略有差异。

在 Item 或另一个 Window 内部声明一个 Window（无论是通过 `default property ` 还是专用属性），都会自动与包含它的窗口建立临时父子关系，除非显式设置了 `transientParent` 属性。当通过 `Qt.createComponent ` 或 `Qt.createQmlObject ` 创建 Window 项时，只要将 Item 或 Window 作为 `parent ` 参数传入，此规则同样适用。

具有临时父元素的 Window 不会被显示，直到其临时父元素被显示为止，即使visible 属性设置为true 也是如此。这同样适用于上述自动建立的临时父子关系。 特别是，如果窗口的容器元素是一个 Item，则该窗口不会显示，直到该容器项通过其视觉父级层次结构被添加到场景中为止。将 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 attached]

此附加属性用于指示窗口是否处于活动状态。Window 附加属性可附加到任何 Item 上。

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

import QtQuick

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

Window.activeFocusItem : Item [read-only attached]

此附加属性保存当前具有活动焦点的项目；如果没有具有活动焦点的项目，则保存null 。Window附加属性可附加到任何Item上。

Window.contentItem : Item [read-only attached]

此附加属性保存场景中的不可见根项，如果该项不在窗口中，则保存null 。Window附加属性可附加到任何Item上。

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

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

该附加属性与窗口在窗口系统中当前的显示状态（正常、最小化、最大化、全屏或隐藏）无关。Window 附加属性可附加到任何Item上。如果该项未在任何窗口中显示，其值将为Hidden 。

另请参阅 visible 和visibility 。

Window.window : Window [attached]

此附加属性用于存储项的窗口。Window 附加属性可附加到任何项上。

信号文档

afterAnimating()

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

您可以实现 onAfterAnimating 方法，在每个动画步骤之后执行额外处理。

closing(CloseEvent close)

当用户尝试关闭窗口时，会触发此信号。

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

devicePixelRatioChanged()

frameSwapped()

当帧已被排入渲染队列时，会触发此信号。在启用垂直同步的情况下，对于持续动画的场景，该信号在每个垂直同步间隔内最多触发一次。

sceneGraphError(SceneGraphError error, QString message)

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

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

方法文档

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 中引入。