menus.create()

Erstellt ein Menüelement anhand eines Optionsobjekts, das Eigenschaften für das Element definiert.

Im Gegensatz zu anderen asynchronen Funktionen gibt diese keine Promise zurück, sondern verwendet einen optionalen Callback zur Kommunikation von Erfolg oder Misserfolg. Dies liegt daran, dass der Rückgabewert die ID des neuen Elements ist.

Um die Kompatibilität mit anderen Browsern sicherzustellen, stellt Firefox diese Methode im contextMenus-Namespace und im menus-Namespace zur Verfügung. Es ist jedoch nicht möglich, Werkzeuge-Menüelemente (contexts: ["tools_menu"]) mit dem contextMenus-Namespace zu erstellen.

Erstellen von Menüs in persistenten und nicht-persistenten Erweiterungen

Wie Sie Menüelemente erstellen, hängt davon ab, ob Ihre Erweiterung verwendet:

  • Nicht-persistente Hintergrundseiten (eine Event-Seite), bei der Menüs über Browser- und Erweiterungsneustarts hinweg bestehen bleiben. Sie rufen menus.create (mit einer menüspezifischen ID) innerhalb eines runtime.onInstalled-Listeners auf. Dies verhindert wiederholte Versuche, das Menuelement zu erstellen, wenn die Seiten neu starten, was bei einem Aufruf auf oberster Ebene der Fall wäre.
  • Persistente Hintergrundseiten:
    • in Chrome werden Menuelemente von persistenten Hintergrundseiten beibehalten. Erstellen Sie Ihre Menüs in einem runtime.onInstalled-Listener.
    • in Firefox werden Menuelemente von persistenten Hintergrundseiten nie beibehalten. Rufen Sie menus.create bedingungslos von der obersten Ebene aus auf, um die Menuelemente zu registrieren.

Weitere Informationen finden Sie unter Erweiterung initialisieren auf der Seite für Hintergrundskripte und Ereignisgesteuerte Hintergrundskripte im Extension Workshop.

Syntax

js
browser.menus.create(
  createProperties, // object
  () => {/* … */}   // optional function
)

Parameter

createProperties

object. Eigenschaften für das neue Menüelement.

checked Optional

boolean. Der Anfangszustand eines Kontrollkästchens oder Radio-Elements: true für ausgewählt und false für nicht ausgewählt. Nur ein Radio-Element kann zu einem bestimmten Zeitpunkt in einer gegebenen Gruppe von Radio-Elementen ausgewählt werden.

command Optional

string. Zeichenfolge, die eine Aktion beschreibt, die ausgeführt werden soll, wenn der Benutzer auf das Element klickt. Die anerkannten Werte sind:

  • "_execute_browser_action": simuliert einen Klick auf die Browser-Action der Erweiterung, um deren Popup zu öffnen, falls vorhanden (nur Manifest V2)
  • "_execute_action": simuliert einen Klick auf die Action der Erweiterung, um deren Popup zu öffnen, falls vorhanden (nur Manifest V3)
  • "_execute_page_action": simuliert einen Klick auf die Page-Action der Erweiterung, um deren Popup zu öffnen
  • "_execute_sidebar_action": öffnet die Seitenleiste der Erweiterung

Details finden Sie in der Dokumentation zu speziellen Shortcuts im Manifest.json-Schlüssel commands.

Wenn einer der anerkannten Werte angegeben ist, löst das Klicken auf das Element nicht das menus.onClicked-Ereignis aus; stattdessen wird die Standardaktion ausgelöst, wie z. B. das Öffnen eines Popups. Andernfalls löst das Klicken auf das Element menus.onClicked aus und das Ereignis kann verwendet werden, um ein alternatives Verhalten zu implementieren.

contexts Optional

array von menus.ContextType. Array von Kontexten, in denen dieses Menüelement angezeigt wird. Wenn diese Option weggelassen wird:

  • falls das übergeordnete Element Kontexte festgelegt hat, erbt dieses Element die Kontexte des übergeordneten Elements
  • andernfalls erhält das Element ein Kontexte-Array von ["page"].
