Popup QML Type

弹出式用户界面控件的基本类型。更多

Import Statement:	`import QtQuick.Controls`
Inherits:	QtObject
Inherited By:	Dialog, Drawer, Menu, and ToolTip

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

属性

activeFocus : bool
anchors.centerIn : Item (since QtQuick.Controls 2.5 (Qt 5.12))
availableHeight : real
availableWidth : real
background : Item
bottomInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
bottomMargin : real
bottomPadding : real
clip : bool
closePolicy : enumeration
contentChildren : list<Item>
contentData : list<QtObject>
contentHeight : real
contentItem : Item
contentWidth : real
dim : bool
enabled : bool (since QtQuick.Controls 2.3 (Qt 5.10))
enter : Transition
exit : Transition
focus : bool
font : font
height : real
horizontalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitBackgroundHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitBackgroundWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitContentHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitContentWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
implicitHeight : real
implicitWidth : real
leftInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
leftMargin : real
leftPadding : real
locale : Locale
margins : real
mirrored : bool (since QtQuick.Controls 2.3 (Qt 5.10))
modal : bool
opacity : real
opened : bool (since QtQuick.Controls 2.3 (Qt 5.10))
padding : real
palette : palette (since QtQuick.Controls 2.3 (Qt 5.10))
parent : Item
popupType : enumeration (since 6.8)
rightInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
rightMargin : real
rightPadding : real
scale : real
spacing : real (since QtQuick.Controls 2.1 (Qt 5.8))
topInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
topMargin : real
topPadding : real
transformOrigin : enumeration
verticalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
visible : bool
width : real
x : real
y : real
z : real

信号

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

方法

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

详细说明

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

import QtQuick.Window
import QtQuick.Controls

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

Popup 本身不提供布局，但需要您对其内容进行定位，例如通过创建RowLayout 或ColumnLayout 。

声明为弹出式窗口子窗口的项目会自动成为弹出式窗口contentItem 的父窗口。动态创建的项目需要明确地与contentItem 关联。

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

覆盖内容的弹出窗口

弹出窗口的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"
    }
}

自 Qt 6.8 起，一些弹出窗口（如Menu ）根据平台的不同提供了三种不同的实现方式。您可以通过设置popupType 来选择您喜欢的类型。

Popup.Item 支持所有平台，但Popup.Window 和Popup.Native 通常只支持桌面平台。此外，如果弹出窗口是Menu 内的native menubar ，菜单也将是本地的。如果菜单是另一个菜单中的子菜单，则由父（或根）菜单决定类型。

如果将popupType 设置为Popup.Item ，弹出窗口将不会作为单独窗口显示，而是作为与父窗口相同场景中的一个项目显示。此项目的父对象是该场景的overlay ，样式看起来像一个真正的窗口。

在不支持多窗口的平台上，该选项尤其有用。这也是 Qt 6.8 之前的唯一选项。

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

通过将popupType 设置为Popup.Window ，弹出窗口将显示在使用Qt::Popup 标志配置的顶层window 内。使用窗口显示弹出窗口的好处是，弹出窗口将浮动在父窗口的顶部，可以放置在其几何形状之外。除此之外，弹出窗口的外观与使用Popup.Item 时相同，也就是说，它将使用与使用Popup.Item 时相同的 QML 委托和样式。

注：如果平台不支持Popup.Window ，则将使用Popup.Item 作为后备。

通过将popupType 设置为Popup.Native ，弹出窗口将使用平台本地弹出窗口显示。该窗口及其所有内容将由平台而非 QML 渲染。这意味着分配给弹出窗口的 QML 委托不会用于渲染。例如，如果在Menu 上使用该选项，它将使用平台特定的菜单 API 实现。这通常会使弹出式菜单的外观和感觉比Popup.Window 等平台更原生，但同时也会受到平台限制以及与外观和行为相关的差异的影响。这些限制在受影响的子类（如Menu ）中有更详细的说明。

注：如果平台不支持Popup.Native ，则将使用Popup.Window 作为后备。

