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 共享给多个关联的上下文菜单对象。当需要上下文菜单的各项具有共同数据时，这允许复用同一个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引入之前编写的旧版应用程序能够继续按预期运行。

原生菜单支持

ContextMenu 在 iOS 上由原生菜单提供支持。

注意：如果您 分配了自己的menu ，必须将popupType 设置为Popup.Native ，以确保原生菜单支持。

属性文档

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

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

Signal 文档

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()。

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