chrome.contextMenus

Beschreibung

Mit der chrome.contextMenus API können Sie dem Kontextmenü von Google Chrome Elemente hinzufügen. Sie können auswählen, auf welche Arten von Objekten die Ergänzungen im Kontextmenü angewendet werden sollen, z. B. auf Bilder, Hyperlinks und Seiten.

Berechtigungen

contextMenus

Sie müssen die Berechtigung "contextMenus" im Manifest Ihrer Erweiterung deklarieren, um die API verwenden zu können. Außerdem solltest du ein Symbol mit einer Größe von 16 × 16 Pixeln angeben, das neben dem Menüpunkt angezeigt werden soll. Beispiel:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

Konzepte und Verwendung

Kontextmenüelemente können in jedem Dokument (oder Frame in einem Dokument) angezeigt werden, auch in Dokumenten mit file://- oder chrome://-URLs. Wenn Sie festlegen möchten, in welchen Dokumenten Ihre Elemente angezeigt werden können, geben Sie das Feld documentUrlPatterns an, wenn Sie die Methoden create() oder update() aufrufen.

Sie können beliebig viele Kontextmenüpunkte erstellen. Wenn jedoch mehrere Elemente Ihrer Erweiterung gleichzeitig sichtbar sind, werden sie in Google Chrome automatisch in einem übergeordneten Menü minimiert.

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das Beispiel für die contextMenus API aus dem Repository chrome-extension-samples.

Typen

ContextType

Chrome 44 und höher

Die verschiedenen Kontexte, in denen ein Menü angezeigt werden kann. Die Angabe von „alle“ entspricht der Kombination aller anderen Kontexte mit Ausnahme von „Launcher“. Der Kontext „Launcher“ wird nur von Apps unterstützt und dient dazu, dem Kontextmenü, das beim Klicken auf das App-Symbol im Launcher/in der Taskleiste/im Dock usw. angezeigt wird, Menüpunkte hinzuzufügen. Auf verschiedenen Plattformen gelten möglicherweise Einschränkungen für die tatsächlich in einem Launcher-Kontextmenü unterstützten Funktionen.

Enum

"alle"

"page"

"frame"

„selection“

"link"

„editable“

"image"

"video"

„audio“

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 und höher

Eigenschaften des neuen Kontextmenüelements.

Attribute

  • ausgewählt

    boolescher Wert optional

    Der Anfangsstatus eines Kästchens oder Optionsfelds: true für ausgewählt, false für nicht ausgewählt. In einer Gruppe kann jeweils nur ein Optionsfeld ausgewählt werden.

  • contexts

    [ContextType, ...ContextType[]] optional

    Liste der Kontexte, in denen dieser Menüpunkt angezeigt wird. Die Standardeinstellung ist ['page'].

  • documentUrlPatterns

    string[] optional

    Das Element wird nur auf Dokumente oder Frames angewendet, deren URL mit einem der angegebenen Muster übereinstimmt. Weitere Informationen zu Musterformaten finden Sie unter Übereinstimmungsmuster.

  • aktiviert

    boolescher Wert optional

    Gibt an, ob dieses Kontextmenüelement aktiviert oder deaktiviert ist. Die Standardeinstellung ist true.

  • id

    String optional

    Die eindeutige ID, die diesem Artikel zugewiesen werden soll. Für Veranstaltungsseiten erforderlich. Sie darf nicht mit einer anderen ID für diese Erweiterung übereinstimmen.

  • parentId

    String | Zahl optional

    Die ID eines übergeordneten Menüpunkts. Dadurch wird das Element zu einem untergeordneten Element eines zuvor hinzugefügten Elements.

  • targetUrlPatterns

    string[] optional

    Ähnlich wie bei documentUrlPatterns basieren diese Filter auf dem src-Attribut der Tags img, audio und video sowie dem href-Attribut der Tags a.

  • Titel

    String optional

    Der im Artikel anzuzeigende Text. Diese Angabe ist erforderlich, es sei denn, type ist separator. Wenn der Kontext selection ist, verwenden Sie %s innerhalb des Strings, um den ausgewählten Text anzuzeigen. Wenn der Wert dieses Parameters beispielsweise „%s in Pig Latin übersetzen“ lautet und der Nutzer das Wort „cool“ auswählt, lautet der Kontextmenüpunkt für die Auswahl „Cool in Pig Latin übersetzen“.

  • Typ

    ItemType optional

    Der Typ des Menüpunkts. Die Standardeinstellung ist normal.

  • sichtbar

    boolescher Wert optional

    Gibt an, ob der Artikel im Menü angezeigt wird.

  • onclick

    void optional

    Eine Funktion, die aufgerufen wird, wenn auf den Menüpunkt geklickt wird. Diese Funktion ist in einem Service Worker nicht verfügbar. Stattdessen sollten Sie einen Listener für contextMenus.onClicked registrieren.

    Die onclick-Funktion sieht so aus: 

    (info: OnClickData, tab: Tab) => {...}

    • Informationen zum angeklickten Element und zum Kontext, in dem der Klick erfolgt ist.

    • Tabulatortaste

      Tab

      Die Details zum Tab, auf dem der Klick erfolgt ist. Dieser Parameter ist für Plattform-Apps nicht vorhanden.