如果在弹出式窗口中只使用了一个项目，它将调整大小以适应其所包含项目的隐式大小。这使其特别适合与布局一起使用。

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 items 时，弹出窗口的content item 会被父代到overlay ，而不会位于弹出窗口的父代中。因此，应用于弹出窗口所在树的scale 并不适用于可视弹出窗口。如要使ComboBox 的弹出窗口与组合框的比例一致，则也要对overlay 应用相同的比例：

Window {
    property double scaleFactor: 2.0

    Scale {
        id: scale
        xScale: scaleFactor
        yScale: scaleFactor
    }
    Item {
        id: scaledContent
        transform: scale

        ComboBox {
            id: combobox
            // ...
        }
    }

    Overlay.overlay.transform: scale
}

与Qt Quick 中的项目类似，弹出窗口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 windows 的情况下，弹出窗口会将其contentItem 的视觉父级设置为窗口的overlay ，以确保弹出窗口显示在场景中其他所有内容的前面。它的主要任务是拦截事件，防止向modal 弹出窗口下的项目发送信息，并根据closePolicy 关闭弹出窗口。

在某些情况下，将一个项目放在弹出窗口的前面可能会很有用，例如virtual keyboard 。目前只能通过将项目的父级设置为覆盖，并确保项目堆叠在任何弹出窗口项目之前（z 的正值可确保这一点）来实现。

一般不建议以这种方式使用覆盖层，因为覆盖层不是为此目的而设计的，而且在更改popupType 时行为也不会一致。

Popup {
    id: popup
    visible: true
    anchors.centerIn: parent
    margins: 10
    closePolicy: Popup.CloseOnEscape
    ColumnLayout {
        TextField {
            placeholderText: qsTr("Username")
        }
        TextField {
            placeholderText: qsTr("Password")
            echoMode: TextInput.Password
        }
    }
}
InputPanel {
    parent: Overlay.overlay
    width: parent.width
    y: popup.y + popup.topMargin + (window.activeFocusItem?.y ?? 0) + (window.activeFocusItem?.height ?? 0)
    z: 1
}

在退出过渡完成后，这些属性将重置为进入过渡开始前的值。

这样，内置样式就可以在这些属性上制作动画，而不会丢失任何明确定义的值。

返回/退出事件处理

默认情况下，如果出现以下情况，弹出窗口将关闭：

它有activeFocus 、
它的closePolicy 是Popup.CloseOnEscape ，并且
用户按下QKeySequence::Cancel 的按键序列（通常是 Escape 键）

要防止这种情况发生，可以

不给弹出窗口focus 。
将弹出窗口的closePolicy 设置为不包括Popup.CloseOnEscape 的值。
在弹出窗口的子项目中处理Keys'escapePressed 信号，使其在弹出窗口之前收到事件。

属性传播

弹出窗口通过其父窗口而非对象或可视化父窗口继承字体、调色板和附加属性：

import QtQuick.Controls.Basic

ApplicationWindow {
    width: 500
    height: 500
    visible: true
    font.pixelSize: 20
    palette.windowText: "steelblue"

    // This will have a pixelSize of 20 and be "steelblue" in color.
    header: Label {
        text: "ApplicationWindow Label"
        leftPadding: 20
        topPadding: 20
    }

    Pane {
        width: 400
        height: 400
        anchors.centerIn: parent
        palette.window: "#edf3f8"
        palette.windowText: "tomato"

        // This will have a pixelSize of 20 and be "tomato" in color.
        Label {
            text: "Pane Label"
        }

        Popup {
            width: 300
            height: 300
            anchors.centerIn: parent
            font.pixelSize: 10
            visible: true

            // This will have a pixelSize of 10 and "steelblue" in color.
            Label {
                text: "Popup Label"
            }

            Popup {
                width: 200
                height: 200
                anchors.centerIn: parent
                visible: true

                // This will have a pixelSize of 20 and be "steelblue" in color.
                Label {
                    text: "Child Popup Label"
                }
            }
        }
    }
}

弹出式属性继承示意图

此外，弹出窗口不会将其属性传播给子弹出窗口。这种行为以Qt Widgets 为模型，其中Qt::Popup widget 是顶层窗口。顶层窗口不会将其属性传播给子窗口。

