chrome.contextMenus

Opis

Aby dodawać elementy do menu kontekstowego Google Chrome, używaj interfejsu API chrome.contextMenus. Możesz wybrać typy obiektów, do których mają zastosowanie dodane w menu kontekstowym, np. obrazów, hiperlinków i stron.

Uprawnienia

contextMenus

Aby korzystać z interfejsu API, musisz zadeklarować uprawnienia "contextMenus" w pliku manifestu rozszerzenia. Oprócz tego: należy określić ikonę o wymiarach 16 na 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 wykorzystanie

Pozycje menu kontekstowego mogą pojawić się w dowolnym dokumencie (lub w ramce dokumentu), nawet jeśli zawiera on element file://. lub chrome://. Aby określić, w których dokumentach mogą się pojawiać Twoje elementy, określ documentUrlPatterns przy wywoływaniu metod create() lub update().

W menu kontekstowym możesz utworzyć dowolną liczbę pozycji. Jeśli jednak jest ich więcej, widocznych jednocześnie, Google Chrome automatycznie zwija je w jedno menu nadrzędne.

Przykłady

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

Typy

ContextType

Chrome w wersji 44 lub nowszej .

w różnych kontekstach, w których może się pojawiać menu; Określanie wszystkich jest odpowiednikiem kombinacji wszystkich innych kontekstów z wyjątkiem „launchera”. Program uruchamiający Kontekst jest obsługiwany tylko przez aplikacje i służy do dodawania pozycji 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ą stosować ograniczenia dotyczące funkcji faktycznie obsługiwanych w menu kontekstowym programu uruchamiającego.

Typ wyliczeniowy

"all"

"strona"

"frame"

"selection"

"link"

"edycja"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome w wersji 123 lub nowszej .

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

Właściwości

  • zaznaczono

    Wartość logiczna opcjonalna

    Początkowy stan pola wyboru lub opcji: true – zaznaczone, false – niezaznaczone. W danej grupie można wybrać tylko jedną opcję naraz.

  • konteksty

    [ContextType, ...ContextType[]] opcjonalny

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

  • documentUrlPatterns

    string[] opcjonalnie

    Ogranicza zastosowanie elementu 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

    Określa, czy ta 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. Obowiązkowy na stronach wydarzeń. Nie może być taki sam jak inny identyfikator tego rozszerzenia.

  • parentId

    string | liczba opcjonalnie

    identyfikator nadrzędnej pozycji menu; element ten staje się elementem podrzędnym elementu dodanego wcześniej.

  • targetUrlPatterns

    string[] opcjonalnie

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

  • tytuł

    ciąg znaków opcjonalny

    Tekst do wyświetlenia w elemencie. jest wymagany, chyba że type ma wartość separator. Jeśli kontekst to selection, użyj w ciągu znaków %s, aby wyświetlić zaznaczony tekst. Jeśli na przykład wartość tego parametru to „Przetłumacz '%s” po „Pig Latin” a użytkownik wybiera słowo „świetne”, co zostaje w menu kontekstowym jako „Przetłumacz „świetne” Pig Latin”.

  • typ

    Opcjonalny ItemType

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

  • widoczna

    Wartość logiczna opcjonalna

    Określa, czy element jest widoczny w menu.

  • Kliknij

    void opcjonalnie

    Funkcja, która jest wywoływana po kliknięciu elementu menu. Nie jest dostępna w mechanizmie Service Worker. zamiast tego zarejestruj odbiornik dla contextMenus.onClicked.

    Funkcja onclick wygląda tak: 

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

    • informacje

      OnClickData

      Informacje o klikniętym produkcie i kontekście kliknięcia.

    • tabulator

      Karta

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

ItemType

Chrome w wersji 44 lub nowszej .

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 wskazująca, czy element można edytować (wpisywanie tekstu, obszar tekstowy itp.).

  • frameId

    liczba opcjonalnie

    Chrome w wersji 51 lub nowszej .

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

  • frameUrl

    ciąg znaków opcjonalny

    Adres URL ramki elementu, w której kliknięto menu kontekstowe (jeśli znajduje się ona w ramce).

  • linkUrl

    ciąg znaków opcjonalny

    Jeśli element jest linkiem, 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 w jednym z tych elementów.

  • menuItemId

    string | numer

    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 ustawiona, 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 | liczba opcjonalnie

    Identyfikator elementu nadrzędnego (jeśli istnieje) klikniętego elementu.

  • selectionText

    ciąg znaków opcjonalny

    Tekst dotyczący zaznaczenia kontekstu (jeśli taki istnieje).

  • srcUrl

    ciąg znaków opcjonalny

    Obecny w elementach z parametrem „src” Adres URL.

  • 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 czynności rozszerzenia. Wszystkie elementy powyżej tego limitu będą ignorowane.

Wartość

6

Metody

create()

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

Tworzy nową pozycję w menu kontekstowym. Jeśli podczas tworzenia wystąpi błąd, może on nie zostać wykryty do czasu uruchomienia wywołania zwrotnego tworzenia. znajdziesz na stronie runtime.lastError.

Parametry

  • createProperties

    CreateProperties

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • liczba | tekst

    Identyfikator nowo utworzonego elementu.

remove()

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

Usuwa pozycję menu kontekstowego.

Parametry

  • menuItemId

    string | numer

    Identyfikator elementu menu kontekstowego, który ma zostać usunięty.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 123 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

removeAll()

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

Usuwa wszystkie pozycje menu kontekstowego dodane przez to rozszerzenie.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 123 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

update()

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

Aktualizuje wcześniej utworzony element menu kontekstowego.

Parametry

  • id

    string | numer

    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

    • konteksty

      [ContextType, ...ContextType[]] opcjonalny

    • documentUrlPatterns

      string[] opcjonalnie

    • włączone

      Wartość logiczna opcjonalna

    • parentId

      string | liczba opcjonalnie

      Identyfikator elementu, który ma zostać ustawiony jako nadrzędny. Uwaga: nie możesz ustawić elementu jako podrzędnego względem jego własnego elementu podrzędnego.

    • targetUrlPatterns

      string[] opcjonalnie

    • tytuł

      ciąg znaków opcjonalny

    • typ

      Opcjonalny ItemType

    • widoczna

      Wartość logiczna opcjonalna

      Chrome w wersji 62 lub nowszej .

      Określa, czy element jest widoczny w menu.

    • Kliknij

      void opcjonalnie

      Funkcja onclick wygląda tak: 

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

      • informacje

        OnClickData

        Chrome w wersji 44 lub nowszej .
      • tabulator

        Karta

        Chrome w wersji 44 lub nowszej .

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 123 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onClicked

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

Uruchamiane po kliknięciu elementu menu kontekstowego.

Parametry