chrome.contextMenus

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu API chrome.contextMenus, aby dodać elementy do menu kontekstowego Google Chrome. Możesz wybrać typy obiektów, do których mają być stosowane dodatki do menu kontekstowego, np. obrazy, hiperlinki i strony.

Uprawnienia

contextMenus

Wykorzystanie

Elementy menu kontekstowego mogą pojawiać się w każdym dokumencie (lub ramce w dokumencie), nawet w tych z adresami URL file:// lub chrome://. Aby kontrolować, w których dokumentach mogą pojawiać się elementy, określ pole documentUrlPatterns podczas wywoływania metody create() lub update().

Możesz utworzyć dowolną liczbę elementów menu kontekstowego, ale jeśli widoczny jest więcej niż 1 element z rozszerzenia, Google Chrome automatycznie zwija je do jednego menu nadrzędnego.

Plik manifestu

Aby korzystać z interfejsu API, musisz zadeklarować uprawnienie „contextMenus” w pliku manifestu rozszerzenia. Należy też określić ikonę o wymiarach 16 x 16 pikseli, która będzie wyświetlana obok elementu menu. Na przykład:

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

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu contextMenus API z repozytorium chrome-extension-samples.

Typy

ContextType

Chrome 44 lub nowsza wersja

Różne konteksty, w których może pojawić się menu. Wartość „all” odpowiada kombinacji wszystkich innych kontekstów z wyjątkiem „launcher” i „tab”. Kontekst „programu uruchamiającego” jest obsługiwany tylko przez aplikacje i służy do dodawania elementów menu do menu kontekstowego, które pojawia się po kliknięciu ikony aplikacji w programie uruchamiającym, na pasku zadań, w docku itp. Różne platformy mogą nakładać ograniczenia na to, co jest faktycznie obsługiwane w menu kontekstowym programu uruchamiającego.

Typ wyliczeniowy

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
Dotyczy menu kontekstowego działania rozszerzenia (ikony na pasku narzędzi).

"tab"
Dotyczy menu kontekstowego karty na pasku kart.

CreateProperties

Chrome 123 lub nowsza wersja

Właściwości nowego elementu menu kontekstowego.

Właściwości

  • zaznaczono

    boolean opcjonalne

    Początkowy stan pola wyboru lub przycisku: true w przypadku zaznaczenia, false w przypadku braku zaznaczenia. W danej grupie można wybrać tylko 1 przycisk opcji naraz.

  • konteksty

    [ContextType, ...ContextType[]] opcjonalny

    Lista kontekstów, w których pojawi się ten element menu. Domyślna wartość to ['page'].

  • documentUrlPatterns

    string[] opcjonalne

    Ogranicza element, aby był stosowany tylko do dokumentów lub ramek, których adres URL pasuje do jednego z podanych wzorców. Szczegółowe informacje o formatach wzorców znajdziesz w artykule Wzorce dopasowania.

  • aktywne

    boolean opcjonalne

    Czy ta pozycja menu kontekstowego jest włączona czy wyłączona. Domyślna wartość to true.

  • id

    ciąg znaków opcjonalny

    Unikalny identyfikator, który ma zostać przypisany do tego elementu. Obowiązkowy w przypadku stron wydarzeń. Nie może być taki sam jak inny identyfikator tego rozszerzenia.

  • parentId

    string | number opcjonalne

    Identyfikator nadrzędnego elementu menu. Dzięki temu element staje się elementem podrzędnym wcześniej dodanego elementu.

  • targetUrlPatterns

    string[] opcjonalne

    Podobnie jak documentUrlPatterns, filtruje na podstawie atrybutu src tagów img, audio i video oraz atrybutu href tagów a.

  • tytuł

    ciąg znaków opcjonalny

    Tekst do wyświetlenia w elemencie. Jest on wymagany, chyba że type to separator. Gdy kontekst to selection, użyj %s w ciągu znaków, aby wyświetlić zaznaczony tekst. Jeśli na przykład wartość tego parametru to „Przetłumacz „%s” na świńską łacinę”, a użytkownik wybierze słowo „fajny”, element menu kontekstowego dla zaznaczenia będzie miał postać „Przetłumacz „fajny” na świńską łacinę”.

  • typ

    ItemType opcjonalny

    Typ pozycji menu. Domyślna wartość to normal.

  • widoczna

    boolean opcjonalne

    Określa, czy element jest widoczny w menu.

  • onclick

    void optional

    Funkcja wywoływana po kliknięciu elementu menu. Ta funkcja nie jest dostępna w skrypcie service worker. Zamiast tego należy zarejestrować detektor dla contextMenus.onClicked.

    Funkcja onclick wygląda tak:

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

    • informacje

      OnClickData

      Informacje o klikniętym elemencie i kontekście, w którym nastąpiło kliknięcie.

    • karta

      Tabulator

      Szczegóły karty, na której nastąpiło kliknięcie. Ten parametr nie występuje w przypadku aplikacji platformy.

ItemType

Chrome 44 lub nowsza wersja

Typ pozycji menu.

