chrome.contextMenus

Opis

Użyj interfejsu API chrome.contextMenus, aby dodać elementy do menu kontekstowego Google Chrome. Możesz wybrać, do jakich obiektów mają się odnosić elementy menu kontekstowego, np. obrazy, hiperlinki i strony.

Uprawnienia

contextMenus

Aby korzystać z interfejsu API, musisz zadeklarować uprawnienie "contextMenus" w pliku manifestu rozszerzenia. Musisz też podać ikonę o wymiarach 16 x 16 pikseli, która będzie wyświetlana obok pozycji menu. Na przykład:

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

Pojęcia i zastosowanie

Elementy menu kontekstowego mogą pojawiać się w dowolnym dokumencie (lub ramce w dokumencie), nawet w przypadku adresów URL file:// lub chrome://. Aby kontrolować, w których dokumentach mogą pojawiać się elementy, określ pole documentUrlPatterns podczas wywoływania metod create() lub update().

Możesz utworzyć dowolną liczbę elementów menu kontekstowego, ale jeśli więcej niż 1 element z Twojego rozszerzenia jest widoczne jednocześnie, Google Chrome automatycznie je złączy w jedno menu nadrzędne.

Przykłady

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

Typy

ContextType

Chrome 44 lub nowszy

Różne konteksty, w których może się wyświetlać menu. Podanie wartości „all” (wszystko) jest równoważne kombinacji wszystkich kontekstów z wyjątkiem „launcher” (uruchomik). Kontekst „launchera” 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 menu lub na pasku aplikacji. Różne platformy mogą nakładać ograniczenia na to, co jest obsługiwane w menu kontekstowym.

Typ wyliczeniowy

„all”

„page”

"frame"

„selection”

"link"

„edytowane”

„image”

"video"

„audio”

„launcher”

"browser_action"

"page_action"

„action”

CreateProperties

Chrome 123+

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

Właściwości

  • zaznaczono

    logiczna opcjonalna

    Początkowy stan pola wyboru lub przycisku opcji: true – zaznaczone, false – niezaznaczone. W danej grupie można zaznaczyć tylko 1 przycisk opcji.

  • kontekstów

    [ContextType, ...ContextType[]] opcjonalnie

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

  • documentUrlPatterns

    string[] opcjonalnie

    Ogranicza działanie elementu tylko do dokumentów lub ramek, których adres URL pasuje do jednego z podanych wzorców. Szczegółowe informacje o formatach wzorca znajdziesz w artykule Wzorce dopasowania.

  • włączone

    logiczna opcjonalna

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

  • id

    ciąg znaków opcjonalny

    Unikalny identyfikator do przypisania 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 nadrzędnego elementu menu; dzięki temu element staje się elementem podrzędnym wcześniej dodanego elementu.

  • targetUrlPatterns

    string[] opcjonalnie

    Podobnie jak w przypadku tagu documentUrlPatterns, filtry oparte na atrybucie src tagów img, audio i video oraz atrybucie href tagów a.

  • tytuł

    ciąg znaków opcjonalny

    Tekst do wyświetlenia w elemencie. Jest wymagany, chyba że type = separator. Jeśli kontekst to selection, użyj w ciągu znaków %s, aby wyświetlić wybrany tekst. Jeśli na przykład wartość tego parametru to „Tłumacz '%s' na pig-latin”, a użytkownik wybierze słowo „fajny”, element menu kontekstowego dla tej selekcji to „Tłumacz 'fajny' na pig-latin”.

  • typ

    ItemType opcjonalny

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

  • widoczna

    logiczna opcjonalna

    Określa, czy element jest widoczny w menu.

  • onclick

    void opcjonalny

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

    Funkcja onclick ma postać:

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

    • informacje

      OnClickData

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

    • tabulator

      Tabulator

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

ItemType

Chrome 44 lub nowszy

Typ pozycji menu.

Typ wyliczeniowy

„normal”

"checkbox"

"radio"

„separator”

OnClickData

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

Właściwości

  • zaznaczono

    logiczna opcjonalna

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

  • edytowalny

    wartość logiczna

    Flaga wskazująca, czy element jest edytowalny (pole tekstowe, textarea itp.).

  • frameId

    number opcjonalny

    Chrome 51 lub nowszy

    Identyfikator ramki elementu, w którym kliknięto menu kontekstowe (jeśli była to ramka).

  • frameUrl

    ciąg znaków opcjonalny

    Adres URL ramki elementu, w której kliknięto menu kontekstowe (jeśli element znajdował się 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

    „image” (obraz), „video” (wideo) lub „audio” (dźwięk), jeśli menu kontekstowe zostało aktywowane w przypadku jednego z tych typów elementów.

  • menuItemId

    ciąg | 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 ustawiona, jeśli kliknięcie nastąpiło w kontekście, w którym nie ma bieżącej strony, np. w menu kontekstowym w menu uruchamiania.

  • parentMenuItemId

    string | number opcjonalnie

    Identyfikator nadrzędnego elementu, jeśli występuje, dla klikniętego elementu.

  • selectionText

    ciąg znaków opcjonalny

    Tekst do wyboru kontekstu (jeśli jest dostępny).

  • srcUrl

    ciąg znaków opcjonalny

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

  • wasChecked

    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 na najwyższym poziomie, 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,
)

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

Parametry

  • createProperties

    CreateProperties

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • liczba | ciąg

    Identyfikator nowo utworzonego elementu.

remove()

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

Usuwa element menu kontekstowego.

Parametry

  • menuItemId

    ciąg | liczba

    Identyfikator pozycji menu kontekstowego do usunięcia.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 123+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

removeAll()

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

Usuwa wszystkie elementy menu kontekstowego dodane przez to rozszerzenie.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 123+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

update()

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

Aktualizuje wcześniej utworzony element menu kontekstowego.

Parametry

  • id

    ciąg | liczba

    Identyfikator elementu, który chcesz zaktualizować.

  • updateProperties

    Obiekt

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

    • zaznaczono

      logiczna opcjonalna

    • kontekstów

      [ContextType, ...ContextType[]] opcjonalnie

    • documentUrlPatterns

      string[] opcjonalnie

    • włączone

      logiczna opcjonalna

    • parentId

      string | number opcjonalnie

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

    • targetUrlPatterns

      string[] opcjonalnie

    • tytuł

      ciąg znaków opcjonalny

    • typ

      ItemType opcjonalny

    • widoczna

      logiczna opcjonalna

      Chrome 62 lub nowszy

      Określa, czy element jest widoczny w menu.

    • onclick

      void opcjonalny

      Funkcja onclick ma postać:

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

      • informacje

        OnClickData

        Chrome 44 lub nowszy
      • tabulator

        Tabulator

        Chrome 44 lub nowszy

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

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 123+

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onClicked

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

Uruchamiane po kliknięciu elementu menu kontekstowego.

Parametry