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

ContextMenu QML Type

Le type associé `ContextMenu` permet d'ouvrir un menu contextuel d'une manière adaptée à la plate-forme. En savoir plus...

Import Statement: import QtQuick.Controls
Since: Qt 6.9

Propriétés

Signaux

Description détaillée

ContextMenu peut être associé à n'importe quel élément item afin d'afficher un menu contextuel lors d'un événement spécifique à la plateforme, 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 objet « Menu » entre plusieurs objets de menu contextuel associés. Cela permet de réutiliser un seul menu lorsque les éléments nécessitant des menus contextuels ont des données en commun. Par exemple :

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

Performances

ContextMenu crée son Menu de manière différée, uniquement lorsqu’il en reçoit la demande. Sans cette optimisation, l’ Menu serait créé lors du chargement du composant qui le contient, c’est-à-dire généralement au démarrage de l’application.

Il est recommandé de ne pas attribuer d’identifiant à l’ Menu affectée à la propriété menu de ContextMenu lors de sa définition à l’endroit où elle est affectée. Cela empêcherait en effet cette optimisation. Par exemple :

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 car l’ Menu est défini séparément de son affectation.

Interaction avec d’autres menus

Si un menu contextuel ( Menu ) est ouvert, par exemple via une propriété ` TapHandler ` ou par d’autres moyens, le menu contextuel (ContextMenu) ne s’ouvrira pas en même temps. Cela permet aux applications héritées, écrites avant l’introduction de ContextMenu, de continuer à fonctionner comme prévu.

Prise en charge native des menus

ContextMenu s’appuie sur un menu natif sous 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 des 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' Menu e attribué à cette propriété ne peut pas recevoir d'identifiant. Pour plus d'informations, consultez Sharing context menus.

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 avec le bouton droit de la souris, la fonction ` position ` renvoie la position du clic par rapport à l'élément parent.

L'exemple ci-dessous montre comment ouvrir un menu contextuel par programmation :

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