menus

Fügen Sie Elemente zum Menüsystem des Browsers hinzu.

Diese API basiert auf Chromes „contextMenus“ API, welche es Chrome-Erweiterungen ermöglicht, Elemente zum Kontextmenü des Browsers hinzuzufügen. Die browser.menus API ergänzt die API von Chrome um einige Funktionen.

Vor Firefox 55 wurde diese API auch ursprünglich contextMenus genannt, und dieser Name wurde als Alias beibehalten, sodass Sie contextMenus verwenden können, um Code zu schreiben, der sowohl in Firefox als auch in anderen Browsern funktioniert.

Um diese API zu verwenden, müssen Sie die menus Berechtigung haben. Sie können auch den contextMenus-Alias anstelle von menus verwenden, aber wenn Sie dies tun, müssen auf die APIs als browser.contextMenus zugegriffen werden.

Mit Ausnahme von menus.getTargetElement() kann diese API nicht von Inhalts-Skripten aus verwendet werden.

Erstellen von Menüelementen

Um ein Menüelement zu erstellen, rufen Sie die Methode menus.create() auf. Sie übergeben dieser Methode ein Objekt mit Optionen für das Element, einschließlich der Element-ID, des Elementtyps und der Kontexte, in denen es angezeigt werden soll.

In einer Firefox-Erweiterung mit nicht-persistenten Hintergrundseiten (Ereignisseiten) oder in einer beliebigen Chrome-Erweiterung rufen Sie menus.create innerhalb eines runtime.onInstalled-Listeners auf. In einer Firefox-Erweiterung mit persistenten Hintergrundseiten wird ein Aufruf auf oberster Ebene gemacht. Weitere Informationen finden Sie unter menus.create().

Hören Sie auf Klicks auf Ihr Menüelement, indem Sie einen Listener zum Ereignis menus.onClicked hinzufügen. Dieser Listener erhält ein Objekt vom Typ menus.OnClickData, das die Details des Ereignisses enthält.

Sie können vier verschiedene Arten von Menüelementen erstellen, basierend auf dem Wert der type-Eigenschaft, die Sie in den Optionen zu create() angeben:

  • „normal“: ein Menüelement, das nur ein Label anzeigt
  • „checkbox“: ein Menüelement, das einen binären Zustand darstellt. Es zeigt ein Häkchen neben dem Label an. Wenn man auf das Element klickt, wird das Häkchen umgeschaltet. Der Klick-Listener erhält zwei zusätzliche Eigenschaften: „checked“, das anzeigt, ob das Element jetzt markiert ist, und „wasChecked“, das anzeigt, ob das Element vor dem Klick-Ereignis markiert war.
  • „radio“: ein Menüelement, das eine von mehreren Wahlmöglichkeiten darstellt. Wie auch ein Checkboxelement, zeigt es ein Häkchen neben dem Label an, und sein Klick-Listener zeigt „checked“ und „wasChecked“ an. Wenn Sie jedoch mehr als ein Radioelement erstellen, funktionieren diese Elemente als Gruppe von Radioelementen: Nur ein Element in der Gruppe kann markiert sein, und ein Klick auf ein Element macht es zum markierten Element.
  • „separator“: eine Linie, die eine Gruppe von Elementen trennt.

Wenn Sie mehr als ein Kontextmenüelement oder mehr als ein Werkzeugmenüelement erstellt haben, werden die Elemente in ein Untermenü platziert. Das Eltern-Menü des Untermenüs wird mit dem Namen der Erweiterung beschriftet. Zum Beispiel hier eine Erweiterung namens „Menu demo“, die zwei Kontextmenüelemente hinzugefügt hat:

Kontextmenü mit zwei Elementen mit der Bezeichnung Click me und Click me too!

Icons

Wenn Sie Icons für Ihre Erweiterung mit dem "icons"-Manifest-Schlüssel angegeben haben, zeigt Ihr Menüelement das angegebene Icon neben seinem Label an. Der Browser wird versuchen, ein 16x16 Pixel großes Icon für eine normale Anzeige oder ein 32x32 Pixel großes Icon für eine Anzeige mit hoher Dichte zu wählen:

Kontextmenü mit zwei Elementen mit der Bezeichnung Click me und Click me too!

Nur für Elemente in einem Untermenü können Sie benutzerdefinierte Icons angeben, indem Sie die icons-Option an menus.create() übergeben:

Kontextmenü mit zwei Elementen mit der Bezeichnung Click me und Click me too!. Die Option Click me ist mit einem grünen Farbdosensymbol gekennzeichnet. Die Option Click me too ist mit einem blauen Farbdosensymbol gekennzeichnet.

Beispiel

Hier ist ein Kontextmenü mit 4 Elementen: ein normales Element, zwei Radioelemente mit Trennern auf jeder Seite und ein Kontrollkästchen. Die Radioelemente erhalten benutzerdefinierte Icons.

Kontextmenü mit vier Elementen mit der Bezeichnung remove me, Greenify, Bluify und uncheck me. Greenify und Bluify sind Radiobuttons mit benutzerdefinierten Symbolen.

Sie könnten ein solches Untermenü mit einem Code wie diesem erstellen:

js
browser.menus.create(
  {
    id: "remove-me",
    title: browser.i18n.getMessage("menuItemRemoveMe"),
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-1",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "greenify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemGreenify"),
    contexts: ["all"],
    checked: true,
    icons: {
      16: "icons/paint-green-16.png",
      32: "icons/paint-green-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "bluify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemBluify"),
    contexts: ["all"],
    checked: false,
    icons: {
      16: "icons/paint-blue-16.png",
      32: "icons/paint-blue-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-2",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

let checkedState = true;

browser.menus.create(
  {
    id: "check-uncheck",
    type: "checkbox",
    title: browser.i18n.getMessage("menuItemUncheckMe"),
    contexts: ["all"],
    checked: checkedState,
  },
  onCreated,
);

Typen

Die verschiedenen Kontexte, in denen ein Menü erscheinen kann.

Der Typ des Menüelements: „normal“, „checkbox“, „radio“, „separator“.

Informationen, die gesendet werden, wenn ein Menüelement angeklickt wird.

Eigenschaften

Die maximale Anzahl von Erweiterungselementen auf oberster Ebene, die zu einem Menüelement hinzugefügt werden können, dessen ContextType „browser_action“ oder „page_action“ ist.

Funktionen

Erstellt ein neues Menüelement.

Gibt das Element für eine gegebene info.targetElementId zurück.

Blendet alle standardmäßigen Firefox-Menüelemente aus, um eine benutzerdefinierte Kontextmenü-Benutzeroberfläche bereitzustellen.

Aktualisiert ein derzeit angezeigtes Menü.

Entfernt ein Menüelement.

Entfernt alle von dieser Erweiterung hinzugefügten Menüelemente.

Aktualisiert ein zuvor erstelltes Menüelement.

Ereignisse

Wird ausgelöst, wenn auf ein Menüelement geklickt wird.

Wird ausgelöst, wenn der Browser ein Menü ausblendet.

Wird ausgelöst, wenn der Browser ein Menü anzeigt.

Browser-Kompatibilität

Beispiel-Erweiterungen

BCD tables only load in the browser

Hinweis: Diese API basiert auf Chromium's chrome.contextMenus API. Diese Dokumentation stammt von context_menus.json im Chromium-Code.