Menu QML Type

弹出菜单，可用作上下文菜单或弹出菜单。更多

• 所有成员（包括继承成员）的列表

属性

• cascade : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• contentData : list<QtObject>
• contentModel : model
• count : int (since QtQuick.Controls 2.3 (Qt 5.10))
• currentIndex : int (since QtQuick.Controls 2.3 (Qt 5.10))
• delegate : Component (since QtQuick.Controls 2.3 (Qt 5.10))
• focus : bool
• icon
  • icon.cache : bool
  • icon.color : color
  • icon.height : int
  • icon.name : string
  • icon.source : url
  • icon.width : int
• overlap : real (since QtQuick.Controls 2.3 (Qt 5.10))
• title : string

方法

• Action actionAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addItem(Item item)
• void addMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• void dismiss() (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertAction(int index, Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertItem(int index, Item item)
• void insertMenu(int index, Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Item itemAt(int index)
• Menu menuAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void moveItem(int from, int to)
• void popup(MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeItem(Item item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Action takeAction(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• MenuItem takeItem(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• Menu takeMenu(int index) (since QtQuick.Controls 2.3 (Qt 5.10))

详细说明

菜单有两种主要用途：

• 上下文菜单；例如，右键单击后显示的菜单
• 弹出式菜单；例如，点击按钮后显示的菜单

作为上下文菜单使用时，建议使用popup() 打开菜单。除非明确指定了位置，否则在有鼠标光标的桌面平台上，菜单会定位在鼠标光标处，否则会居中显示在其父项上。

MouseArea {
    anchors.fill: parent
    acceptedButtons: Qt.LeftButton | Qt.RightButton
    onClicked: (mouse) => {
        if (mouse.button === Qt.RightButton)
            contextMenu.popup()
    }
    onPressAndHold: (mouse) => {
        if (mouse.source === Qt.MouseEventNotSynthesized)
            contextMenu.popup()
    }

    Menu {
        id: contextMenu
        MenuItem { text: "Cut" }
        MenuItem { text: "Copy" }
        MenuItem { text: "Paste" }
    }
}

作为弹出式菜单使用时，最简单的方法是通过使用相应属性指定所需的x 和y 坐标来指定位置，然后调用open() 打开菜单。

Button {
    id: fileButton
    text: "File"
    onClicked: menu.open()

    Menu {
        id: menu
        y: fileButton.height

        MenuItem {
            text: "New..."
        }
        MenuItem {
            text: "Open..."
        }
        MenuItem {
            text: "Save"
        }
    }
}

如果按钮在点击时也要关闭菜单，则使用Popup.CloseOnPressOutsideParent 标志：

    onClicked: menu.visible = !menu.visible

    Menu {
        id: menu
        // ...
        closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent

自QtQuick.Controls 2.3 (Qt XML 5.10) 起，也可以在 Menu.Controls 2.3 中创建子菜单并声明 Action 对象：

Menu {
    Action { text: "Cut" }
    Action { text: "Copy" }
    Action { text: "Paste" }

    MenuSeparator { }

    Menu {
        title: "Find/Replace"
        Action { text: "Find Next" }
        Action { text: "Find Previous" }
        Action { text: "Replace" }
    }
}

在有鼠标光标的桌面平台上，子菜单默认为cascading 。非层叠菜单一次显示一个菜单，并位于父菜单的中心。

通常情况下，菜单项被静态声明为菜单的子菜单，但 Menu 也提供了动态访问add 、insert 、move 和remove 项的 API。可以使用itemAt() 或contentChildren 访问菜单中的项目。

虽然MenuItems 最常用于菜单，但它可以包含任何类型的项目。

边距

由于继承自 Popup，Menu 支持margins 。默认情况下，所有内置样式都为菜单的边距指定了0 ，以确保菜单保持在窗口的范围内。如果要让菜单跳出窗口（例如以动画形式移动到视图中），可将 margins 属性设置为-1 。

动态生成菜单项

您可以通过Instantiator 或动态对象创建来动态创建菜单项。

使用实例器

您可以使用Instantiator 动态创建菜单项。下面的代码展示了如何实现 "最近文件 "子菜单，其中的项目来自存储在设置中的文件列表：

Menu {
    title: qsTr("File")

    Menu {
        id: recentFilesMenu
        title: qsTr("Recent Files")
        enabled: recentFilesInstantiator.count > 0

        Instantiator {
            id: recentFilesInstantiator
            model: settings.recentFiles
            delegate: MenuItem {
                text: settings.displayableFilePath(modelData)
                onTriggered: loadFile(modelData)
            }

            onObjectAdded: (index, object) => recentFilesMenu.insertItem(index, object)
            onObjectRemoved: (index, object) => recentFilesMenu.removeItem(object)
        }

        MenuSeparator {}

        MenuItem {
            text: qsTr("Clear Recent Files")
            onTriggered: settings.clearRecentFiles()
        }
    }
}

使用动态对象创建

你也可以使用Qt.createComponent() 从 QML 文件动态加载一个组件。一旦组件准备就绪，你就可以调用其createObject() 方法来创建该组件的实例。

Row {
    anchors.centerIn: parent

    Component {
        id: menuItemComponent

        MenuItem {}
    }

    Button {
        id: button
        text: "Menu"
        onClicked: menu.open()
        Menu {
            id: menu
        }
    }

    Button {
        text: "Add item"
        onClicked: {
            onClicked: {
                let menuItem = menuItemComponent.createObject(
                    menu.contentItem, { text: qsTr("New item") })
                menu.addItem(menuItem)
            }
        }
    }
}

菜单类型

自 Qt 6.8 起，菜单根据平台的不同提供了三种不同的实现方式。您可以通过设置popupType 来选择哪一种。这将让你控制菜单是显示为一个单独的窗口、作为父窗口中的一个项目，还是显示为一个本地菜单。有关这些选项的更多信息，请访问here 。

默认的popupType 由样式决定。例如，macOS 风格将其设置为Popup.Native ，而Imagine 风格则使用Popup.Window （当风格未设置弹出式类型时，默认值为 ）。如果你在菜单中添加了自定义功能，并希望无论使用哪种样式都能使用这些功能，就应该明确地将弹出类型设置为Popup.Window （或Popup.Item ）。另一种方法是设置Qt::AA_DontUseNativeMenuWindows application attribute 。这将禁用整个应用程序的本地上下文菜单，而与样式无关。

Popup.Item 在所有平台上都受支持，但Popup.Window 通常只在桌面平台上受支持。此外，如果菜单位于native menubar 中，菜单也将是本地的。如果菜单是另一个菜单中的子菜单，则由父（或根）菜单决定类型。

使用本地菜单时的限制

将popupType 设置为Popup.Native 时，与使用Popup.Item 和Popup.Window 相比，存在一些限制和差异。

API 差异

使用本地菜单时，所有平台都只支持菜单 API 的一个子集：

• x
• y
• visible
• opened
• title
• count
• contentData
• contentChildren (可视化子菜单将不可见）
• contentModel
• open()
• popup()
• close()
• opened()
• closed()
• aboutToShow()
• aboutToHide()

此外，在某些平台上，显示弹出窗口（例如使用open() 或popup() ）将是一个阻塞调用。这意味着在菜单再次关闭之前，调用不会返回，这会影响应用程序的逻辑。如果您的应用程序面向多个平台，因此有时会在不支持本地菜单的平台上运行，这一点尤其需要考虑。在这种情况下，例如，popupType 将返回Popup.Item ，而对open() 的调用将不会阻塞。

MenuItem 等项目仍会通过发出信号等方式对相应本地菜单项的点击做出反应，但会被本地对应项目取代。

渲染差异

本地菜单是使用平台上可用的本地菜单 API 实现的。因此，这些菜单及其所有内容都将由平台而非 QML 渲染。这意味着delegate 不会用于渲染。不过，它将始终被实例化（但隐藏），这样，诸如onCompleted() 等函数的执行与平台和popupType 无关。

支持的平台

本地菜单目前支持以下平台：

• 安卓
• iOS
• Linux（仅在使用 GTK+ 平台主题运行时可作为独立上下文菜单使用）
• MacOS
• Windows

另请参阅 Customizing Menu（自定义菜单）、MenuItem 、Menu Controls（菜单控件）、Popup Controls（弹出式控件）、Dynamic QML Object Creation from JavaScript（从 JavaScript 创建动态 QML 对象）、Popup type 、[QML] 和popupType 。

属性文档

Menu {
    id: menu
    contentItem: ListView {
        model: menu.contentModel
    }
}

Menu {
    Action { text: "Cut" }
    Action { text: "Copy" }
    Action { text: "Paste" }
}

方法文档