chrome.contextMenus

Beschreibung

Verwenden Sie die chrome.contextMenus API, um Elemente zum Kontextmenü von Google Chrome hinzuzufügen. Sie können auswählen, für welche Objekttypen die Elemente im Kontextmenü gelten, z. B. Bilder, Hyperlinks und Seiten.

Berechtigungen

contextMenus

Du musst die Berechtigung „"contextMenus"“ im Manifest deiner Erweiterung deklarieren, um die API nutzen zu können. Außerdem sollten Sie neben dem Menüpunkt ein Symbol mit 16 × 16 Pixel angeben, das angezeigt werden soll. Beispiel:

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

Konzepte und Nutzung

Kontextmenüelemente können in jedem Dokument (oder Frame innerhalb eines Dokuments) erscheinen, auch in den URLs mit file:// oder chrome://. Wenn Sie festlegen möchten, in welchen Dokumenten Ihre Elemente angezeigt werden, geben Sie beim Aufrufen der Methoden create() oder update() das Feld documentUrlPatterns an.

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

Beispiele

Wenn Sie diese API testen möchten, installieren Sie das contextMenus API-Beispiel aus dem Repository chrome-extension-sample.

Typen

ContextType

Chrome 44 und höher

Die verschiedenen Kontexte, in denen ein Menü angezeigt werden kann Die Angabe von „all“ entspricht der Kombination aller anderen Kontexte mit Ausnahme von „Launcher“. Der Kontext „Launcher“ wird nur von Apps unterstützt und wird verwendet, um Menüelemente zum Kontextmenü hinzuzufügen, das angezeigt wird, wenn in der Launcher-Taste, der Taskleiste, der Dockingstation usw. auf das App-Symbol geklickt wird. Je nach Plattform kann es sein, dass die Unterstützung in einem Launcher-Kontextmenü eingeschränkt wird.

Enum

"browser_action"

"page_action"

CreateProperties

Chrome 123 oder höher

Eigenschaften des neuen Kontextmenüelements.

Attribute

  • ausgewählt

    Boolescher Wert optional

    Der Anfangszustand eines Kästchens oder Optionsfelds: true für „ausgewählt“, „false“ für „nicht ausgewählt“. Pro 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

    Beschränkt das Element auf Dokumente oder Frames, deren URL mit einem der angegebenen Muster übereinstimmt. Weitere Informationen zu Musterformaten finden Sie unter Übereinstimmungsmuster.

  • aktiviert

    Boolescher Wert optional

    Gibt an, ob dieser Kontextmenüpunkt aktiviert oder deaktiviert ist. Die Standardeinstellung ist true.

  • id

    String optional

    Die eindeutige ID, die diesem Artikel zugewiesen werden soll. Für Veranstaltungsseiten erforderlich. Darf für diese Erweiterung nicht mit einer anderen ID identisch sein.

  • parentId

    String|Zahl optional

    Die ID eines übergeordneten Menüpunkts. Dadurch wird der Artikel einem zuvor hinzugefügten Element untergeordnet.

  • targetUrlPatterns

    string[] optional

    Ähnlich wie bei documentUrlPatterns werden Filter basierend auf dem Attribut src der Tags img, audio und video sowie des Attributs href von a-Tags gefiltert.

  • Titel

    String optional

    Der im Artikel anzuzeigende Text. Dies ist erforderlich, es sei denn, type ist separator. Wenn der Kontext selection ist, verwenden Sie %s im String, 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üeintrag für die Auswahl „Übersetzen von ‚cool‘ in Pig Latin“.

  • Typ

    ItemType optional

    Die Art des Menüpunkts. Die Standardeinstellung ist normal.

  • sichtbar

    Boolescher Wert optional

    Gibt an, ob das Element im Menü sichtbar ist

  • onclick

    void optional

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

    Die Funktion onclick sieht so aus: 

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

    • Informationen zum angeklickten Artikel und Kontext, in dem der Klick erfolgte

    •  

      Tab

      Die Details des Tabs, auf dem der Klick erfolgte. Dieser Parameter ist für Plattform-Apps nicht vorhanden.

ItemType

Chrome 44 und höher

Die Art des Menüpunkts.

Enum

"normal"

"radio"

OnClickData

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

Attribute

  • ausgewählt

    Boolescher Wert optional

    Eine Markierung, die den Status eines Kästchens oder Optionsfelds nach dem Anklicken angibt.

  • bearbeitbar

    boolean

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

  • frameId

    Nummer optional

    Chrome 51 und höher

    ID des Frames des Elements, in dem auf das Kontextmenü geklickt wurde, wenn es sich in einem Frame befand.

  • frameUrl

    String optional

    URL des Frames des Elements, in dem auf das Kontextmenü geklickt wurde, wenn es sich in einem Frame befand.

  • linkUrl

    String optional

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

  • mediaType

    String optional

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

  • menuItemId

    string|number

    Die ID des Artikels auf der Speisekarte, auf den geklickt wurde.

  • pageUrl

    String optional

    Die URL der Seite, auf der auf das Menü geklickt wurde. Diese Eigenschaft wird nicht festgelegt, wenn der Klick in einem Kontext erfolgte, in dem keine aktuelle Seite vorhanden ist, z. B. in einem Launcher-Kontextmenü.

  • parentMenuItemId

    String|Zahl optional

    Die übergeordnete ID des angeklickten Artikels, falls 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

    Eine Markierung, die den Status eines Kästchens oder Optionsfelds vor dem Anklicken angibt.

Attribute

ACTION_MENU_TOP_LEVEL_LIMIT

Die maximale Anzahl von Erweiterungselementen auf oberster Ebene, die einem Kontextmenü für die Erweiterungsaktionen hinzugefügt werden können. Alle darüber hinausgehenden Elemente 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 erkannt, wenn der Erstellungs-Callback ausgelöst wird. Details finden Sie in runtime.lastError.

Parameter

  • createProperties

    CreateProperties

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • number|string

    Die ID des neu erstellten Elements

remove()

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

Entfernt einen Kontextmenüeintrag.

Parameter

  • menuItemId

    string|number

    Die ID des zu entfernenden Kontextmenüelements.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 123 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

removeAll()

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

Entfernt alle von dieser Erweiterung hinzugefügten Kontextmenüelemente.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 123 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

update()

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

Aktualisiert ein zuvor erstelltes Kontextmenü.

Parameter

  • id

    string|number

    Die ID des Artikels, der aktualisiert werden soll.

  • updateProperties

    Objekt

    Die zu aktualisierenden Attribute. Akzeptiert die gleichen 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 Elements, das zum übergeordneten Element dieses Elements gemacht werden soll Hinweis: Sie können ein Element nicht als untergeordnetes Element eines eigenen Nachfolgerelements festlegen.

    • targetUrlPatterns

      string[] optional

    • Titel

      String optional

    • Typ

      ItemType optional

    • sichtbar

      Boolescher Wert optional

      Chrome 62 und höher

      Gibt an, ob das Element im Menü sichtbar ist

    • onclick

      void optional

      Die Funktion onclick sieht so aus: 

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

      • Chrome 44 und höher
      •  

        Tab

        Chrome 44 und höher

        Die Details des Tabs, auf dem der Klick erfolgte. Dieser Parameter ist für Plattform-Apps nicht vorhanden.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 123 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

onClicked

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

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

Parameter