menus.create()
Erstellt ein Menüelement unter Verwendung 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 Erfolg oder Misserfolg zu kommunizieren. Der Rückgabewert ist die ID des neuen Elements.
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"]
) unter Verwendung des contextMenus
-Namespaces zu erstellen.
Erstellen von Menüs in persistenter und nicht-persistenter Erweiterungen
Wie Sie Menüelemente erstellen, hängt davon ab, ob Ihre Erweiterung folgende verwendet:
- nicht-persistente Hintergrundseiten (eine Ereignisseite), bei denen Menüs über Neustarts des Browsers und der Erweiterung hinweg erhalten bleiben. 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, was bei einem Aufruf auf oberster Ebene geschehen würde.- persistente Hintergrundseiten:
- in Chrome bleiben Menüelemente von persistenten Hintergrundseiten erhalten. Erstellen Sie Ihre Menüs in einem
runtime.onInstalled
-Listener.- in Firefox bleiben Menüelemente von persistenten Hintergrundseiten niemals erhalten. Rufen Sie
menus.create
bedingungslos von oberster Ebene auf, um die Menüelemente zu registrieren.Siehe Initialisieren der Erweiterung auf der Seite über Hintergrundskripte und Ereignisgesteuerte Hintergrundskripte im Erweiterungs-Workshop für weitere Informationen.
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 Radioelements:true
für ausgewählt undfalse
für nicht ausgewählt. In einer gegebenen Gruppe von Radioelementen kann jeweils nur ein Element ausgewählt werden. command
Optional-
string
. Zeichenkette, 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-Aktion der Erweiterung, wobei deren Popup geöffnet wird, falls vorhanden (nur Manifest V2)"_execute_action"
: simuliert einen Klick auf die Aktion der Erweiterung, wobei deren Popup geöffnet wird, falls vorhanden (nur Manifest V3)"_execute_page_action"
: simuliert einen Klick auf die Seitenaktion der Erweiterung, wobei deren Popup geöffnet wird"_execute_sidebar_action"
: öffnet die Seitenleiste der Erweiterung
Detaillierte Informationen finden Sie in der Dokumentation zu speziellen Shortcuts im manifest.json-Schlüssel
commands
.Wenn einer der anerkannten Werte angegeben wird, löst das Klicken auf das Element nicht das
menus.onClicked
-Ereignis aus; stattdessen wird die Standardaktion ausgelöst, z.B. das Öffnen eines Pop-ups. Andernfalls löst das Klicken auf das Elementmenus.onClicked
aus, und das Ereignis kann verwendet werden, um ein Fallback-Verhalten zu implementieren. contexts
Optional-
array
of
. Array von Kontexten, in denen dieses Menüelement erscheinen wird. Wenn diese Option weggelassen wird:menus.ContextType
- wenn das übergeordnete Element Kontexte festgelegt hat, erbt dieses Element die Kontexte des übergeordneten Elements
- andernfalls wird das Element mit einem Kontextarray von ["page"] versehen.
documentUrlPatterns
Optional-
array
vonstring
. Ermöglicht, das Element so einzuschränken, dass es nur auf Dokumente angewendet wird, deren URL mit einem der angegebenen Übereinstimmungsmuster übereinstimmt. Dies gilt auch für Frames. enabled
Optional-
boolean
. Ob dieses Menüelement aktiviert oder deaktiviert ist. Standardmäßigtrue
. icons
Optional-
object
. Eine oder mehrere benutzerdefinierte Symbole, die neben dem Element angezeigt werden. 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 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 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 übergeordnete Menüelement verwendet die im Manifest angegebenen Symbole anstatt der mit diesem Schlüssel angegebenen.
id
Optional-
string
. Die eindeutige ID, die diesem Element zugewiesen werden soll. Ist für nicht-persistente Hintergrund (Ereignis)seiten in Manifest V2 und in 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 verwenden: Sie sollten stattdessen 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 können Sie basierend auf demhref
von Ankertags und demsrc
-Attribut von<img>/<audio>/<video>
-Tags filtern. Dieser Parameter unterstützt jedes URL-Schema, selbst solche, die normalerweise nicht in einem Übereinstimmungsmuster erlaubt sind. title
Optional-
string
. Der im Element anzuzeigende Text. Obligatorisch, es sei denn,type
ist "separator".Sie können "
%s
" in der Zeichenkette verwenden. Wenn Sie dies in einem Menüelement tun und beim Anzeigen des Menüs im Dokument einige Texte ausgewählt sind, wird der ausgewählte Text in den Titel interpoliert. Wenn dertitle
beispielsweise "Translate '%s' to Pig Latin" lautet und der Benutzer das Wort "cool" auswählt, dann das Menü aktiviert, dann lautet der Titel des Menüelements: "Translate 'cool' to Pig Latin".Wenn der Titel ein kaufmännisches Und-Zeichen "&" enthält, wird das nächste Zeichen als Zugriffstaste für das Element verwendet, und das kaufmännische Und-Zeichen wird nicht angezeigt. Ausnahmen hiervon sind:
- Wenn das nächste Zeichen ebenfalls ein kaufmännisches Und-Zeichen ist: Dann wird ein einzelnes kaufmännisches Und-Zeichen angezeigt und keine Zugriffstaste gesetzt. In Wirklichkeit wird "&&" verwendet, um ein einzelnes kaufmännisches Und-Zeichen anzuzeigen.
- Wenn die nächsten Zeichen die Interpolationsanweisung "%s" sind: dann wird das kaufmännische Und-Zeichen nicht angezeigt und keine Zugriffstaste gesetzt.
- Wenn das kaufmännische Und-Zeichen das letzte Zeichen im Titel ist: dann wird das kaufmännische Und-Zeichen nicht angezeigt und keine Zugriffstaste gesetzt.
Nur das erste kaufmännische Und-Zeichen wird verwendet, um eine Zugriffstaste zu setzen: Nachfolgende kaufmännische Und-Zeichen werden nicht angezeigt, aber keine Tasten gesetzt. Also wird "&A and &B" als "A and B" angezeigt und "A" als Zugriffstaste gesetzt.
In einigen lokalisierten Versionen von Firefox (Japanisch und Chinesisch) wird die Zugriffstaste in Klammern gesetzt und dem Menülabel hinzugefügt, es sei denn, der Menütitel endet selbst bereits mit der Zugriffstaste (
"toolkit(&K)"
zum Beispiel). Weitere Details finden Sie im Firefox-Bug 1647373. type
Optional-
. Der Typ des Menüelements: "normal", "checkbox", "radio", "separator". Standardmäßig "normal".menus.ItemType
viewTypes
Optional-
. Liste der Ansichtsarten, in denen das Menüelement angezeigt wird. Standardmäßig wird es in jeder Ansicht angezeigt, auch in solchen ohneextension.ViewType
viewType
. 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 beim Erstellen 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 der 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 ein grüner oder blauer Rahmen auf die Seite angewendet werden soll. Beachten Sie, dass dieses Beispiel die Berechtigung activeTab 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,
});
}
});
Beispiel-Erweiterungen
Browser-Kompatibilität
BCD tables only load in the browser
Hinweis: Diese API basiert auf der chrome.contextMenus
-API von Chromium. Diese Dokumentation basiert auf context_menus.json
im Chromium-Code.