menus.create()
Erstellt ein Menüelement mithilfe eines Optionsobjekts, das Eigenschaften für das Element definiert.
Im Gegensatz zu anderen asynchronen Funktionen gibt diese keinen Promise zurück, sondern verwendet einen optionalen Rückruf, um über Erfolg oder Misserfolg zu kommunizieren. Dies liegt daran, dass der Rückgabewert die ID des neuen Elements ist.
Für die Kompatibilität mit anderen Browsern stellt Firefox diese Methode sowohl im contextMenus
-Namespace als auch 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 Ereignisseite), bei denen Menüs über Browser- und Erweiterungsneustarts hinweg bestehen. Sie rufen
menus.create
(mit einer menüspezifischen ID) innerhalb einesruntime.onInstalled
-Listeners auf. Dies vermeidet wiederholte Versuche, das Menüelement zu erstellen, wenn die Seiten neu starten würden, was bei einem Aufruf auf oberster Ebene der Fall wäre.- persistente Hintergrundseiten:
- In Chrome werden Menüelemente aus persistenten Hintergrundseiten beibehalten. Erstellen Sie Ihre Menüs in einem
runtime.onInstalled
-Listener.- In Firefox werden Menüelemente aus persistenten Hintergrundseiten niemals beibehalten. Rufen Sie
menus.create
bedingungslos aus der obersten Ebene auf, um die Menüelemente zu registrieren.Weitere Informationen finden Sie unter Die Erweiterung initialisieren auf der Seite zu Hintergrundskripten 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 anfängliche Zustand eines Checkbox- oder Radio-Elements:true
für ausgewählt undfalse
für nicht ausgewählt. Nur ein Radio-Element kann gleichzeitig in einer gegebenen Gruppe von Radio-Elementen ausgewählt sein. command
Optional-
string
. Ein String, der eine Aktion beschreibt, die ausgeführt werden soll, wenn der Benutzer auf das Element klickt. Anerkannte Werte sind:"_execute_browser_action"
: simuliert einen Klick auf die Browseraktion der Erweiterung und öffnet dessen Popup, falls vorhanden (nur Manifest V2)"_execute_action"
: simuliert einen Klick auf die Aktion der Erweiterung und öffnet dessen Popup, falls vorhanden (nur Manifest V3)"_execute_page_action"
: simuliert einen Klick auf die Seitenaktion der Erweiterung und öffnet dessen Popup, falls vorhanden"_execute_sidebar_action"
: öffnet die Seitenleiste der Erweiterung
Siehe die Dokumentation der speziellen Tastenkombinationen im manifest.json-Schlüssel
commands
für Details.Wenn einer der anerkannten Werte angegeben ist, löst ein Klick auf das Element nicht das
menus.onClicked
-Ereignis aus; stattdessen wird die Standardaktion ausgelöst, wie z. B. das Öffnen eines Pop-Ups. Andernfalls löst ein Klick auf das Element dasmenus.onClicked
-Ereignis aus, das verwendet werden kann, um ein alternatives Verhalten zu implementieren. contexts
Optional-
array
vonmenus.ContextType
. Array von Kontexten, in denen dieses Menüelement erscheinen wird. Wenn diese Option weggelassen wird:- Wenn das übergeordnete Element Kontexte festgelegt hat, erbt dieses Element die Kontexte seines übergeordneten Elements
- Andernfalls wird dem Element ein Kontext-Array von ["page"] zugewiesen.
documentUrlPatterns
Optional-
array
vonstring
. Ermöglicht es, das Element so zu beschränken, dass es nur auf Dokumente angewendet wird, deren URL einem der angegebenen Ü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 sollen. Benutzerdefinierte Symbole können nur für Elemente festgelegt werden, die in Untermenüs erscheinen. 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 aus dem Stammverzeichnis der Erweiterung. Der Browser versucht, ein 16x16 Pixel großes Symbol für ein normales Display oder ein 32x32 Pixel großes Symbol für ein hochauflösendes Display auszuwählen. Um jegliche Skalierung zu vermeiden, können Sie Symbole wie folgt 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 Menüelement auf oberster Ebene verwendet die im Manifest angegebenen Symbole, anstatt was mit diesem Schlüssel angegeben ist.
id
Optional-
string
. Die eindeutige ID, die diesem Element zugewiesen werden soll. Ist obligatorisch für nicht-persistente Hintergrund- (Ereignis-) Seiten in Manifest V2 und in Manifest V3. Kann nicht dieselbe wie eine andere ID für diese Erweiterung sein. onclick
Optional-
function
. Die Funktion, die aufgerufen wird, wenn das Menüelement angeklickt wird. Ereignisseiten können dies nicht verwenden: Stattdessen sollten sie einen Listener fürmenus.onClicked
registrieren. parentId
Optional-
integer
oderstring
. Die ID eines übergeordneten Menüelements; dies macht das Element zu einem Kind eines zuvor hinzugefügten Elements. Hinweis: Wenn Sie mehr als ein Menüelement erstellt haben, werden die Elemente in einem Untermenü platziert. Das übergeordnete Element des Untermenüs wird mit dem Namen der Erweiterung beschriftet. targetUrlPatterns
Optional-
array
vonstring
. Ähnlich wiedocumentUrlPatterns
, jedoch ermöglicht es, basierend auf demhref
von Anker-Tags und demsrc
-Attribut 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 wird. Obligatorisch, es sei denn,type
ist "separator".Sie können
%s
im String verwenden. Wenn Sie dies in einem Menüelement tun und etwas Text auf der Seite ausgewählt ist, wenn das Menü angezeigt wird, wird der ausgewählte Text in den Titel interpoliert. Zum Beispiel, wenntitle
"Übersetze '%s' in Pig Latin" ist und der Benutzer das Wort "cool" auswählt, dann das Menü aktiviert, lautet der Titel des Menüelements: "Übersetze 'cool' in Pig Latin".Wenn der Titel ein Kaufmanns-Und "&" enthält, wird das nächste Zeichen als Zugangsschlüssel für das Element verwendet, und das Kaufmanns-Und wird nicht angezeigt. Ausnahmen hiervon sind:
- Wenn das nächste Zeichen ebenfalls ein Kaufmanns-Und ist: dann wird ein einzelnes Kaufmanns-Und angezeigt und kein Zugangsschlüssel festgelegt. Im Effekt wird "&&" verwendet, um ein einzelnes Kaufmanns-Und anzuzeigen.
- Wenn die nächsten Zeichen die Interpolationsanweisung "%s" sind: dann wird das Kaufmanns-Und nicht angezeigt und es wird kein Zugangsschlüssel festgelegt.
- Wenn das Kaufmanns-Und das letzte Zeichen im Titel ist: dann wird das Kaufmanns-Und nicht angezeigt und es wird kein Zugangsschlüssel festgelegt.
Nur das erste Kaufmanns-Und wird verwendet, um einen Zugangsschlüssel festzulegen: nachfolgende Kaufmanns-Unds werden nicht angezeigt, aber auch keine Schlüssel festgelegt. Also wird "&A und &B" als "A und B" angezeigt und "A" als Zugangsschlüssel festgelegt.
In einigen lokalisierten Versionen von Firefox (Japanisch und Chinesisch) ist der Zugangsschlüssel in Klammern gesetzt und wird an das Menülabel angehängt, es sei denn, der Menütitel selbst endet bereits mit dem Zugangsschlüssel (
"toolkit(&K)"
zum Beispiel). Weitere Details finden Sie in Firefox Bug 1647373. type
Optional-
menus.ItemType
. Der Typ des Menüelements: "normal", "checkbox", "radio", "separator". Standardmäßig "normal". viewTypes
Optional-
extension.ViewType
. Liste der Ansichtstypen, in denen das Menüelement angezeigt wird. Standardmäßig auf jede Ansicht, einschließlich solcher 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 Einzelheiten 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 einen grünen oder blauen Rahmen auf die Seite anwenden können. 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 der chrome.contextMenus
API von Chromium. Diese Dokumentation ist von context_menus.json
im Chromium-Code abgeleitet.