某些派生类型（如ComboBox ）的典型实现方式是将弹出窗口视为控件不可分割的一部分，因此可以继承附加属性等内容。例如，在Material 样式 ComboBox 中，弹出窗口从ComboBox 本身明确继承了主题和其他附加属性：

popup: T.Popup {
    // ...

    Material.theme: control.Material.theme
    Material.accent: control.Material.accent
    Material.primary: control.Material.primary
}

因此，要确保子弹出窗口具有与其父弹出窗口相同的属性值，请明确设置这些属性：

Popup {
    id: parentPopup
    // ...

    Popup {
        palette: parentPopup.palette
    }
}

波兰语关闭弹出窗口的行为

当弹出窗口关闭时，它没有相关窗口，其子项也没有相关窗口。这意味着在弹出窗口显示之前，任何子项目都不会被polished 。因此，您不能依靠关闭的Popup 中的ListView 来更新其count 属性：

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    SomeModel {
        id: someModel
    }

    Button {
        text: view.count
        onClicked: popup.open()
    }

    Popup {
        id: popup
        width: 400
        height: 400
        contentItem: ListView {
            id: view
            model: someModel
            delegate: Label {
                text: display

                required property string display
            }
        }
    }
}

在上面的示例中，当弹出窗口关闭时，在component completion 之后向someModel 添加或删除行时，按钮的文本将不会更新。

相反，可以在SomeModel 中添加一个count 属性，每当rowsInserted 、rowsRemoved 和modelReset 信号发出时，该属性就会更新。然后，Button 可将此属性绑定到其text 。

另请参阅 弹出窗口控件、自定义弹出窗口和ApplicationWindow 。

属性文档

activeFocus : bool `[read-only]`

该属性表示弹出窗口是否有活动焦点。

另请参阅 focus 和 Qt Quick 中的键盘焦点。

anchors.centerIn : Item `[since QtQuick.Controls 2.5 (Qt 5.12)]`

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

一个常见的用例是将弹出窗口置于其父级窗口的中心。一种方法是使用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.

availableHeight : real `[read-only]`

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

另请参阅 padding,topPadding, 和bottomPadding 。

availableWidth : real `[read-only]`

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

另请参阅 padding,leftPadding, 和rightPadding 。

background : Item

该属性用于保存背景项。

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

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

另请参阅 自定义弹出窗口。

bottomInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

该属性用于保存背景的底部嵌入。

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

另请参阅 Popup Layout 和topInset 。

bottomMargin : real

该属性表示弹出窗口的底边与其窗口底边之间的距离。

底部边距为负值的弹出窗口不会被推到包围窗口的底部边缘内。默认值为-1 。

另请参阅 margins,topMargin, 和Popup Layout 。

bottomPadding : real

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

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

弹出窗口使用与Control 相同的填充方法。有关 padding 系统的可视化说明，请参阅文档的Control Layout 部分。

另请参阅 padding,topPadding,verticalPadding 和availableHeight 。

clip : bool

此属性表示是否启用剪切。默认值为false 。只有当弹出窗口不在自己的窗口中时，剪切才会起作用。

closePolicy : enumeration

该属性决定弹出窗口在何种情况下关闭。标志可以组合使用，以实现多种关闭弹出窗口的方式。

可用的值有

常量	说明
`Popup.NoAutoClose`	弹出窗口只有在收到手动关闭指示时才会关闭。
`Popup.CloseOnPressOutside`	当鼠标在弹出窗口外按下时，弹出窗口将关闭。
`Popup.CloseOnPressOutsideParent`	当鼠标被按到父级之外时，弹出窗口将关闭。
`Popup.CloseOnReleaseOutside`	在弹出窗口外释放鼠标时，弹出窗口将关闭。
`Popup.CloseOnReleaseOutsideParent`	当鼠标从父窗口外释放时，弹出窗口将关闭。
`Popup.CloseOnEscape`	在弹出窗口有活动焦点时按下 Escap 键，弹出窗口将关闭。

CloseOnPress* 和CloseOnRelease* 策略仅适用于弹出窗口之外的事件。也就是说，如果打开了两个弹出窗口，且第一个弹出窗口的策略为Popup.CloseOnPressOutside ，则点击第二个弹出窗口不会导致第一个弹出窗口关闭。

