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
Wykorzystanie
Elementy menu kontekstowego mogą pojawiać się w dowolnym dokumencie (lub w jego ramce), nawet w tych z adresami URL typu file:// lub 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.
Plik manifestu
Aby używać interfejsu API, musisz zadeklarować uprawnienie „contextMenus” w pliku manifestu rozszerzenia. Poza tym musisz 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"
},
...
}
Przykłady
Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs contextMenus API z repozytorium chrome-extension-samples.
Typy
ContextType
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
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 | liczba 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 atrybutusrc
tagówimg
,audio
ivideo
oraz atrybutuhref
a
tagów. -
title
ciąg znaków opcjonalny
Tekst wyświetlany w elemencie. Jest wymagany, chyba że
type
toseparator
. Jeśli kontekst toselection
, 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
Informacje o klikniętym elemencie i kontekście kliknięcia.
-
tab
Szczegóły karty, na której miało miejsce kliknięcie. Ten parametr nie jest obecny w przypadku aplikacji platformy.
-
ItemType
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 wersjeIdentyfikator 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.
-
ciąg | liczba
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 | liczba 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
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
liczba | ciąg
Identyfikator nowo utworzonego elementu.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
Usuwa pozycję menu kontekstowego.
Parametry
-
ciąg | liczba
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 wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
removeAll()
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 wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
Aktualizuje wcześniej utworzony element menu kontekstowego.
Parametry
-
id
ciąg | liczba
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 | liczba 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 wersjeOkreśla, czy element jest widoczny w menu.
-
onclick
void opcjonalny
Funkcja
onclick
wygląda tak:(info: OnClickData, tab: Tab) => {...}
-
informacjeChrome 44 i nowsze wersje
-
tabChrome 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 wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
Wydarzenia
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
Uruchamiane po kliknięciu elementu menu kontekstowego.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(info: OnClickData, tab?: tabs.Tab) => void
-
informacje
-
tab
tabs.Tab opcjonalnie
-