chrome.contextMenus

Opis

Interfejs API chrome.contextMenus pozwala dodawać elementy do menu kontekstowego Google Chrome. Możesz wybrać typy obiektów, do których mają zastosowanie dodatki w menu kontekstowym, np. obrazy, hiperlinki i strony.

Uprawnienia

contextMenus

Aby używać interfejsu API, musisz zadeklarować uprawnienie "contextMenus" w pliku manifestu rozszerzenia. Musisz też określić 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 w ramce w obrębie dokumentu), nawet w przypadku adresów URL typu file:// i chrome://. Aby kontrolować, w których dokumentach mogą się pojawiać elementy, określ pole documentUrlPatterns podczas wywoływania metody create() lub update().

Możesz utworzyć dowolną liczbę elementów menu kontekstowego, ale jeśli jednocześnie widocznych jest więcej niż jedno z nich, Google Chrome automatycznie zwija je w jedno menu nadrzędne.

Przykłady

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

Typy

ContextType

Chrome 44 i nowsze wersje

Różne konteksty, w których może pojawiać się menu. Określenie „all” jest równoważne z kombinacją wszystkich innych kontekstów z wyjątkiem „launchera”. Kontekst „Menu z aplikacjami” jest obsługiwany tylko przez aplikacje i pozwala dodawać elementy menu do menu kontekstowego wyświetlanego po kliknięciu ikony aplikacji w Menu z aplikacjami, na pasku zadań, w stacji dokującej itp. Różne platformy mogą nakładać ograniczenia na funkcje, które faktycznie są obsługiwane w menu kontekstowym programu uruchamiającego.

Typ wyliczeniowy

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 i nowsze wersje

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 – niewybrane. W danej grupie może być wybrana tylko jedna opcja.

  • konteksty

    [ContextType,...ContextType[]] opcjonalnie

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

  • documentUrlPatterns

    string[] opcjonalny

    Ogranicza zastosowanie elementu tylko do dokumentów lub ramek, których adres URL pasuje do jednego z podanych wzorców. Szczegółowe informacje na temat formatów wzorców można znaleźć 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 przypisany do tego elementu. Wymagane na stronach wydarzeń. Nie może być taki sam jak inny identyfikator tego rozszerzenia.

  • parentId

    ciąg|numer opcjonalny

    Identyfikator nadrzędnego elementu menu. Oznacza element podrzędny w stosunku do wcześniej dodanego elementu.

  • targetUrlPatterns

    string[] opcjonalny

    Podobnie jak w przypadku documentUrlPatterns filtry działające na podstawie atrybutu src tagów img, audio i video oraz atrybutu href a tagów.

  • title

    ciąg znaków opcjonalny

    Tekst wyświetlany w elemencie. Jest wymagany, chyba że type to separator. Jeśli kontekst to selection, użyj elementu %s w ciągu znaków, aby wyświetlić zaznaczony tekst. Jeśli na przykład wartość tego parametru to „Przetłumacz „%s” na język Pig Latin”, a użytkownik wybierze słowo „fajne”, element menu kontekstowego dla tego wyboru to „Przetłumacz »fajne« na język Pig Latin”.

  • Niestandardowy typ treści

    ItemType opcjonalnie

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

  • widoczna

    wartość logiczna opcjonalna

    Określa, czy element jest widoczny w menu.

  • onclick

    void opcjonalny

    Funkcja, która jest wywoływana po kliknięciu elementu menu. Ta funkcja nie jest dostępna w skrypcie service worker – zamiast tego zarejestruj detektor na potrzeby contextMenus.onClicked.

    Funkcja onclick wygląda tak: 

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

    • informacje

      OnClickData

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

    • tab

      Karta

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

ItemType

Chrome 44 i nowsze wersje

Typ pozycji menu.

Typ wyliczeniowy

"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 elementu opcji po kliknięciu.

  • edytowalny

    boolean

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

  • frameId

    Liczba opcjonalnie

    Chrome 51 i nowsze wersje

    Identyfikator ramki elementu, w którym kliknięto menu kontekstowe (jeśli znajduje się w ramce).

  • frameUrl

    ciąg znaków opcjonalny

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

    Jedna z wartości „obraz”, „wideo” lub „dźwięk”, jeśli menu kontekstowe zostało aktywowane w przypadku jednego z tych elementów.

  • menuItemId

    string|number

    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, gdy nie ma bieżącej strony, na przykład w menu kontekstowym Menu z aplikacjami.

  • parentMenuItemId

    ciąg|numer opcjonalny

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

  • selectionText

    ciąg znaków opcjonalny

    Tekst do wyboru kontekstu (jeśli istnieje).

  • srcUrl

    ciąg znaków opcjonalny

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

  • wasChecked

    wartość logiczna opcjonalna

    Flaga wskazująca stan pola wyboru lub elementu 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 zostaną zignorowane.

Wartość

6

Metody

create()

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

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

Parametry

  • createProperties

    CreateProperties

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Zwroty

  • number|string

    Identyfikator nowo utworzonego elementu.

remove()

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

Usuwa pozycję menu kontekstowego.

Parametry

  • menuItemId

    string|number

    Identyfikator elementu menu kontekstowego do usunięcia.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Zwroty

  • Promise<void>

    Chrome 123 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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 opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Zwroty

  • Promise<void>

    Chrome 123 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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|number

    Identyfikator elementu do aktualizacji.

  • updateProperties

    obiekt

    Właściwości do zaktualizowania. Może mieć te same wartości co funkcja contextMenus.create.

    • zaznaczono

      wartość logiczna opcjonalna

    • konteksty

      [ContextType,...ContextType[]] opcjonalnie

    • documentUrlPatterns

      string[] opcjonalny

    • włączone

      wartość logiczna opcjonalna

    • parentId

      ciąg|numer opcjonalny

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

    • targetUrlPatterns

      string[] opcjonalny

    • title

      ciąg znaków opcjonalny

    • Niestandardowy typ treści

      ItemType opcjonalnie

    • widoczna

      wartość logiczna opcjonalna

      Chrome 62 i nowsze wersje

      Określa, czy element jest widoczny w menu.

    • onclick

      void opcjonalny

      Funkcja onclick wygląda tak: 

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

      • informacje

        OnClickData

        Chrome 44 i nowsze wersje
      • tab

        Karta

        Chrome 44 i nowsze wersje

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Zwroty

  • Promise<void>

    Chrome 123 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika 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