Back to Qt.io
Contact Us Blog Download Qt

ContextMenu QML Type

ContextMenu 附件类型提供了一种以适合平台的方式打开上下文菜单的方法。更多

Import Statement: import QtQuick.Controls
Since: Qt 6.9

属性

信号

详细说明

ContextMenu 可附加到任何item ，以便在特定平台事件（如右键或上下文菜单键）发生时显示上下文菜单。

Pane {
    anchors.fill: parent

    ContextMenu.menu: Menu {
        MenuItem {
            text: qsTr("Eat Tomato")
            onTriggered: { /* ... */ }
        }
        MenuItem {
            text: qsTr("Throw Tomato")
            onTriggered: { /* ... */ }
        }
        MenuItem {
            text: qsTr("Squash Tomato")
            onTriggered: { /* ... */ }
        }
    }
}

共享上下文菜单

多个附加的上下文菜单对象可以共享一个Menu 。这样，当需要使用上下文菜单的项目有共同数据时，就可以重复使用单个菜单。例如

pragma ComponentBehavior: Bound

import QtQuick
import QtQuick.Controls.Basic
import QtQuick.Templates as T

ApplicationWindow {
    width: 600
    height: 400
    visible: true

    component Tomato: Label {
        id: tomato
        objectName: text
        horizontalAlignment: Label.AlignHCenter
        verticalAlignment: Label.AlignVCenter
        width: Math.max(200, contentWidth * 1.5, contentWidth * 1.5)
        height: width
        color: skinColor

        function eat() { print("Ate " + text) }
        function ditch() { print("Threw " + text) }
        function squash() { print("Squashed " + text) }

        property color skinColor: "tomato"

        background: Rectangle {
            color: tomato.skinColor
            radius: width / 2
        }

        ContextMenu.menu: contextMenu
    }

    Menu {
        id: contextMenu

        readonly property Tomato triggerItem: parent as Tomato
        readonly property string triggerItemText: triggerItem?.text ?? ""

        MenuItem {
            text: qsTr("Eat %1").arg(contextMenu.triggerItemText)
            onTriggered: contextMenu.triggerItem.eat()
        }
        MenuItem {
            text: qsTr("Throw %1").arg(contextMenu.triggerItemText)
            onTriggered: contextMenu.triggerItem.ditch()
        }
        MenuItem {
            text: qsTr("Squash %1").arg(contextMenu.triggerItemText)
            onTriggered: contextMenu.triggerItem.squash()
        }
    }

    Row {
        anchors.centerIn: parent

        Tomato {
            text: qsTr("tomato")
        }

        Tomato {
            text: qsTr("really ripe tomato")
            skinColor: "maroon"
        }
    }
}

性能

ContextMenu 仅在需要时才创建其Menu 。如果没有这种优化，Menu 将在加载包含组件（通常是在应用程序启动时）时创建。

建议在定义分配给 ContextMenu 的menu 属性的Menu 时，不要给它分配 id。这样做可以避免这种优化。例如

Pane {
    anchors.fill: parent

    ContextMenu.menu: Menu {
        // This prevents lazy creation of the Menu.
        id: myMenu

        // ...
    }
}

Sharing context menus 部分中的示例之所以有效，是因为Menu 是与其赋值分开定义的。

与其他菜单的交互

如果通过TapHandler 或其他方式打开Menu ，ContextMenu 将不会同时打开。这样，在引入 ContextMenu 之前编写的传统应用程序就可以继续按预期运行。

属性文档

该属性用于保存将打开的上下文菜单。它可以设置为任何Menu 对象。

注意： 分配给此属性的Menu 不能被赋予 id。更多信息请参见Sharing context menus 。


信号文档

requested(point position)

该信号在请求打开上下文菜单时发出。

如果是通过点击鼠标右键请求的，position 会给出相对于父对象的点击位置。

下面的示例展示了如何通过编程打开上下文菜单：

Button {
    id: button
    text: qsTr("Click me!")
    ContextMenu.onRequested: position => {
        const menu = buttonMenu.createObject(button)
        menu.popup(position)
    }
}

Component {
    id: buttonMenu
    Menu {
        MenuItem { text: qsTr("Open") }
    }
}

如果没有设置菜单，但连接了该信号，则上下文菜单事件将被接受，不会传播。

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

另请参阅 QContextMenuEvent::pos() 。


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