Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

ContextMenu QML Type

Le type de pièce jointe ContextMenu permet d'ouvrir un menu contextuel d'une manière adaptée à la plate-forme. Plus d'informations...

Import Statement: import QtQuick.Controls
Since: Qt 6.9

Propriétés

Signaux

Description détaillée

ContextMenu peut être attaché à n'importe quel site item afin d'afficher un menu contextuel lors d'un événement spécifique à la plate-forme, tel qu'un clic droit ou la touche de menu contextuel.

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: { /* ... */ }
        }
    }
}

Partage des menus contextuels

Il est possible de partager un site Menu entre plusieurs objets de menu contextuel attachés. Cela permet de réutiliser un seul menu lorsque les éléments qui ont besoin d'un menu contextuel ont des données en commun. C'est le cas, par exemple, des éléments suivants

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

Performance

ContextMenu crée paresseusement son Menu uniquement lorsqu'il est demandé. Sans cette optimisation, le site Menu serait créé lors du chargement du composant qui le contient, ce qui se produit généralement au démarrage de l'application.

Il est recommandé de ne pas donner d'identifiant au Menu assigné à la propriété menu de ContextMenu lorsqu'il est défini à l'endroit où il est assigné. Cela empêcherait cette optimisation. Par exemple, l'exemple de la section fonctionne :

Pane {
    anchors.fill: parent

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

        // ...
    }
}

L'exemple de la section Sharing context menus fonctionne parce que le Menu est défini séparément de son affectation.

Interaction avec d'autres menus

Si un Menu est ouvert par le biais, par exemple, d'un TapHandler ou d'un autre moyen, ContextMenu ne s'ouvrira pas en même temps. Cela permet aux applications écrites avant l'introduction de ContextMenu de continuer à fonctionner comme prévu.

Prise en charge du menu natif

ContextMenu est soutenu par un menu natif sur iOS.

Remarque : si vous attribuez votre propre menu, vous devez définir popupType sur Popup.Native pour garantir la prise en charge du menu natif.

Documentation sur les propriétés

Cette propriété contient le menu contextuel qui sera ouvert. Elle peut être définie sur n'importe quel objet Menu.

Remarque : l'adresse Menu attribuée à cette propriété ne peut pas recevoir d'identifiant. Voir Sharing context menus pour plus d'informations.

Documentation sur les signaux

requested(point position)

Ce signal est émis lorsqu'un menu contextuel est demandé.

S'il a été demandé par un clic sur le bouton droit de la souris, position indique la position du clic par rapport au parent.

L'exemple ci-dessous montre comment ouvrir un menu contextuel de manière programmatique :

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

Si aucun menu n'est défini, mais que ce signal est connecté, l'événement du menu contextuel sera accepté et ne se propagera pas.

Remarque : le gestionnaire correspondant est onRequested.

Voir également 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.