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ą się odnosić dodatki do menu kontekstowego, np. do obrazów, hiperlinków i stron.

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 elementu 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 tych z adresami URL file:// lub chrome://. Aby określić, w których dokumentach mogą się pojawiać Twoje elementy, podczas wywoływania metod create() lub update() podaj pole documentUrlPatterns.

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

Przykłady

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

Typy

ContextType

Chrome 44 lub nowszy

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”

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[]] optional

    Lista kontekstów, w których pojawi się 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. Obowiązkowe w przypadku stron wydarzeń. 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, 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 on wymagany, chyba że type ma wartość separator. Gdy kontekst to selection, użyj w ciągu znaków symbolu %s, aby wyświetlić wybrany tekst. Jeśli np. 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

      Tab

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

ItemType

Chrome 44 lub nowszy

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 znajdował się on 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

    Występuje 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 nie zostać wykryty, dopóki nie zostanie wywołane wywołanie zwrotne 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()

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

Usuwa pozycję menu kontekstowego.

Parametry

  • menuItemId

    ciąg znaków | liczba

    Identyfikator elementu menu kontekstowego do usunięcia.

Zwroty

  • Promise<void>

    Chrome 123 lub nowsza

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

removeAll()

chrome.contextMenus.removeAll(): Promise<void>

Usuwa wszystkie elementy menu kontekstowego dodane przez to rozszerzenie.

Zwroty

  • Promise<void>

    Chrome 123 lub nowsza

    Spełnia się po zakończeniu usuwania.

update()

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

Aktualizuje utworzoną wcześniej pozycję 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[]] optional

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

        Tab

        Chrome 44 lub nowszy

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

Zwroty

  • Promise<void>

    Chrome 123 lub nowsza

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

Wydarzenia

onClicked

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

Uruchamiane po kliknięciu elementu menu kontekstowego.

Parametry