QML Popup 组件

Popup 是 QML 中用于创建弹出窗口的组件，它提供了一种在现有内容上方显示临时内容的方式。Popup 继承自 QtQuick.Controls 模块，是对话框、菜单、工具提示等弹出式UI的基础。

基本属性

属性	类型	默认值	说明
visible	bool	false	控制弹出窗口是否可见
modal	bool	false	是否为模态弹出窗口
dim	bool	false	背景是否变暗
closePolicy	enumeration	Popup.CloseOnEscape | Popup.CloseOnPressOutside	关闭策略
padding	real	0	内边距
leftPadding	real	padding	左内边距
rightPadding	real	padding	右内边距
topPadding	real	padding	上内边距
bottomPadding	real	padding	下内边距
margins	real	0	外边距
leftMargin	real	margins	左外边距
rightMargin	real	margins	右外边距
topMargin	real	margins	上外边距
bottomMargin	real	margins	下外边距
contentWidth	real	implicitContentWidth	内容宽度
contentHeight	real	implicitContentHeight	内容高度
implicitContentWidth	real	自动计算	隐式内容宽度
implicitContentHeight	real	自动计算	隐式内容高度
background	Item	null	背景项
contentItem	Item	null	内容项
enter	Transition	null	进入动画
exit	Transition	null	退出动画
overlay	Item	自动创建	覆盖层项
parent	Item	Overlay.overlay	父项
x	real	(parent.width - width) / 2	X坐标
y	real	(parent.height - height) / 2	Y坐标

ClosePolicy 枚举值

值	说明
Popup.NoAutoClose	不自动关闭
Popup.CloseOnPressOutside	点击外部时关闭
Popup.CloseOnPressOutsideParent	点击父项外部时关闭
Popup.CloseOnReleaseOutside	在外部释放鼠标时关闭
Popup.CloseOnReleaseOutsideParent	在父项外部释放鼠标时关闭
Popup.CloseOnEscape	按下Esc键时关闭

常用方法

方法	参数	返回值	说明
open()	-	-	打开弹出窗口
close()	-	-	关闭弹出窗口
toggle()	-	-	切换弹出窗口状态
forceActiveFocus()	-	-	强制获取焦点

常用信号

信号	参数	说明
opened()	-	弹出窗口打开后触发
closed()	-	弹出窗口关闭后触发
aboutToShow()	-	弹出窗口即将显示时触发
aboutToHide()	-	弹出窗口即将隐藏时触发

使用示例

基本弹出窗口

qml

import QtQuick 2.15
import QtQuick.Controls 2.15

Button {
    text: "打开弹出窗口"
    onClicked: popup.open()
}

Popup {
    id: popup
    x: 100
    y: 100
    width: 200
    height: 300
    modal: true
    focus: true
    
    Column {
        anchors.fill: parent
        spacing: 10
        
        Label {
            text: "这是一个弹出窗口"
            font.bold: true
        }
        
        Button {
            text: "关闭"
            onClicked: popup.close()
        }
    }
}

带动画的弹出窗口

qml

Popup {
    id: animatedPopup
    width: 250
    height: 150
    
    enter: Transition {
        NumberAnimation { property: "opacity"; from: 0.0; to: 1.0; duration: 200 }
        NumberAnimation { property: "scale"; from: 0.5; to: 1.0; duration: 200 }
    }
    
    exit: Transition {
        NumberAnimation { property: "opacity"; from: 1.0; to: 0.0; duration: 200 }
        NumberAnimation { property: "scale"; from: 1.0; to: 0.5; duration: 200 }
    }
    
    // 内容...
}

自定义样式的弹出窗口

qml

Popup {
    id: styledPopup
    width: 300
    height: 200
    dim: true
    closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutside
    
    background: Rectangle {
        color: "#FFFFFF"
        border.color: "#21BE2B"
        border.width: 2
        radius: 5
    }
    
    contentItem: Column {
        padding: 20
        spacing: 15
        
        Label {
            text: "自定义样式弹出窗口"
            font.pixelSize: 18
            font.bold: true
            color: "#21BE2B"
        }
        
        Text {
            text: "这是一个自定义样式的弹出窗口示例。"
            wrapMode: Text.Wrap
            width: styledPopup.width - 40
        }
    }
}

定位弹出窗口

qml

Button {
    id: button
    text: "定位弹出窗口"
    onClicked: positionedPopup.open()
}

Popup {
    id: positionedPopup
    parent: button  // 相对于按钮定位
    y: button.height + 5  // 按钮下方5像素
    width: 200
    height: 100
    
    // 内容...
}

高级用法

动态内容弹出窗口

qml

Popup {
    id: dynamicPopup
    property string message: ""
    
    Column {
        anchors.fill: parent
        padding: 10
        
        Label {
            text: dynamicPopup.message
            wrapMode: Text.Wrap
            width: parent.width
        }
        
        Button {
            text: "确定"
            onClicked: dynamicPopup.close()
        }
    }
}

// 使用方式
Button {
    text: "显示消息"
    onClicked: {
        dynamicPopup.message = "这是一个动态内容的弹出窗口示例。"
        dynamicPopup.open()
    }
}

复杂布局弹出窗口

qml

Popup {
    id: complexPopup
    width: 350
    height: 250
    modal: true
    
    Column {
        anchors.fill: parent
        spacing: 0
        
        // 标题栏
        Rectangle {
            width: parent.width
            height: 40
            color: "#21BE2B"
            
            Label {
                anchors.centerIn: parent
                text: "复杂弹出窗口"
                color: "white"
                font.bold: true
            }
            
            Button {
                anchors.right: parent.right
                anchors.verticalCenter: parent.verticalCenter
                text: "X"
                flat: true
                onClicked: complexPopup.close()
            }
        }
        
        // 内容区域
        ScrollView {
            width: parent.width
            height: parent.height - 80
            clip: true
            
            TextArea {
                text: "这是一个带有标题栏和按钮区域的复杂弹出窗口示例。"
                wrapMode: Text.Wrap
            }
        }
        
        // 按钮区域
        Row {
            width: parent.width
            height: 40
            spacing: 10
            padding: 5
            layoutDirection: Qt.RightToLeft
            
            Button {
                text: "取消"
                onClicked: complexPopup.close()
            }
            
            Button {
                text: "确定"
                highlighted: true
                onClicked: {
                    console.log("确定按钮被点击")
                    complexPopup.close()
                }
            }
        }
    }
}

嵌套弹出窗口

qml

Popup {
    id: mainPopup
    width: 300
    height: 200
    
    Button {
        text: "打开嵌套弹出窗口"
        anchors.centerIn: parent
        onClicked: nestedPopup.open()
    }
    
    Popup {
        id: nestedPopup
        parent: mainPopup.contentItem
        width: 200
        height: 100
        x: (mainPopup.width - width) / 2
        y: (mainPopup.height - height) / 2
        
        Label {
            text: "嵌套的弹出窗口"
            anchors.centerIn: parent
        }
    }
}

注意事项

1. 模态弹出窗口会阻止与其他窗口的交互

2. 设置 dim: true 时，背景会变暗

3. 默认情况下，Popup 会附加到 Overlay.overlay 上

4. 可以通过设置 parent 属性改变弹出窗口的父项

5. 使用 closePolicy 可以灵活控制弹出窗口的关闭行为

6. 为获得更好的用户体验，建议为弹出窗口添加适当的动画效果