chrome.contextMenus

Beschreibung

Verwende die chrome.contextMenus API, um dem Kontextmenü von Google Chrome Elemente hinzuzufügen. Sie können auswählen, für welche Typen von Objekten Ihre Kontextmenüs gelten sollen, z. B. Bilder, Hyperlinks und Seiten.

Berechtigungen

contextMenus

Du musst die Berechtigung "contextMenus" im Manifest deiner Erweiterung deklarieren, um die API verwenden zu können. Außerdem sollten Sie ein 16 x 16 Pixel großes Symbol neben Ihrem Menüpunkt angeben. 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 innerhalb eines Dokuments) angezeigt werden, auch in solchen mit „file://“. oder „chrome://“. Um zu steuern, in welchen Dokumenten Ihre Elemente erscheinen können, geben Sie documentUrlPatterns, wenn Sie die Methoden create() oder update() aufrufen.

Sie können beliebig viele Kontextmenüelemente erstellen. Wenn jedoch mehrere Elemente aus Ihrer Erweiterung angezeigt wird, werden sie in Google Chrome automatisch zu einem übergeordneten Menü zusammengefasst.

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das Beispiel für diecontextMenus API aus chrome-extension-samples. zu erstellen.

Typen

ContextType

Chrome (ab Version 44)

Die verschiedenen Kontexte, in denen ein Menü angezeigt werden kann. "all" angeben entspricht der Kombination aller anderen Kontexte außer „Launcher“. Die „Übersicht“ Kontext wird nur von Apps unterstützt und wird verwendet, um Menüpunkte zum Kontextmenü hinzuzufügen, das angezeigt wird, wenn auf das App-Symbol im Launcher, in der Taskleiste, im Dock usw. geklickt wird. Je nach Plattform gibt es möglicherweise Einschränkungen dafür, was im Kontextmenü des Launchers tatsächlich unterstützt wird.

Enum

"alle"

„Seite“

"Frame"

"Auswahl"

"Link"

"bearbeitbar"

"Bild"

"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

    Anfangszustand 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

    Beschränkt das Element, sodass es nur auf Dokumente oder Frames angewendet wird, 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 Element zugewiesen werden soll. Obligatorisch für Veranstaltungsseiten. Darf nicht mit einer anderen ID für diese Erweiterung identisch sein.

  • parentId

    string | Zahl optional

    Die ID eines übergeordneten Menüelements. wird das Element einem zuvor hinzugefügten Element untergeordnet.

  • targetUrlPatterns

    string[] optional

    Ähnlich wie documentUrlPatterns, Filter, die auf dem Attribut src von img-, audio- und video-Tags und dem href-Attribut von a-Tags basieren.

  • Titel

    String optional

    Der Text, der im Element angezeigt werden soll. Dies ist erforderlich, es sei denn, type ist separator. Wenn der Kontext selection ist, verwenden Sie im String %s, um den ausgewählten Text anzuzeigen. Lautet der Wert dieses Parameters beispielsweise "%s" übersetzen, zu Pig Latin“ und der Nutzer das Wort „cool“ auswählt, ist das Kontextmenüelement für die Auswahl „Übersetze ‚cool‘“. zu Pig Latin“.

  • Typ

    ItemType optional

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

  • sichtbar

    Boolescher Wert optional

    Gibt an, ob das Element im Menü sichtbar ist.

  • onclick

    void optional

    Eine Funktion, die beim Anklicken des Menüelements zurückgerufen wird. Dies ist innerhalb eines Service Workers nicht verfügbar. Registrieren Sie stattdessen einen Listener für contextMenus.onClicked.

    Die Funktion onclick sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

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

    • Tabulatortaste

      Tab

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

ItemType

Chrome (ab Version 44)

Die Art des Menüelements.

Enum

"normal"

"Kästchen"

"Radio"

"Trennzeichen"

OnClickData

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

Attribute

  • ausgewählt

    Boolescher Wert optional

    Eine Markierung, die den Status eines Kontrollkästchens oder Optionsfelds nach einem Klick angibt.

  • bearbeitbar

    boolean

    Eine Markierung, die angibt, ob das Element bearbeitbar ist (Texteingabe, Textbereich usw.).

  • frameId

    Zahl optional

    Chrome 51 oder höher

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

  • frameUrl

    String optional

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

  • linkUrl

    String optional

    Wenn das Element ein Link ist, 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 | Nummer

    Die ID des angeklickten Menüpunkts.

  • pageUrl

    String optional

    Die URL der Seite, auf der auf den Menüpunkt geklickt wurde. Diese Eigenschaft ist nicht festgelegt, wenn der Klick in einem Kontext erfolgte, in dem keine aktuelle Seite vorhanden ist, z. B. in einem Kontextmenü des Launchers.

  • parentMenuItemId

    string | Zahl optional

    Gegebenenfalls die übergeordnete ID des angeklickten Artikels.

  • selectionText

    String optional

    Der Text für die Kontextauswahl, falls vorhanden.

  • srcUrl

    String optional

    Wird für Elemente mit einem "src"-Attribut vorhanden sein URL

  • 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ü einer Erweiterungsaktion hinzugefügt werden können. Alle Elemente, die darüber hinausgehen, 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 findest du in runtime.lastError.

Parameter

  • createProperties

    CreateProperties

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Zahl | String

    Die ID des neu erstellten Elements.

remove()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

Entfernt einen Kontextmenüeintrag.

Parameter

  • menuItemId

    string | Nummer

    Die ID des Kontextmenüelements, das entfernt werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 123 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

removeAll()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 123 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

update()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

Aktualisiert einen zuvor erstellten Kontextmenüeintrag.

Parameter

  • id

    string | Nummer

    Die ID des zu aktualisierenden Elements.

  • updateProperties

    Objekt

    Die zu aktualisierenden Eigenschaften. 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

      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: <ph type="x-smartling-placeholder"></ph>

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

      • Chrome (ab Version 44)
      • Tabulatortaste

        Tab

        Chrome (ab Version 44)

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 123 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

Ereignisse

onClicked

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (info: OnClickData, tab?: tabs.Tab) => void