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 einesruntime.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
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 undfalse
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 Elementmenus.onClicked
aus und das Ereignis kann verwendet werden, um ein alternatives Verhalten zu implementieren. contexts
Optional-
array
vonmenus.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
vonstring
. 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äßigtrue
. 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:jsbrowser.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:
jsbrowser.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ürmenus.onClicked
registrieren. parentId
Optional-
integer
oderstring
. 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
vonstring
. Ähnlich wiedocumentUrlPatterns
, ermöglicht es Ihnen jedoch, anhand deshref
von Anchor-Tags und dessrc
-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, wenntitle
"Ü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 ohneviewType
. visible
Optional-
boolean
. Ob das Element im Menü angezeigt wird. Standardmäßigtrue
.
callback
Optional-
function
. Wird aufgerufen, wenn das Element erstellt wurde. Wenn es Probleme bei der Erstellung des Elements gab, sind Details inruntime.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:
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.
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.