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 来实现。

声明为 Popup 子节点的元素会自动成为 Popup 的contentItem 的子节点。动态创建的元素需要显式地将其父节点设置为contentItem 。

下图展示了弹出窗口在窗口内的布局：

覆盖内容的弹出窗口

弹出窗口的implicitWidth 和implicitHeight 通常基于背景和内容项的隐式尺寸，再加上任何内边距和填充。当未显式指定width 或height 时，这些属性决定了弹出窗口的大小。

contentItem 的几何形状由 padding 决定。以下示例在弹出框边界与其内容之间预留了 10px 的 padding：

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 通常仅在桌面平台上受支持。此外，如果弹出窗口是位于native menubar 中的Menu ，则该菜单也将采用原生形式。如果该菜单是另一个菜单内的子菜单，则由父（或根）菜单决定其类型。

通过将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 的情况下，Popup会将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
}

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

这使得内置样式能够根据这些属性进行动画效果，同时不会丢失任何显式定义的值。

“返回”/“Esc”事件处理

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

其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 控件是顶级窗口。顶级窗口不会将其属性传播给子窗口。

某些派生类型（如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 。

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

Popup 采用与 `Control` 相同的内边距处理方式。有关内边距系统的直观说明，请参阅文档中的“Control Layout ”部分。

另请参阅 padding 、topPadding 、verticalPadding 以及availableHeight 。

clip : bool

该属性控制是否启用裁剪功能。默认值为false 。只有当弹出窗口未位于独立窗口中时，裁剪功能才有效。

closePolicy : enumeration

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

可用值包括：

常量	描述
`Popup.NoAutoClose`	弹出窗口仅在手动操作时才会关闭。
`Popup.CloseOnPressOutside`	当鼠标在弹出窗口外部被点击时，弹出窗口将关闭。
`Popup.CloseOnPressOutsideParent`	当鼠标在其父容器外部被按下时，弹出窗口将关闭。
`Popup.CloseOnReleaseOutside`	当鼠标在弹出窗口外部松开时，弹出窗口将关闭。
`Popup.CloseOnReleaseOutsideParent`	当鼠标在其父容器外部松开时，弹出窗口将关闭。
`Popup.CloseOnEscape`	当弹出窗口处于活动焦点状态时，按下 Esc 键将关闭该弹出窗口。
`Popup.CloseMultiple`	当使用多个嵌套弹出窗口时，默认情况下，每次外部点击只会关闭最顶层的弹出窗口。当要关闭的弹出窗口设置了此标志时，也会检查堆栈中的下一个弹出窗口：如果点击位置也在其外部，则该弹出窗口也会关闭。这种级联会沿堆栈向下继续，直到所有弹出窗口均已关闭、遇到边界包含点击位置的弹出窗口，或者关闭了一个未设置`CloseMultiple` 标志的弹出窗口为止。必须与至少一个`CloseOnPress` 或`CloseOnRelease` 标志结合使用。

默认值为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 。

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

Popup 采用与Control 相同的内边距处理方式。有关内边距系统的直观说明，请参阅文档中的“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 。

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

Popup 采用与Control 相同的内边距处理方式。有关内边距系统的直观说明，请参阅文档中的“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 中定义的独特背景变暗效果，并且不允许点击或释放事件传递到其下方的元素。例如，如果用户不小心点击了弹出窗口外部，位于该点击位置且在弹出窗口下方的任何元素都不会接收到该事件。

在桌面平台上，模态弹出窗口通常仅在按下Esc键时才会关闭。要实现此行为，请将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

此属性用于设置默认内边距。

内边距属性用于控制content item 的几何形状。

Popup 采用与Control 相同的内边距处理方式。有关内边距系统的直观说明，请参阅文档中的“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 在所有平台上均受支持，但Popup.Window 和Popup.Native 通常仅在桌面平台上受支持。此外，如果弹出窗口是位于native menubar 内的Menu ，则该菜单也将采用原生形式。如果该菜单是另一个菜单内的子菜单，则由父（或根）菜单决定其类型。

默认值通常为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 。

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

Popup 采用与Control 相同的内边距处理方式。有关内边距系统的直观说明，请参阅文档中的“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 。

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

Popup 采用与Control 相同的内边距处理方式。有关内边距系统的可视化说明，请参阅文档中的“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 。

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

Popup 采用与Control 相同的内边距处理方式。有关内边距系统的直观说明，请参阅文档中的“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-value 为0 。

另请参阅 x 和y 。

Signal 文档

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

属性

信号

方法

详细说明

弹出窗口布局

弹出窗口类型

将弹出窗口显示为菜单项

将弹出窗口显示为独立窗口

显示原生弹出窗口

弹出窗口的尺寸调整

弹出窗口定位

使用覆盖层

弹出窗口过渡

“返回”/“Esc”事件处理

属性传播

完善已关闭弹出窗口的行为

属性文档

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

Signal 文档

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)]`