documentUrlPatterns Optional

array von string. Ermöglicht Ihnen, das Element nur auf Dokumente anzuwenden, deren URL einem der gegebenen Übereinstimmungsmuster entspricht. Dies gilt auch für Frames.

enabled Optional

boolean. Ob dieses Menüelement aktiviert oder deaktiviert ist. Standardmäßig true.

icons Optional

object. Eines oder mehrere benutzerdefinierte Symbole, die neben dem Element angezeigt werden. Benutzerdefinierte Symbole können nur für Elemente in Untermenüs gesetzt werden. Diese Eigenschaft ist ein Objekt mit einer Eigenschaft für jedes bereitgestellte Symbol: Der Name der Eigenschaft sollte die Größe des Symbols in Pixeln enthalten, und der Pfad ist relativ zum Symbol vom Stammverzeichnis der Erweiterung. Der Browser versucht, ein 16x16-Pixel-Symbol für eine normale Anzeige oder ein 32x32-Pixel-Symbol für eine hochauflösende Anzeige auszuwählen. Um jede Skalierung zu vermeiden, können Sie Symbole folgendermaßen angeben:

js
browser.menus.create({
  icons: {
    16: "path/to/geo-16.png",
    32: "path/to/geo-32.png",
  },
});

Alternativ können Sie ein einzelnes SVG-Symbol angeben, das entsprechend skaliert wird:

js
browser.menus.create({
  icons: {
    16: "path/to/geo.svg",
  },
});

Hinweis: Das oberste Menuelement verwendet die im Manifest angegebenen Icons anstelle derer, die mit diesem Schlüssel angegeben sind.

id Optional

string. Die eindeutige ID, die diesem Element zugewiesen wird. Ist für nicht-persistente Hintergrund-(Ereignis-)seiten im Manifest V2 und im Manifest V3 obligatorisch. Kann nicht dieselbe sein wie eine andere ID für diese Erweiterung.

onclick Optional

function. Die Funktion, die aufgerufen wird, wenn auf das Menüelement geklickt wird. Ereignisseiten können dies nicht nutzen: Stattdessen sollten sie einen Listener für menus.onClicked registrieren.

parentId Optional

integer oder string. Die ID eines übergeordneten Menuelements, wodurch das Element ein Kind eines zuvor hinzugefügten Elements wird. Hinweis: Wenn Sie mehr als ein Menuelement erstellt haben, werden die Elemente in einem Untermenü platziert. Das Untermenü wird mit dem Namen der Erweiterung beschriftet.

targetUrlPatterns Optional

array von string. Ähnlich wie documentUrlPatterns, ermöglicht es Ihnen jedoch, anhand des href von Anchor-Tags und des src-Attributs von img/audio/video-Tags zu filtern. Dieser Parameter unterstützt jedes URL-Schema, auch solche, die normalerweise in einem Übereinstimmungsmuster nicht erlaubt sind.

title Optional

string. Der Text, der im Element angezeigt werden soll. Obligatorisch, es sei denn, type ist "separator".

Sie können %s in der Zeichenkette verwenden. Wenn Sie dies in einem Menüelement tun und ein Text im Dokument ausgewählt ist, wenn das Menü angezeigt wird, dann wird der ausgewählte Text in den Titel eingefügt. Zum Beispiel, wenn title "Übersetze '%s' ins Schweinlatein" ist und der Benutzer das Wort "cool" auswählt, dann das Menü aktiviert wird, wird der Titel des Menüelements sein: "Übersetze 'cool' ins Schweinlatein".