Typ wyliczeniowy

"normal"

"checkbox"

"radio"

"separator"

OnClickData

Informacje wysyłane po kliknięciu elementu menu kontekstowego.

Właściwości

  • zaznaczono

    boolean opcjonalne

    Flaga wskazująca stan pola wyboru lub przycisku opcji po kliknięciu.

  • do edycji

    wartość logiczna

    Flaga wskazująca, czy element można edytować (pole tekstowe, obszar tekstowy itp.).

  • frameId

    number optional

    Chrome 51 lub nowsza wersja

    Identyfikator ramki elementu, w którym kliknięto menu kontekstowe, jeśli znajdował się on w ramce.

  • frameUrl

    ciąg znaków opcjonalny

    Adres URL ramki elementu, w którym kliknięto menu kontekstowe, jeśli znajdował się on w ramce.

  • linkUrl

    ciąg znaków opcjonalny

    Jeśli element jest linkiem, adres URL, do którego prowadzi.

  • mediaType

    ciąg znaków opcjonalny

    Jedna z wartości: „image”, „video” lub „audio”, jeśli menu kontekstowe zostało aktywowane na jednym z tych typów elementów.

  • menuItemId

    ciąg znaków | liczba

    Identyfikator klikniętej pozycji menu.

  • pageUrl

    ciąg znaków opcjonalny

    Adres URL strony, na której kliknięto element menu. Ta właściwość nie jest ustawiana, jeśli kliknięcie nastąpiło w kontekście, w którym nie ma bieżącej strony, np. w menu kontekstowym programu uruchamiającego.

  • parentMenuItemId

    string | number opcjonalne

    Identyfikator nadrzędny klikniętego elementu (jeśli jest dostępny).

  • selectionText

    ciąg znaków opcjonalny

    Tekst wyboru kontekstu (jeśli występuje).

  • srcUrl

    ciąg znaków opcjonalny

    Będzie obecny w przypadku elementów z adresem URL „src”.

  • wasChecked

    boolean opcjonalne

    Flaga wskazująca stan pola wyboru lub przycisku opcji przed kliknięciem.

Właściwości

ACTION_MENU_TOP_LEVEL_LIMIT

Maksymalna liczba elementów rozszerzenia najwyższego poziomu, które można dodać do menu kontekstowego działania rozszerzenia. Wszystkie elementy powyżej tego limitu będą ignorowane.

Wartość

6

Metody

create()

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

Tworzy nowy element menu kontekstowego. Jeśli podczas tworzenia wystąpi błąd, może on nie zostać wykryty, dopóki nie zostanie wywołane wywołanie zwrotne tworzenia. Szczegóły znajdziesz w runtime.lastError.

Parametry

  • createProperties

    CreateProperties

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • number | string

    Identyfikator nowo utworzonego elementu.

remove()

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

Usuwa element menu kontekstowego.

Parametry

  • menuItemId

    ciąg znaków | liczba

    Identyfikator elementu menu kontekstowego do usunięcia.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 123 lub nowsza wersja

    Rozwiązuje problem po usunięciu menu kontekstowego.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

removeAll()

Obietnica 
chrome.contextMenus.removeAll(
  callback?: function,
): Promise<void>

Usuwa wszystkie elementy menu kontekstowego dodane przez to rozszerzenie.

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 123 lub nowsza wersja

    Zostanie rozwiązany po zakończeniu usuwania.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

update()

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

Aktualizuje wcześniej utworzony element menu kontekstowego.

Parametry

  • id

    ciąg znaków | liczba

    Identyfikator elementu, który chcesz zaktualizować.

  • updateProperties

    obiekt

    Właściwości do zaktualizowania. Akceptuje te same wartości co funkcja contextMenus.create.

    • zaznaczono

      boolean opcjonalne

    • konteksty

      [ContextType, ...ContextType[]] opcjonalny

    • documentUrlPatterns

      string[] opcjonalne

    • aktywne

      boolean opcjonalne

    • parentId

      string | number opcjonalne

      Identyfikator elementu, który ma być elementem nadrzędnym tego elementu. Uwaga: nie możesz ustawić elementu jako elementu podrzędnego jego własnego elementu podrzędnego.

    • targetUrlPatterns

      string[] opcjonalne

    • tytuł

      ciąg znaków opcjonalny

    • typ

      ItemType opcjonalny

    • widoczna

      boolean opcjonalne

      Chrome 62 lub nowsza wersja

      Określa, czy element jest widoczny w menu.

    • onclick

      void optional

      Funkcja onclick wygląda tak:

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

      • informacje

        OnClickData

        Chrome 44 lub nowsza wersja
      • karta

        Tabulator

        Chrome 44 lub nowsza wersja

        Szczegóły karty, na której nastąpiło kliknięcie. Ten parametr nie występuje w przypadku aplikacji platformy.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 123 lub nowsza wersja

    Rozwiązuje problem po zaktualizowaniu menu kontekstowego.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onClicked

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

Uruchamiane po kliknięciu elementu menu kontekstowego.

Parametry