ItemType

Chrome 44 und höher

Der Typ des Menüpunkts.

Enum

„normal“

„checkbox“

"radio"

"separator"

OnClickData

Informationen, die gesendet werden, wenn auf einen Kontextmenüpunkt geklickt wird.

Attribute

  • ausgewählt

    boolescher Wert optional

    Ein Flag, das den Status eines Kästchens oder Optionsfelds angibt, nachdem darauf geklickt wurde.

  • bearbeitbar

    boolean

    Ein Flag, das angibt, ob das Element bearbeitbar ist (Texteingabe, Textfeld usw.).

  • frameId

    number optional

    Chrome 51 und höher

    Die ID des Frames des Elements, auf das das Kontextmenü angeklickt wurde, falls es sich in einem Frame befand.

  • frameUrl

    String optional

    Die URL des Frames des Elements, auf das das Kontextmenü angeklickt wurde, sofern es sich in einem Frame befand.

  • linkUrl

    String optional

    Wenn es sich bei dem Element um einen Link handelt, die URL, auf die er verweist.

  • mediaType

    String optional

    „image“, „video“ oder „audio“, wenn das Kontextmenü für einen dieser Elementtypen aktiviert wurde.

  • menuItemId

    String | Zahl

    Die ID des angeklickten Menüpunkts.

  • pageUrl

    String optional

    Die URL der Seite, auf der auf den Menüpunkt geklickt wurde. Diese Property wird nicht festgelegt, wenn der Klick in einem Kontext erfolgt, in dem es keine aktuelle Seite gibt, z. B. in einem Launcher-Kontextmenü.

  • parentMenuItemId

    String | Zahl optional

    Die übergeordnete ID des angeklickten Elements, sofern vorhanden.

  • selectionText

    String optional

    Der Text für die Kontextauswahl, falls vorhanden.

  • srcUrl

    String optional

    Ist für Elemente mit einer „src“-URL vorhanden.

  • wasChecked

    boolescher Wert optional

    Ein Flag, das den Status eines Kästchens oder Optionsfelds angibt, bevor darauf geklickt wurde.

Attribute

ACTION_MENU_TOP_LEVEL_LIMIT

Die maximale Anzahl von Erweiterungselementen der obersten Ebene, die einem Kontextmenü für Erweiterungsaktionen hinzugefügt werden können. Alle Elemente darüber hinaus werden ignoriert.

Wert

6

Methoden

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

Erstellt ein neues Kontextmenüelement. Wenn während der Erstellung ein Fehler auftritt, wird er möglicherweise erst beim Auslösen des Rückrufs erkannt. Details findest du unter runtime.lastError.

Parameter

  • createProperties

    CreateProperties

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Zahl | String

    Die ID des neu erstellten Artikels.

remove()

Promise 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

Entfernt ein Kontextmenüelement.

Parameter

  • menuItemId

    String | Zahl

    Die ID des zu entfernenden Kontextmenüpunkts.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 123 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
)

Entfernt alle Kontextmenüelemente, die von dieser Erweiterung hinzugefügt wurden.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 123 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

update()

Promise 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

Aktualisiert ein zuvor erstelltes Kontextmenüelement.

Parameter

  • id

    String | Zahl

    Die ID des zu aktualisierenden Artikels.

  • updateProperties

    Objekt

    Die zu aktualisierenden Properties. Akzeptiert dieselben Werte wie die Funktion contextMenus.create.

    • ausgewählt

      boolescher Wert optional

    • contexts

      [ContextType, ...ContextType[]] optional

    • documentUrlPatterns

      string[] optional

    • aktiviert

      boolescher Wert optional

    • parentId

      String | Zahl optional

      Die ID des Artikels, der übergeordnetes Element dieses Artikels werden soll. Hinweis: Sie können ein Element nicht so festlegen, dass es ein untergeordnetes Element seines eigenen Nachkommens wird.

    • targetUrlPatterns

      string[] optional

    • Titel

      String optional

    • Typ

      ItemType optional

    • sichtbar

      boolescher Wert optional

      Chrome 62 und höher

      Gibt an, ob der Artikel im Menü angezeigt wird.

    • onclick

      void optional

      Die onclick-Funktion sieht so aus: 

      (info: OnClickData, tab: Tab) => {...}

      • Chrome 44 und höher
      • Tabulatortaste

        Tab

        Chrome 44 und höher

        Die Details zum Tab, auf dem der Klick erfolgt ist. Dieser Parameter ist für Plattform-Apps nicht vorhanden.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Chrome 123 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

Ereignisse

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

Wird ausgelöst, wenn auf ein Element im Kontextmenü geklickt wird.

Parameter