Wenn der Titel ein Kaufmannsund "&" enthält, wird das nächste Zeichen als Zugriffstaste für das Element verwendet, und das Kaufmannsund wird nicht angezeigt. Ausnahmen hiervon sind:

  • Wenn das nächste Zeichen ebenfalls ein Kaufmannsund ist: dann wird ein einzelnes Kaufmannsund angezeigt und es wird keine Zugriffstaste gesetzt. Effektiv wird "&&" verwendet, um ein einzelnes Kaufmannsund anzuzeigen.
  • Wenn die nächsten Zeichen die Interpolationsanweisung "%s" sind: dann wird das Kaufmannsund nicht angezeigt und es wird keine Zugriffstaste gesetzt.
  • Wenn das Kaufmannsund das letzte Zeichen im Titel ist: dann wird das Kaufmannsund nicht angezeigt und es wird keine Zugriffstaste gesetzt.

Nur das erste Kaufmannsund wird verwendet, um eine Zugriffstaste zu setzen: nachfolgende Kaufmannsundet werden nicht angezeigt, setzen jedoch keine Schlüssel. So wird "&A und &B" als "A und B" angezeigt und "A" als Zugriffstaste setzen.

In einigen lokalisierten Versionen von Firefox (Japanisch und Chinesisch) wird die Zugriffstaste in Klammern gesetzt und an das Menülabeletikett angehängt, es sei denn, der Menütitel endet selbst bereits mit der Zugriffstaste („toolkit(&K)“ zum Beispiel). Für weitere Details siehe Firefox Bug 1647373.

type Optional

menus.ItemType. Der Typ des Menüelements: "normal", "checkbox", "radio", "separator". Standardmäßig "normal".

viewTypes Optional

extension.ViewType. Liste von Ansichtstypen, in denen das Menüelement angezeigt wird. Standardmäßig in jeder Ansicht, einschließlich derjenigen ohne viewType.

visible Optional

boolean. Ob das Element im Menü angezeigt wird. Standardmäßig true.

callback Optional

function. Wird aufgerufen, wenn das Element erstellt wurde. Wenn es Probleme bei der Erstellung des Elements gab, sind Details in runtime.lastError verfügbar.

Rückgabewert

integer oder string. Die ID des neu erstellten Elements.

Beispiele

Dieses Beispiel erstellt ein Kontextmenüelement, das angezeigt wird, wenn der Benutzer Text auf der Seite ausgewählt hat. Es protokolliert einfach den ausgewählten Text in die Konsole:

js
browser.menus.create({
  id: "log-selection",
  title: "Log '%s' to the console",
  contexts: ["selection"],
});

browser.menus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "log-selection") {
    console.log(info.selectionText);
  }
});

Dieses Beispiel fügt zwei Radioelemente hinzu, mit denen Sie wählen können, ob Sie einen grünen oder einen blauen Rahmen auf die Seite anwenden möchten. Beachten Sie, dass dieses Beispiel die activeTab-Berechtigung benötigt.

js
function onCreated() {
  if (browser.runtime.lastError) {
    console.log("error creating item:", browser.runtime.lastError);
  } else {
    console.log("item created successfully");
  }
}

browser.menus.create(
  {
    id: "radio-green",
    type: "radio",
    title: "Make it green",
    contexts: ["all"],
    checked: false,
  },
  onCreated,
);

browser.menus.create(
  {
    id: "radio-blue",
    type: "radio",
    title: "Make it blue",
    contexts: ["all"],
    checked: false,
  },
  onCreated,
);

let makeItBlue = 'document.body.style.border = "5px solid blue"';
let makeItGreen = 'document.body.style.border = "5px solid green"';

browser.menus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "radio-blue") {
    browser.tabs.executeScript(tab.id, {
      code: makeItBlue,
    });
  } else if (info.menuItemId === "radio-green") {
    browser.tabs.executeScript(tab.id, {
      code: makeItGreen,
    });
  }
});

Beispielerweiterungen

Browser-Kompatibilität

Hinweis: Diese API basiert auf Chromiums chrome.contextMenus API. Diese Dokumentation ist abgeleitet von context_menus.json im Chromium-Code.