chrome.contextMenus

Opis

Użyj interfejsu chrome.contextMenus API, aby dodać elementy do menu kontekstowego Google Chrome. Możesz wybrać, do jakich typów obiektów mają być stosowane dodatki do menu kontekstowego, np. do obrazów, hiperlinków i stron.

Uprawnienia

contextMenus

Wykorzystanie

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

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

Plik manifestu

Aby używać interfejsu API, musisz zadeklarować uprawnienie „contextMenus” w pliku manifestu rozszerzenia. Musisz też określić ikonę o rozmiarze 16 × 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 API contextMenus z repozytorium chrome-extension-samples.

Typy

ContextType

Chrome 44 lub nowsza

Różne konteksty, w których może pojawić się menu. Określenie wartości „all” jest równoznaczne z połączeniem wszystkich innych kontekstów z wyjątkiem „launcher”. Kontekst „launcher” 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”

„browser_action”

„page_action”

„action”

„tab”

CreateProperties

Chrome 123 lub nowsza

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

Właściwości

  • zaznaczono

    wartość logiczna opcjonalna

    Stan początkowy pola wyboru lub przycisku: true – zaznaczony, false – odznaczony. W danej grupie można wybrać tylko jedną opcję.

  • kontekstów,

    [ContextType, ...ContextType[]] opcjonalnie

    Lista kontekstów, w których będzie wyświetlana ta pozycja menu. Domyślna wartość to ['page'].

  • documentUrlPatterns

    string[] opcjonalny

    Ogranicza element tak, 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.

  • włączone

    wartość logiczna opcjonalna

    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. Wymagany w przypadku stron z informacjami o wydarzeniach. Nie może być taki sam jak inny identyfikator tego rozszerzenia.

  • parentId

    string | number opcjonalnie

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

  • targetUrlPatterns

    string[] opcjonalny

    Podobnie jak w przypadku 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 atrybut type ma wartość separator. Gdy kontekst to selection, użyj w ciągu znaków symbolu %s, aby wyświetlić wybrany tekst. Jeśli na przykład wartość tego parametru to „Przetłumacz „%s” na język Pig Latin”, a użytkownik wybierze słowo „cool”, element menu kontekstowego dla tego wyboru będzie brzmiał „Przetłumacz „cool” na język Pig Latin”.

  • typ

    ItemType opcjonalny

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

  • widoczna

    wartość logiczna opcjonalna

    Określa, czy element jest widoczny w menu.

  • onclick

    void optional

    Funkcja, która jest wywoływana po kliknięciu elementu menu. Nie jest to dostępne w skrypcie service worker. Zamiast tego zarejestruj odbiornik dla zdarzenia 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

      Karta

      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

Typ elementu menu.

Typ wyliczeniowy

„normal”

„checkbox”

„radio”

"separator"

OnClickData

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

Właściwości

  • zaznaczono

    wartość logiczna opcjonalna

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

  • do edycji

    Wartość logiczna

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

  • frameId

    number opcjonalny

    Chrome 51 lub nowsza

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

  • frameUrl

    ciąg znaków opcjonalny

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

  • linkUrl

    ciąg znaków opcjonalny

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

  • mediaType

    ciąg znaków opcjonalny

    Wartość „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ętego elementu 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 opcjonalnie

    Identyfikator nadrzędny klikniętego elementu (jeśli występuje).

  • selectionText

    ciąg znaków opcjonalny

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

  • srcUrl

    ciąg znaków opcjonalny

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

  • wasChecked

    wartość logiczna opcjonalna

    Flaga wskazująca stan pola wyboru lub 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 związanego z rozszerzeniem. 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 zostać wykryty dopiero po wywołaniu zwrotnym tworzenia. Szczegóły znajdziesz w runtime.lastError.

Parametry

  • createProperties

    CreateProperties

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • liczba | ciąg znaków

    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

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 123 lub nowsza

    Zwraca wartość, gdy menu kontekstowe zostanie usunięte.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą 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

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 123 lub nowsza

    Zwraca wartość po zakończeniu usuwania.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

update()

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

Aktualizuje utworzony wcześniej element menu kontekstowego.

Parametry

  • id

    ciąg znaków | liczba

    Identyfikator elementu do zaktualizowania.

  • updateProperties

    obiekt

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

    • zaznaczono

      wartość logiczna opcjonalna

    • kontekstów,

      [ContextType, ...ContextType[]] opcjonalnie

    • documentUrlPatterns

      string[] opcjonalny

    • włączone

      wartość logiczna opcjonalna

    • parentId

      string | number opcjonalnie

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

    • targetUrlPatterns

      string[] opcjonalny

    • tytuł

      ciąg znaków opcjonalny

    • typ

      ItemType opcjonalny

    • widoczna

      wartość logiczna opcjonalna

      Chrome 62 lub nowsza

      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
      • karta

        Karta

        Chrome 44 lub nowsza

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

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 123 lub nowsza

    Rozwiązuje się, gdy menu kontekstowe zostanie zaktualizowane.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onClicked

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

Uruchamiane po kliknięciu elementu menu kontekstowego.

Parametry