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 Radio-Eintrags: true für ausgewählt und false für nicht ausgewählt. In einer Gruppe von Radio-Einträgen kann jeweils nur ein Eintrag ausgewählt sein.

command Optional

string. Zeichenfolge, die eine Aktion beschreibt, die beim Klicken auf den Eintrag ausgeführt werden soll. Folgende Werte werden erkannt:

• "_execute_browser_action": Simuliert einen Klick auf die browser action der Erweiterung und öffnet deren Popup, falls vorhanden (nur Manifest V2).
• "_execute_action": Simuliert einen Klick auf die action der Erweiterung und öffnet deren Popup, falls vorhanden (nur Manifest V3).
• "_execute_page_action": Simuliert einen Klick auf die page action der Erweiterung und öffnet deren Popup, falls vorhanden.
• "_execute_sidebar_action": Öffnet die Seitenleiste der Erweiterung.

Einzelheiten finden Sie in der Dokumentation zu speziellen Tastenkombinationen für den 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 verwendet werden, um ein alternatives Verhalten zu implementieren.

contexts Optional

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

• Erbt der Eintrag die Kontexte seines übergeordneten Eintrags, falls 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 enthalten, und 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 ein Symbol 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 statt der mit diesem Schlüssel angegebenen Symbole.

id Optional

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

onclick Optional

function. Die Funktion, die beim Klicken auf den Menüeintrag aufgerufen wird. Event Pages 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ü angeordnet. Der übergeordnete Eintrag des Untermenüs trägt den Namen der Erweiterung.

targetUrlPatterns Optional

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

title Optional

string. Der im Eintrag angezeigte Text. Erforderlich, sofern type nicht "separator" ist.

Sie können %s in der Zeichenfolge verwenden. Wenn Sie dies in 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, 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 Und-Zeichen nicht angezeigt. Ausnahmen:

• Wenn das nächste Zeichen ebenfalls ein Und-Zeichen ist, wird ein einzelnes Und-Zeichen angezeigt und keine Zugriffstaste festgelegt. „&&“ dient somit dazu, ein einzelnes Und-Zeichen anzuzeigen.
• Wenn die nächsten Zeichen die Einfügeanweisung „%s“ sind, wird das Und-Zeichen nicht angezeigt und keine Zugriffstaste festgelegt.
• Wenn das Und-Zeichen das letzte Zeichen im Titel ist, wird es nicht angezeigt und keine Zugriffstaste festgelegt.

Nur das erste Und-Zeichen wird zum Festlegen einer Zugriffstaste verwendet. Nachfolgende 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 Firefox-Versionen (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 (beispielsweise "toolkit(&K)"). Weitere Informationen 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 des Eintrags Probleme aufgetreten sind, stehen Einzelheiten in 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 Radio-Einträge hinzu, mit denen Sie der Seite einen grünen oder blauen Rahmen zuweisen können. Dafür 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