menus.create()

Syntax

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

Parameter

createProperties

object. Eigenschaften des neuen Menüeintrags.

checked Optional

boolean. Der Anfangszustand eines Kontrollkästchen- oder Optionsfeld-Eintrags: true für ausgewählt und false für nicht ausgewählt. Innerhalb einer Gruppe von Optionsfeld-Einträgen kann jeweils nur ein Eintrag ausgewählt sein.

command Optional

string. Zeichenfolge, die eine Aktion beschreibt, die beim Anklicken des Eintrags ausgeführt werden soll. Folgende Werte werden erkannt:

• "_execute_browser_action": Simuliert einen Klick auf die Browser-Aktion der Erweiterung und öffnet gegebenenfalls deren Popup (nur Manifest V2).
• "_execute_action": Simuliert einen Klick auf die Aktion der Erweiterung und öffnet gegebenenfalls deren Popup (nur Manifest V3).
• "_execute_page_action": Simuliert einen Klick auf die Seitenaktion der Erweiterung und öffnet gegebenenfalls deren Popup.
• "_execute_sidebar_action": Öffnet die Seitenleiste der Erweiterung.

Einzelheiten finden Sie in der Dokumentation zu speziellen Tastenkombinationen beim manifest.json-Schlüssel commands.

Wenn einer der erkannten Werte angegeben ist, löst ein Klick auf den Eintrag nicht das Ereignis menus.onClicked aus. Stattdessen wird die Standardaktion ausgeführt, beispielsweise das Öffnen eines Popups. Andernfalls löst ein Klick auf den Eintrag menus.onClicked aus; dieses Ereignis kann zur Implementierung eines alternativen Verhaltens verwendet werden.

contexts Optional

array von menus.ContextType. Array der Kontexte, in denen dieser Menüeintrag erscheint. Wenn diese Option weggelassen wird:

• Erbt der Eintrag die Kontexte seines übergeordneten Eintrags, sofern für diesen Kontexte festgelegt sind.
• Andernfalls erhält der Eintrag das Kontext-Array ["page"].

documentUrlPatterns Optional

array von string. Beschränkt den Eintrag auf Dokumente, deren URL mit einem der angegebenen Übereinstimmungsmuster übereinstimmt. Dies gilt auch für Frames.

enabled Optional

boolean. Gibt an, ob dieser Menüeintrag aktiviert oder deaktiviert ist. Der Standardwert ist true.

icons Optional

object. Ein oder mehrere benutzerdefinierte Symbole, die neben dem Eintrag angezeigt werden. Benutzerdefinierte Symbole können nur für Einträge in Untermenüs festgelegt werden. Diese Eigenschaft ist ein Objekt mit einer Eigenschaft für jedes bereitgestellte Symbol: Der Eigenschaftsname sollte die Größe des Symbols in Pixeln angeben; der Pfad zum Symbol ist relativ zum Stammverzeichnis der Erweiterung. Der Browser versucht, für eine normale Anzeige ein Symbol mit 16 × 16 Pixeln und für eine Anzeige mit hoher Pixeldichte eines mit 32 × 32 Pixeln auszuwählen. Um eine Skalierung zu vermeiden, können Sie Symbole wie folgt 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: Der Menüeintrag auf oberster Ebene verwendet die im Manifest angegebenen Symbole und nicht die mit diesem Schlüssel festgelegten.

id Optional

string. Die eindeutige ID, die diesem Eintrag zugewiesen wird. Für nicht persistente Hintergrundseiten (Ereignisseiten) in Manifest V2 und in Manifest V3 ist sie erforderlich. Sie darf nicht mit einer anderen ID dieser Erweiterung übereinstimmen.

onclick Optional

function. Die Funktion, die beim Anklicken des Menüeintrags aufgerufen wird. Ereignisseiten können diese Eigenschaft nicht verwenden; stattdessen sollten sie einen Listener für menus.onClicked registrieren.

parentId Optional

integer oder string. Die ID eines übergeordneten Menüeintrags; dadurch wird der Eintrag einem zuvor hinzugefügten Eintrag untergeordnet. Hinweis: Wenn Sie mehr als einen Menüeintrag erstellt haben, werden die Einträge in einem Untermenü platziert. Der übergeordnete Eintrag des Untermenüs trägt den Namen der Erweiterung.