默认值为Popup.CloseOnEscape | Popup.CloseOnPressOutside 。

注意： 已知的限制是Popup.CloseOnReleaseOutside 和Popup.CloseOnReleaseOutsideParent 策略仅适用于modal 弹出窗口。

contentChildren : list<Item>

该属性包含内容子项列表。

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

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

另请参阅 Item::children 和contentData 。

contentData : list<QtObject> `[default]`

该属性包含内容数据列表。

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

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

另请参阅 Item::data 和contentChildren 。

contentHeight : real

该属性包含内容高度。它用于计算弹出窗口的总隐含高度。

更多信息，请参见Popup Sizing 。

另请参见 contentWidth 。

contentItem : Item

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

内容项是弹出窗口的可视化实现。当弹出窗口可见时，内容项会自动被重新分配到overlay item 。

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

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

另请参阅 自定义弹出窗口。

contentWidth : real

该属性用于保存内容宽度。它用于计算弹出窗口的总隐含宽度。

更多信息，请参见Popup Sizing 。

另请参见 contentHeight 。

dim : bool

该属性表示弹出窗口是否调暗背景。

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

另请参阅 modal 和Overlay.modeless 。

enabled : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

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

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

另请参阅 visible 和Item::enabled 。

enter : Transition

该属性用于保存弹出项打开并进入屏幕时的过渡效果。

下面的示例将在弹出窗口进入屏幕时对其不透明度进行动画处理：

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

另请参阅 exit 。

exit : Transition

该属性用于保存弹出项关闭并退出屏幕时的过渡效果。

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

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

另请参阅 enter 。

focus : bool

该属性表示弹出窗口是否需要焦点。

当弹出窗口实际收到焦点时，activeFocus ，true 。更多信息，请参阅 Qt Quick 中的 "键盘焦点"。

默认值为false 。

另请参阅 activeFocus 。

font : font

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

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

