QML Popup 组件

原创于 2025-04-20 00:46:55 发布

· 385 阅读

8 ·

版权

文章标签：

#qml

QML 专栏收录该内容

91 篇文章

订阅专栏

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