targetUrlPatterns Optional

array von string. Ähnlich wie documentUrlPatterns, ermöglicht aber die Filterung anhand von href bei Anker-Tags und des src-Attributs bei img/audio/video-Tags. Dieser Parameter unterstützt jedes URL-Schema, auch solche, die in Übereinstimmungsmustern normalerweise nicht zulässig sind.

title Optional

string. Der Text, der im Eintrag angezeigt wird. Erforderlich, sofern type nicht "separator" ist.

Sie können %s in der Zeichenfolge verwenden. Wenn Sie dies bei einem Menüeintrag tun und beim Anzeigen des Menüs Text auf der Seite ausgewählt ist, wird der ausgewählte Text in den Titel eingefügt. Wenn title beispielsweise "Translate '%s' to Pig Latin" lautet und der Benutzer das Wort "cool" auswählt und dann das Menü öffnet, lautet der Titel des Menüeintrags: "Translate 'cool' to Pig Latin".

Wenn der Titel ein kaufmännisches Und-Zeichen "&" enthält, wird das folgende Zeichen als Zugriffstaste für den Eintrag verwendet und das kaufmännische Und-Zeichen nicht angezeigt. Ausnahmen sind:

• Wenn das nächste Zeichen ebenfalls ein kaufmännisches Und-Zeichen ist, wird ein einzelnes kaufmännisches Und-Zeichen angezeigt und keine Zugriffstaste festgelegt. Mit "&&" lässt sich also ein einzelnes kaufmännisches Und-Zeichen anzeigen.
• Wenn die nächsten Zeichen die Einfügeanweisung "%s" sind, wird das kaufmännische Und-Zeichen nicht angezeigt und keine Zugriffstaste festgelegt.
• Wenn das kaufmännische Und-Zeichen das letzte Zeichen im Titel ist, wird es nicht angezeigt und keine Zugriffstaste festgelegt.

Nur das erste kaufmännische Und-Zeichen wird zum Festlegen einer Zugriffstaste verwendet: Nachfolgende kaufmännische Und-Zeichen werden nicht angezeigt, legen aber auch keine Zugriffstasten fest. So wird "&A and &B" als "A and B" angezeigt und "A" als Zugriffstaste festgelegt.

In einigen lokalisierten Versionen von Firefox (Japanisch und Chinesisch) wird die Zugriffstaste in Klammern gesetzt und an die Menübeschriftung angehängt, es sei denn, der Menütitel endet bereits mit der Zugriffstaste (zum Beispiel "toolkit(&K)"). Weitere Einzelheiten finden Sie unter Firefox-Bug 1647373.

type Optional

menus.ItemType. Der Typ des Menüeintrags: "normal", "checkbox", "radio" oder "separator". Der Standardwert ist "normal".

viewTypes Optional

extension.ViewType. Liste der Ansichtstypen, in denen der Menüeintrag angezeigt wird. Standardmäßig wird er in allen Ansichten angezeigt, auch in solchen ohne viewType.

visible Optional

boolean. Gibt an, ob der Eintrag im Menü angezeigt wird. Der Standardwert ist true.

callback Optional

function. Wird aufgerufen, wenn der Eintrag erstellt wurde. Falls beim Erstellen Probleme aufgetreten sind, stehen Einzelheiten unter runtime.lastError zur Verfügung.

Rückgabewert

integer oder string. Die ID des neu erstellten Eintrags.

Beispiele

Dieses Beispiel erstellt einen Kontextmenüeintrag, der angezeigt wird, wenn der Benutzer Text auf der Seite ausgewählt hat. Der ausgewählte Text wird lediglich in der Konsole protokolliert:

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 Optionsfeld-Einträge hinzu, mit denen Sie der Seite einen grünen oder blauen Rahmen geben können. Für dieses Beispiel ist die Berechtigung activeTab erforderlich.

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

• menu-accesskey-visible
• menu-demo
• menu-labelled-open
• menu-remove-element
• menu-search
• session-state

Browser-Kompatibilität