x ：真实

y ：真实

z ：真实

Signals

• void aboutToHide ()
• void aboutToShow ()
• void closed ()
• void opened ()

Methods

• void close ()
• forceActiveFocus (enumeration reason )
• void open ()

Detailed Description

弹出窗口是类似弹出窗口的用户界面控件的基本类型。它可以与 Window 或 ApplicationWindow 一起使用。

import QtQuick.Window 2.2
import QtQuick.Controls 2.12
ApplicationWindow {
    id: window
    width: 400
    height: 400
    visible: true
    Button {
        text: "Open"
        onClicked: popup.open()
    Popup {
        id: popup
        x: 100
        y: 100
        width: 200
        height: 300
        modal: true
        focus: true
        closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent
}

为了确保弹出窗口显示在场景中其他项目的上方，建议使用 ApplicationWindow 。 ApplicationWindow 还提供背景调光效果。

Popup 不提供自己的布局，但需要您定位其内容，例如通过创建 RowLayout 或 ColumnLayout 。

声明为 Popup 子项的项目自动成为 Popup 的 contentItem 的父项。动态创建的项目需要明确成为 contentItem 的父级。

Popup Layout

下图说明了窗口内弹出窗口的布局：

弹出窗口的 implicitWidth 和 implicitHeight 通常基于背景和内容项的隐式大小以及任何插图和填充。这些属性确定在未指定显式 width 或 height 时弹出窗口的大小。

contentItem 的几何形状由填充决定。以下示例在弹出窗口及其内容的边界之间保留 10px 的填充：

Popup {
    padding: 10
    contentItem: Text {
        text: "Content"
}

background 项目填充弹出窗口的整个宽度和高度，除非为其指定了插图或显式大小。

负插图可用于使背景大于弹出窗口。以下示例使用负插图将阴影放置在弹出窗口边界之外：

Popup {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6
    background: BorderImage {
        source: ":/images/shadowed-background.png"
}

Popup Sizing

如果 Popup 中仅使用单个项目，它将调整大小以适应其所包含项目的隐式大小。这使得它特别适合与布局一起使用。

Popup {
    ColumnLayout {
        anchors.fill: parent
        CheckBox { text: qsTr("E-mail") }
        CheckBox { text: qsTr("Calendar") }
        CheckBox { text: qsTr("Contacts") }
}

有时弹出窗口中可能有两个项目：

Popup {
    SwipeView {
        // ...
    PageIndicator {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
}

在这种情况下，Popup 无法计算合理的隐式大小。由于我们将 PageIndicator 锚定在 SwipeView 上，因此我们可以简单地将内容大小设置为视图的隐式大小：

Popup {
    contentWidth: view.implicitWidth
    contentHeight: view.implicitHeight
    SwipeView {
        id: view
        // ...
    PageIndicator {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
 }

Popup Positioning

与 Qt Quick 中的项目类似，Popup 的 x 和 y 坐标是相对于其父级的。这意味着，例如，打开 Button 子级的弹出窗口将导致弹出窗口相对于按钮定位。

以下示例使用附加的 Overlay.overlay 属性将弹出窗口定位在窗口的中心，而不管打开弹出窗口的按钮的位置如何：

Button {
    onClicked: popup.open()
    Popup {
        id: popup
        parent: Overlay.overlay
        x: Math.round((parent.width - width) / 2)
        y: Math.round((parent.height - height) / 2)
        width: 100
        height: 100
}

无论其父项如何，将弹出窗口置于窗口中心的另一种方法是使用 anchors.centerIn ：

ApplicationWindow {
    id: window
    // ...
    Pane {
        // ...
        Popup {
            anchors.centerIn: Overlay.overlay
}

为了确保弹出窗口位于封闭窗口的边界内，可以将 margins 属性设置为非负值。

Popup Transitions

自 Qt 5.15.3 起，退出转换完成后，以下属性将恢复为进入转换之前的原始值。

• opacity
• scale

这允许内置样式对这些属性进行动画处理，而不会丢失任何显式定义的值。

另请参见 Popup Controls 、 Customizing Popup 和 ApplicationWindow 。

Property Documentation

[只读] activeFocus： bool

该属性保存弹出窗口是否具有活动焦点。

另请参见 focus 和 Keyboard Focus in Qt Quick 。

[自 QtQuick.Controls 2.5 (Qt 5.12) 起]anchors.centerIn ：对象

锚点提供了一种通过指定项目与其他项目的关系来定位项目的方法。

一个常见的用例是将弹出窗口置于其父窗口的中心。实现此目的的一种方法是使用 x 和 y 属性。锚点提供了一种更方便的方法：

Pane {
    // ...
    Popup {
        anchors.centerIn: parent
}

还可以使用 Overlay 将弹出窗口置于窗口中央：

ApplicationWindow {
    id: window
    // ...
    Pane {
        // ...
        Popup {
            anchors.centerIn: Overlay.overlay
}

这使得可以轻松地将任何组件的弹出窗口置于窗口的中心。

注意：弹出窗口只能在其直接父级或窗口覆盖层中居中；尝试将注意力集中在其他项目上将会产生警告。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 Popup Positioning 、 anchors 和 Using Qt Quick Controls types in property declarations 。

[只读]可用高度： real

此属性保存从弹出窗口的 height 中扣除垂直填充后 contentItem 可用的高度。

另请参见 padding 、 topPadding 和 bottomPadding 。

[只读]可用宽度： real

该属性保存从弹出窗口的 width 中扣除水平填充后 contentItem 可用的宽度。

另请参见 padding 、 leftPadding 和 rightPadding 。

背景： Item

该属性保存背景项。

注意：如果背景项没有指定明确的大小，它将自动遵循弹出窗口的大小。在大多数情况下，不需要指定背景项目的宽度或高度。

注意：大多数弹出窗口使用背景项的隐式大小来计算弹出窗口本身的隐式大小。如果您将背景项替换为自定义项，您还应该考虑为其提供合理的隐式尺寸（除非它是像 Image 这样具有自己隐式尺寸的项）。

另请参见 Customizing Popup 。

[自 QtQuick.Controls 2.5 (Qt 5.12) 起] 底部插入： real

该属性保存背景的底部插图。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 Popup Layout 和 topInset 。

底部边距： real

该属性保存弹出窗口的底部边缘与其窗口的底部边缘之间的距离。

具有负底部边距的弹出窗口不会被推入封闭窗口的底部边缘内。默认值为 -1 。

另请参见 margins 、 topMargin 和 Popup Layout 。

底部填充： real

该属性保存底部填充。除非明确设置，否则该值等于 verticalPadding 。

填充属性用于控制 content item 的几何形状。

Popup 使用与 Control 相同的填充方法。有关填充系统的直观说明，请参阅文档的 Control Layout 部分。

另请参见 padding 、 topPadding 、 verticalPadding 和 availableHeight 。

夹子： bool

该属性保存是否启用剪辑。默认值为 false 。

关闭策略： enumeration

该属性决定了弹出窗口关闭的情况。可以组合这些标志以允许多种方式关闭弹出窗口。

可用值为：

Constant	Description	Popup.NoAutoClose	仅当手动指示关闭时，弹出窗口才会关闭。	Popup.CloseOnPressOutside	当鼠标在弹出窗口外按下时，弹出窗口将关闭。	Popup.CloseOnPressOutsideParent	当鼠标在其父级之外按下时，弹出窗口将关闭。	Popup.CloseOnReleaseOutside	当鼠标在弹出窗口之外释放时，弹出窗口将关闭。	Popup.CloseOnReleaseOutsideParent	当鼠标从其父级之外释放时，弹出窗口将关闭。	Popup.CloseOnEscape	当弹出窗口具有活动焦点时按下退出键，弹出窗口将关闭。

默认值为 Popup.CloseOnEscape | Popup.CloseOnPressOutside 。此默认值可能会干扰使用该功能的应用程序中的现有快捷方式 Escape key.

注意：存在一个已知限制，即 Popup.CloseOnReleaseOutside 和 Popup.CloseOnReleaseOutsideParent 策略仅适用于 modal 弹出窗口。

内容儿童： list < Item >

该属性保存内容子项的列表。

该列表包含已在 QML 中声明为弹出窗口子项的所有项目。

注意：与 contentData 不同， contentChildren 不包含非可视 QML 对象。

另请参见 Item::children 和 contentData 。

[默认] contentData : list <对象>

该属性保存内容数据的列表。

该列表包含已在 QML 中声明为弹出窗口子级的所有对象。

注意：与 contentChildren 不同， contentData 包含非可视 QML 对象。

另请参见 Item::data 和 contentChildren 。

内容高度： real

该属性保存内容高度。它用于计算 Popup 的总隐式高度。

有关详细信息，请参阅 Popup Sizing 。

另请参见 contentWidth 。

内容项目 : Item

该属性保存弹出窗口的内容项。

内容项是弹出窗口的视觉实现。当弹出窗口可见时，内容项会自动重新设置为 overlay item 的父级。

注意：内容项会自动调整大小以适合弹出窗口的 padding 。

注意：大多数弹出窗口使用内容项的隐式大小来计算弹出窗口本身的隐式大小。如果将内容项替换为自定义项，您还应该考虑为其提供合理的隐式大小（除非它是像 Text 这样具有自己的隐式大小的项）。

另请参见 Customizing Popup 。

内容宽度： real

该属性保存内容宽度。它用于计算 Popup 的总隐式宽度。

有关详细信息，请参阅 Popup Sizing 。

另请参见 contentHeight 。

暗淡： bool

该属性保存弹出窗口是否使背景变暗。

除非明确设置，否则此属性遵循 modal 的值。要返回默认值，请将此属性设置为 undefined 。

另请参见 modal 和 Overlay.modeless 。

[自 QtQuick.Controls 2.3 (Qt 5.10) 起] 启用： bool

该属性保存是否启用弹出窗口。默认值为 true 。

该属性是在 QtQuick.Controls 2.3 (Qt 5.10) 中引入的。

另请参见 visible 和 Item::enabled 。

输入： Transition

该属性保存当弹出窗口打开并进入屏幕时应用于弹出项目的转换。

以下示例为弹出窗口进入屏幕时的不透明度设置动画：

Popup {
    enter: Transition {
        NumberAnimation { property: "opacity"; from: 0.0; to: 1.0 }
}

另请参见 exit 。

出口： Transition

该属性保存弹出窗口关闭并退出屏幕时应用于弹出项目的过渡。

以下示例为弹出窗口退出屏幕时的不透明度设置动画：

Popup {
    exit: Transition {
        NumberAnimation { property: "opacity"; from: 1.0; to: 0.0 }
}

另请参见 enter 。

焦点： bool

该属性保存弹出窗口是否需要焦点。

当弹出窗口实际获得焦点时， activeFocus 将是 true 。有关详细信息，请参阅 Keyboard Focus in Qt Quick 。

默认值为 false 。

另请参见 activeFocus 。

字体： font

该属性保存当前为弹出窗口设置的字体。

弹出窗口将显式字体属性传播给其子窗口。如果您更改弹出窗口字体的特定属性，该属性将传播到弹出窗口的所有子项，从而覆盖该属性的任何系统默认值。

Popup {
    font.family: "Courier"
    Column {
        Label {
            text: qsTr("This will use Courier...")
        Switch {
            text: qsTr("... and so will this")
}

另请参见 Control::font 和 ApplicationWindow::font 。

高度： real

该属性保存弹出窗口的高度。

[自 QtQuick.Controls 2.5 (Qt 5.12) 起] 水平填充： real

该属性保存水平填充。除非明确设置，否则该值等于 padding 。

填充属性用于控制 content item 的几何形状。

Popup 使用与 Control 相同的填充方法。有关填充系统的直观说明，请参阅文档的 Control Layout 部分。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 padding 、 leftPadding 、 rightPadding 和 verticalPadding 。

[只读，自 QtQuick.Controls 2.5 (Qt 5.12) 起]隐式背景高度： real

该属性保存隐式背景高度。

该值等于 background ? background.implicitHeight : 0 。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 implicitBackgroundWidth 和 implicitContentHeight 。

[只读，自 QtQuick.Controls 2.5 (Qt 5.12) 起]隐式背景宽度： real

该属性保存隐式背景宽度。

该值等于 background ? background.implicitWidth : 0 。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 implicitBackgroundHeight 和 implicitContentWidth 。

[只读，自 QtQuick.Controls 2.5 (Qt 5.12) 起]implicitContentHeight : real

该属性保存隐式内容高度。

该值是根据内容子项计算的。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 implicitContentWidth 和 implicitBackgroundHeight 。

[只读，自 QtQuick.Controls 2.5 (Qt 5.12) 起]隐式内容宽度： real

该属性保存隐式内容宽度。

该值是根据内容子项计算的。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 implicitContentHeight 和 implicitBackgroundWidth 。

隐式高度： real

该属性保存弹出窗口的隐式高度。

隐式宽度： real

该属性保存弹出窗口的隐式宽度。

[自 QtQuick.Controls 2.5 (Qt 5.12) 起] leftInset： real

该属性保存背景的左侧插图。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 Popup Layout 和 rightInset 。

左边距： real

该属性保存弹出窗口的左边缘与其窗口左边缘之间的距离。

左边距为负的弹出窗口不会被推入封闭窗口的左边缘内。默认值为 -1 。

另请参见 margins 、 rightMargin 和 Popup Layout 。

左填充： real

该属性保存左填充。除非明确设置，否则该值等于 horizontalPadding 。

填充属性用于控制 content item 的几何形状。

Popup 使用与 Control 相同的填充方法。有关填充系统的直观说明，请参阅文档的 Control Layout 部分。

另请参见 padding 、 rightPadding 、 horizontalPadding 和 availableWidth 。

区域设置： Locale

该属性保存弹出窗口的区域设置。

另请参见 mirrored 和 LayoutMirroring 。

边距： real

该属性保存弹出窗口边缘与其窗口边缘之间的距离。

具有负边距的弹出窗口不会被推入封闭窗口的边界内。默认值为 -1 。

另请参见 topMargin 、 leftMargin 、 rightMargin 、 bottomMargin 和 Popup Layout 。

[只读，自 QtQuick.Controls 2.3 (Qt 5.10) 起] 镜像： bool

该属性保存弹出窗口是否镜像。

提供此属性是为了方便。当弹出窗口的视觉布局方向为从右到左时，该弹出窗口被视为镜像；也就是说，当使用从右到左的语言环境时。

该属性是在 QtQuick.Controls 2.3 (Qt 5.10) 中引入的。

另请参见 locale 和 Right-to-left User Interfaces 。

模态 : bool

该属性保存弹出窗口是否是模态的。

模态弹出窗口通常具有 Overlay.modal 中定义的独特背景变暗效果，并且不允许按下或释放事件到达其下方的项目。例如，如果用户意外单击弹出窗口外部，则单击位置处该弹出窗口下方的任何项目都不会收到该事件。

在桌面平台上，通常只有在按下退出键时才会关闭模式弹出窗口。要实现此行为，请将 closePolicy 设置为 Popup.CloseOnEscape 。默认情况下， closePolicy 设置为 Popup.CloseOnEscape | Popup.CloseOnPressOutside ，这意味着单击模式弹出窗口外部将关闭它。

默认值为 false 。

另请参见 dim 。

不透明度： real

该属性保存弹出窗口的不透明度。不透明度指定为 0.0 （完全透明）和 1.0 （完全不透明）之间的数字。默认值为 1.0 。

另请参见 visible 。

[自 QtQuick.Controls 2.3 (Qt 5.10)] 打开： bool

该属性保存弹出窗口是否完全打开。当弹出窗口可见且 enter 和 exit 转换均未运行时，该弹出窗口被视为已打开。

该属性是在 QtQuick.Controls 2.3 (Qt 5.10) 中引入的。

另请参见 open ()、 close () 和 visible 。

填充物： real

该属性保存默认的填充。

填充属性用于控制 content item 的几何形状。

Popup 使用与 Control 相同的填充方法。有关填充系统的直观说明，请参阅文档的 Control Layout 部分。

另请参见 availableWidth 、 availableHeight 、 topPadding 、 leftPadding 、 rightPadding 和 bottomPadding 。

[自 QtQuick.Controls 2.3 (Qt 5.10) 起] 调色板 : 调色板

该属性保存当前为弹出窗口设置的调色板。

弹出窗口将显式调色板属性传播给其子项。如果您更改弹出窗口调色板上的特定属性，该属性将传播到弹出窗口的所有子级，从而覆盖该属性的任何系统默认值。

Popup {
    palette.text: "red"
    Column {
        Label {
            text: qsTr("This will use red color...")
        Switch {
            text: qsTr("... and so will this")
}

该属性是在 QtQuick.Controls 2.3 (Qt 5.10) 中引入的。

另请参见 Item::palette 、 Window::palette 、 ColorGroup 和 Palette 。

父级： Item

该属性保存父项。

[自 QtQuick.Controls 2.5 (Qt 5.12) 起] rightInset： real

该属性保留背景的正确插图。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 Popup Layout 和 leftInset 。

右边距： real

该属性保存弹出窗口的右边缘与其窗口的右边缘之间的距离。

右边距为负的弹出窗口不会被推入封闭窗口的右边缘内。默认值为 -1 。

另请参见 margins 、 leftMargin 和 Popup Layout 。

右填充： real

该属性拥有正确的填充。除非明确设置，否则该值等于 horizontalPadding 。

填充属性用于控制 content item 的几何形状。

Popup 使用与 Control 相同的填充方法。有关填充系统的直观说明，请参阅文档的 Control Layout 部分。

另请参见 padding 、 leftPadding 、 horizontalPadding 和 availableWidth 。

秤： real

该属性保存弹出窗口的比例因子。默认值为 1.0 。

小于 1.0 的比例会导致弹出窗口以较小的尺寸呈现，而大于 1.0 的比例会以较大的尺寸呈现弹出窗口。不支持负比例。

[自 QtQuick.Controls 2.1 (Qt 5.8) 起] 间距： real

该属性保留间距。

间距对于具有多个或重复构建块的弹出窗口很有用。例如，某些样式使用间距来确定 Dialog 的页眉、内容和页脚之间的距离。间距不是由 Popup 强制执行的，因此每种样式可能会以不同的方式解释它，有些可能会完全忽略它。

该属性是在 QtQuick.Controls 2.1 (Qt 5.8) 中引入的。

[自 QtQuick.Controls 2.5 (Qt 5.12) 起] topInset： real

该属性保存背景的顶部插图。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 Popup Layout 和 bottomInset 。

顶部边距： real

该属性保存弹出窗口的上边缘与其窗口的上边缘之间的距离。

具有负上边距的弹出窗口不会被推入封闭窗口的上边缘内。默认值为 -1 。

另请参见 margins 、 bottomMargin 和 Popup Layout 。

顶部填充： real

该属性保存顶部填充。除非明确设置，否则该值等于 verticalPadding 。

填充属性用于控制 content item 的几何形状。

Popup 使用与 Control 相同的填充方法。有关填充系统的直观说明，请参阅文档的 Control Layout 部分。

另请参见 padding 、 bottomPadding 、 verticalPadding 和 availableHeight 。

变换来源： enumeration

该属性保存进入和退出转换中转换的原点。

有九个变换原点可用，如下图所示。默认变换原点是 Popup.Center 。

另请参见 enter 、 exit 和 Item::transformOrigin 。

[自 QtQuick.Controls 2.5 (Qt 5.12) 起] 垂直填充： real

该属性保存垂直填充。除非明确设置，否则该值等于 padding 。

填充属性用于控制 content item 的几何形状。

Popup 使用与 Control 相同的填充方法。有关填充系统的直观说明，请参阅文档的 Control Layout 部分。

该属性是在 QtQuick.Controls 2.5 (Qt 5.12) 中引入的。

另请参见 padding 、 topPadding 、 bottomPadding 和 horizontalPadding 。

可见： bool

该属性保存弹出窗口是否可见。默认值为 false 。

另请参见 open ()、 close () 和 opened 。

宽度： real

该属性保存弹出窗口的宽度。

x： real

该属性保存弹出窗口的 x 坐标。

另请参见 y 和 z 。

y： real

该属性保存弹出窗口的 y 坐标。

另请参见 x 和 z 。

: real

该属性保存弹出窗口的 z 值。Z 值决定弹出窗口的堆叠顺序。

如果两个可见的弹出窗口具有相同的 z 值，则最后一个打开的弹出窗口将位于顶部。

默认 z 值为 0 。

另请参见 x 和 y 。

Signal Documentation

voidaboutToHide()

当弹出窗口即将隐藏时会发出此信号。

注：对应的处理程序为 onAboutToHide 。

另请参见 closed ()。

voidaboutToShow()

当弹出窗口即将显示时会发出此信号。

注：对应的处理程序为 onAboutToShow 。

另请参见 opened ()。

voidclosed()

当弹出窗口关闭时会发出此信号。

注：对应的处理程序为 onClosed 。

另请参见 aboutToHide ()。

voidopened()

当弹出窗口打开时会发出此信号。

注：对应的处理程序为 onOpened 。

另请参见 aboutToShow ()。

Method Documentation

voidclose()

关闭弹出窗口。

另请参见 visible 。

forceActiveFocus( enumeration reason = Qt.OtherFocusReason)

强制主动关注给定的弹出窗口 reason .

此方法将焦点设置在弹出窗口上，并确保对象层次结构中的所有祖先 FocusScope 对象也被赋予 focus 。

另请参见 activeFocus 和 Qt::FocusReason 。

voidopen()

打开弹出窗口。

另请参见 visible 。

© Qt 有限公司
根据 GNU 自由文档许可证版本 1.3 获得许可。
https://doc.qt.io/qt-6.2/qml-qtquick-controls2-popup.html