Popup {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

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

height : real

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

horizontalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

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

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

弹出窗口使用与Control 相同的填充方法。有关 padding 系统的可视化解释，请参阅文档的Control Layout 部分。

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

另请参阅 padding,leftPadding,rightPadding, 和verticalPadding 。

implicitBackgroundHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

该属性包含隐式背景高度。

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

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

另请参阅 implicitBackgroundWidth 和implicitContentHeight 。

implicitBackgroundWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

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

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

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

另请参阅 implicitBackgroundHeight 和implicitContentWidth 。

implicitContentHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

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

该值根据内容子代计算得出。

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

另请参阅 implicitContentWidth 和implicitBackgroundHeight 。

implicitContentWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

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

该值根据内容子代计算得出。

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

另请参阅 implicitContentHeight 和implicitBackgroundWidth 。

implicitHeight : real

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

implicitWidth : real

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

leftInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

该属性用于保存背景的左侧嵌入。

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

另请参阅 Popup Layout 和rightInset 。

leftMargin : real

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

左边缘为负值的弹出窗口不会被推到包围窗口的左边缘内。默认值为-1 。

另请参阅 margins,rightMargin, 和Popup Layout 。

leftPadding : real

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

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

弹出窗口使用与Control 相同的填充方法。有关 padding 系统的可视化说明，请参阅文档的Control Layout 部分。

另请参阅 padding,rightPadding,horizontalPadding 和availableWidth 。

locale : Locale

该属性用于保存弹出窗口的位置信息。

另请参阅 mirrored 和LayoutMirroring 。

margins : real

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

具有负边距的弹出窗口不会被推到包围窗口的范围内。默认值为-1 。

另请参阅 topMargin,leftMargin,rightMargin,bottomMargin 和Popup Layout 。

mirrored : bool `[read-only, since QtQuick.Controls 2.3 (Qt 5.10)]`

该属性表示弹出窗口是否镜像。

提供该属性是为了方便。当弹出窗口的视觉布局方向是从右到左时，即使用从右到左的定位时，弹出窗口被认为是镜像的。

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

另请参阅 locale 和从右向左的用户界面。

该属性用于确定弹出窗口是否为模式弹出窗口。

模态弹出窗口通常具有独特的背景调光效果（定义于Overlay.modal ），并且不允许将按下或释放事件传递到弹出窗口下方的项目。例如，如果用户不小心点击了弹出窗口之外的位置，弹出窗口之下位于点击位置的任何项目都不会收到事件。

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

默认值为false 。

另请参见 dim 。

opacity : real

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

另请参阅 visible 。

opened : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

该属性表示弹出窗口是否完全打开。当弹出窗口可见且enter 或exit 过渡都未运行时，弹出窗口被视为已打开。

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

另请参阅 open(),close() 和visible 。

padding : real

该属性包含默认的 padding。

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

弹出窗口使用与Control 相同的填充方法。有关 padding 系统的可视化说明，请参阅文档的Control Layout 部分。

另请参阅 availableWidth,availableHeight,topPadding,leftPadding,rightPadding 和bottomPadding 。

palette : palette `[since 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")
        }
    }
}

另请参阅：Item::palette,Window::palette,ColorGroup 、Palette

此属性在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

parent : Item

该属性包含父项目。

popupType : enumeration `[since 6.8]`

该属性决定首选的弹出窗口类型。

可用选项

常量	说明
`Item`	弹出窗口将嵌入same scene as the parent ，不使用单独窗口。
`Window`	弹出窗口将在separate window 中显示。如果平台不支持多窗口，则将使用`Popup.Item` 代替。
`Native`	弹出窗口将是平台的本地窗口。如果平台不支持本地弹出窗口，则将使用`Popup.Window` 代替。

默认值通常是Popup.Item ，但也有上述例外情况。这可能会在未来的 Qt 版本中发生变化，因为某些样式和平台会从使用其他弹出式菜单类型中受益。例如，如果您总是想在 macOS 上的所有样式中使用本地菜单，您就可以这样做：

Menu {
    popupType: Qt.platform.os === "osx" ? Popup.Native : Popup.Window
}

此外，如果您选择自定义弹出窗口（例如更改任何委托），则应考虑将弹出窗口类型也设置为Popup.Window 。这将确保您的更改在所有平台和所有样式上都是可见的。否则，在使用本地菜单时，将不会使用委托进行呈现。

此属性在 Qt 6.8 中引入。

另请参见 Popup type 。

rightInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

该属性用于保存背景的右侧嵌入。

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

另请参阅 Popup Layout 和leftInset 。

rightMargin : real

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

右边距为负值的弹出窗口不会被推到包围窗口的右边缘内。默认值为-1 。

另请参阅 margins,leftMargin, 和Popup Layout 。

rightPadding : real

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

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

弹出窗口使用与Control 相同的填充方法。有关 padding 系统的可视化说明，请参阅文档的Control Layout 部分。

另请参阅 padding,leftPadding,horizontalPadding 和availableWidth 。

scale : real

该属性用于设置弹出窗口的比例因子。默认值为1.0 。

缩放比例小于1.0 时，弹出窗口的尺寸会变小；缩放比例大于1.0 时，弹出窗口的尺寸会变大。不支持负缩放。

spacing : real `[since QtQuick.Controls 2.1 (Qt 5.8)]`

该属性保留间距。

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

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

topInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

该属性用于保存背景的顶部嵌入。

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

另请参阅 Popup Layout 和bottomInset 。

topMargin : real

该属性表示弹出窗口顶边与其窗口顶边之间的距离。

顶部边距为负值的弹出窗口不会被推到包围窗口的顶部边缘内。默认值为-1 。

另请参阅 margins,bottomMargin, 和Popup Layout 。

topPadding : real

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

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

弹出窗口使用与Control 相同的填充方法。有关 padding 系统的可视化说明，请参阅文档的Control Layout 部分。

另请参阅 padding,bottomPadding,verticalPadding 和availableHeight 。

transformOrigin : enumeration

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

如下图所示，有九种变换原点可供选择。默认的变换原点是Popup.Center 。

弹出窗口显示变换原点

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

verticalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

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

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

弹出窗口使用与Control 相同的填充方法。有关 padding 系统的可视化解释，请参阅文档的Control Layout 部分。

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

另请参阅 padding,topPadding,bottomPadding, 和horizontalPadding 。

visible : bool

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

另请参阅 open(),close() 和opened 。

width : real

该属性表示弹出窗口的宽度。

x : real

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

另请参阅 y 和z 。

y : real

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

另请参阅 x 和z 。

z : real

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

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

如果一个弹出窗口在打开时没有明确设置 z 值，并且是一个已打开弹出窗口的子窗口，那么它将被堆叠在父窗口的顶部。这样可以确保子窗口不会隐藏在父窗口之下。

如果弹出窗口有自己的窗口，z 值将决定窗口的堆叠顺序。

默认 z 值为0 。

另请参阅 x 和y 。

信号文档

void aboutToHide()

该信号在弹出窗口即将隐藏时发出。

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

另请参阅 closed() 。

void aboutToShow()

该信号在弹出窗口即将显示时发出。

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

另请参阅 opened() 。

void closed()

该信号在弹出窗口关闭时发出。

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

另请参阅 aboutToHide().

void opened()

该信号在弹出窗口打开时发出。

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

另请参阅 aboutToShow().

方法文档

void close()

关闭弹出窗口。

另请参阅 visible 。

void forceActiveFocus(enumeration reason = Qt.OtherFocusReason)

通过给定的reason ，将焦点激活到弹出窗口上。

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

另请参阅 activeFocus 和Qt::FocusReason 。

void open()

打开弹出窗口。

另请参阅 visible 。

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

Popup QML Type

属性

信号

方法

详细说明

弹出窗口布局

弹出窗口类型

将弹出式菜单显示为一个项目

以单独窗口显示弹出窗口

显示本地弹出窗口

弹出窗口大小

弹出窗口定位

使用覆盖

弹出过渡

返回/退出事件处理

属性传播

波兰语 关闭弹出窗口的行为

属性文档

activeFocus : bool [read-only]

anchors.centerIn : Item [since QtQuick.Controls 2.5 (Qt 5.12)]

availableHeight : real [read-only]

availableWidth : real [read-only]

background : Item

bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

bottomMargin : real

bottomPadding : real

clip : bool

closePolicy : enumeration

contentChildren : list<Item>

contentData : list<QtObject> [default]

contentHeight : real

contentItem : Item

contentWidth : real

dim : bool

enabled : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

enter : Transition

exit : Transition

focus : bool

font : font

height : real

horizontalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

implicitBackgroundHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

implicitBackgroundWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

implicitContentHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

implicitContentWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

implicitHeight : real

implicitWidth : real

leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

leftMargin : real

leftPadding : real

locale : Locale

margins : real

mirrored : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

modal : bool

opacity : real

opened : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

padding : real

palette : palette [since QtQuick.Controls 2.3 (Qt 5.10)]

parent : Item

popupType : enumeration [since 6.8]

rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

rightMargin : real

rightPadding : real

scale : real

spacing : real [since QtQuick.Controls 2.1 (Qt 5.8)]

topInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

topMargin : real

topPadding : real

transformOrigin : enumeration

verticalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

visible : bool

width : real

x : real

y : real

z : real

信号文档

void aboutToHide()

void aboutToShow()

void closed()

void opened()

波兰语关闭弹出窗口的行为

activeFocus : bool `[read-only]`

anchors.centerIn : Item `[since QtQuick.Controls 2.5 (Qt 5.12)]`

availableHeight : real `[read-only]`

availableWidth : real `[read-only]`

bottomInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

contentData : list<QtObject> `[default]`

enabled : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

horizontalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

implicitBackgroundHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

implicitBackgroundWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

implicitContentHeight : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

implicitContentWidth : real `[read-only, since QtQuick.Controls 2.5 (Qt 5.12)]`

leftInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

mirrored : bool `[read-only, since QtQuick.Controls 2.3 (Qt 5.10)]`

opened : bool `[since QtQuick.Controls 2.3 (Qt 5.10)]`

palette : palette `[since QtQuick.Controls 2.3 (Qt 5.10)]`

popupType : enumeration `[since 6.8]`

rightInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

spacing : real `[since QtQuick.Controls 2.1 (Qt 5.8)]`

topInset : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`

verticalPadding : real `[since QtQuick.Controls 2.5 (Qt 5.12)]`