chrome.action

Opis

Dostępność

Plik manifestu

Aby użyć interfejsu chrome.action API, określ "manifest_version" jako 3 i uwzględnij klucz "action" w pliku manifestu.

{   "name": "Action Extension",   ...   "action": {     "default_icon": {              // optional       "16": "images/icon16.png",   // optional       "24": "images/icon24.png",   // optional       "32": "images/icon32.png"    // optional     },     "default_title": "Click Me",   // optional, shown in tooltip     "default_popup": "popup.html"  // optional   },   ... } 

Klucz "action" (wraz z jego elementami podrzędnymi) jest opcjonalny. Jeśli nie jest on uwzględniony, rozszerzenie nadal będzie wyświetlane na pasku narzędzi, aby zapewnić dostęp do menu rozszerzenia. Z tego powodu zalecamy, aby zawsze uwzględniać co najmniej klucze "action" i "default_icon".

Pojęcia i zastosowanie

Elementy interfejsu

Ikona

Ikona jest głównym obrazem na pasku narzędzi rozszerzenia i jest ustawiana przez klucz "default_icon" w kluczu "action" pliku manifestu. Ikony muszą mieć szerokość i wysokość 16 pikseli niezależnych od urządzenia (DIP).

Klucz "default_icon" to słownik rozmiarów i ścieżek do obrazów. Chrome używa tych ikon, aby wybrać skalę obrazu. Jeśli nie zostanie znalezione dopasowanie ścisłe, Chrome wybierze najbliższe dostępne dopasowanie i skaluje je tak, aby pasowało do obrazu, co może wpłynąć na jakość obrazu.

Urządzenia z mniej popularnymi współczynnikami skalowania, takimi jak 1,5x czy 1,2x, stają się coraz bardziej powszechne, dlatego zachęcamy do przesyłania ikon w różnych rozmiarach. Dzięki temu rozszerzenie będzie odporne na potencjalne zmiany rozmiaru wyświetlania ikon w przyszłości. Jeśli jednak podajesz tylko 1 rozmiar, klucz "default_icon" może być też ustawiony na ciąg znaków ze ścieżką do pojedynczej ikony zamiast słownika.

Możesz też wywołać action.setIcon(), aby programowo ustawić ikonę rozszerzenia, podając inną ścieżkę obrazu lub dostarczając dynamicznie generowaną ikonę za pomocą elementu canvas HTML lub, jeśli ustawiasz ikonę z poziomu skryptu service worker rozszerzenia, interfejsu offscreen canvas.

const canvas = new OffscreenCanvas(16, 16); const context = canvas.getContext('2d'); context.clearRect(0, 0, 16, 16); context.fillStyle = '#00FF00';  // Green context.fillRect(0, 0, 16, 16); const imageData = context.getImageData(0, 0, 16, 16); chrome.action.setIcon({imageData: imageData}, () => { /* ... */ }); 

W przypadku spakowanych rozszerzeń (instalowanych z pliku CRX) obrazy mogą być w większości formatów, które może wyświetlać silnik renderujący Blink, w tym PNG, JPEG, BMP, ICO i inne. Format SVG nie jest obsługiwany. Rozpakowane rozszerzenia muszą używać obrazów PNG.

Etykietka (tytuł)

Etykietka lub tytuł pojawia się, gdy użytkownik przytrzyma wskaźnik myszy nad ikoną rozszerzenia na pasku narzędzi. Jest on też uwzględniany w tekście na potrzeby ułatwień dostępu odczytywanym przez czytniki ekranu, gdy przycisk jest aktywny.

Domyślny opis jest ustawiany za pomocą pola "default_title" klucza "action" w manifest.json. Możesz też ustawić go programowo, wywołując action.setTitle().

Plakietka

Działania mogą opcjonalnie wyświetlać „odznakę”, czyli fragment tekstu nałożony na ikonę. Umożliwia to aktualizowanie działania w celu wyświetlania niewielkiej ilości informacji o stanie rozszerzenia, np. licznika. Odznaka składa się z komponentu tekstowego i koloru tła. Ze względu na ograniczoną ilość miejsca zalecamy, aby tekst plakietki miał maksymalnie 4 znaki.

Aby utworzyć plakietkę, ustaw ją automatycznie, wywołując funkcje action.setBadgeBackgroundColor() i action.setBadgeText(). W pliku manifestu nie ma domyślnego ustawienia plakietki. Wartości koloru plakietki mogą być tablicą 4 liczb całkowitych z zakresu od 0 do 255, które tworzą kolor RGBA plakietki, lub ciągiem znaków z wartością koloru CSS.

chrome.action.setBadgeBackgroundColor(   {color: [0, 255, 0, 0]},  // Green   () => { /* ... */ }, );  chrome.action.setBadgeBackgroundColor(   {color: '#00FF00'},  // Also green   () => { /* ... */ }, );  chrome.action.setBadgeBackgroundColor(   {color: 'green'},  // Also, also green   () => { /* ... */ }, ); 

Wyskakujące okienko

Wyskakujące okienko działania jest wyświetlane, gdy użytkownik kliknie przycisk działania rozszerzenia na pasku narzędzi. Wyskakujące okienko może zawierać dowolną treść HTML i będzie automatycznie dopasowywane do jej rozmiaru. Rozmiar wyskakującego okienka musi mieścić się w zakresie od 25 x 25 do 800 x 600 pikseli.

Początkowe ustawienie wyskakującego okienka jest określone przez właściwość "default_popup" w kluczu "action" w pliku manifest.json. Jeśli ta właściwość jest obecna, powinna wskazywać ścieżkę względną w katalogu rozszerzenia. Można ją też aktualizować dynamicznie, aby wskazywała inną ścieżkę względną, za pomocą metody action.setPopup().

Przypadki użycia

Stan karty

Działania rozszerzenia mogą mieć różne stany na każdej karcie. Aby ustawić wartość dla poszczególnych kart, użyj właściwości tabId w metodach ustawień interfejsu action API. Aby na przykład ustawić tekst plakietki na konkretnej karcie, wykonaj te czynności:

function getTabId() { /* ... */} function getTabBadge() { /* ... */}  chrome.action.setBadgeText(   {     text: getTabBadge(tabId),     tabId: getTabId(),   },   () => { ... } ); 

Jeśli pominiesz właściwość tabId, ustawienie zostanie potraktowane jako globalne. Ustawienia dotyczące konkretnej karty mają wyższy priorytet niż ustawienia globalne.

Stan włączony

Domyślnie działania na pasku narzędzi są włączone (można je kliknąć) na każdej karcie. Możesz zmienić to ustawienie domyślne, ustawiając właściwość default_state w kluczu action pliku manifestu. Jeśli parametr default_state ma wartość "disabled", działanie jest domyślnie wyłączone i musi zostać włączone programowo, aby można było je kliknąć. Jeśli parametr default_state ma wartość "enabled" (domyślną), działanie jest domyślnie włączone i można je kliknąć.

Stan możesz kontrolować programowo za pomocą metod action.enable() i action.disable(). Wpływa to tylko na to, czy wyskakujące okienko (jeśli występuje) lub zdarzenie action.onClicked jest wysyłane do rozszerzenia. Nie ma to wpływu na obecność działania na pasku narzędzi.

Przykłady

Poniższe przykłady pokazują typowe sposoby wykorzystania działań w rozszerzeniach. Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu Action API z repozytorium chrome-extension-samples.

Wyświetlanie wyskakującego okienka

Rozszerzenie często wyświetla wyskakujące okienko, gdy użytkownik kliknie jego działanie. Aby zaimplementować to w swoim rozszerzeniu, zadeklaruj wyskakujące okienko w pliku manifest.json i określ treść, która ma być w nim wyświetlana.

// manifest.json {   "name": "Action popup demo",   "version": "1.0",   "manifest_version": 3,   "action": {     "default_title": "Click to view a popup",     "default_popup": "popup.html"   } } 

<!-- popup.html --> <!DOCTYPE html> <html> <head>   <style>     html {       min-height: 5em;       min-width: 10em;       background: salmon;     }   </style> </head> <body>   <p>Hello, world!</p> </body> </html> 

Wstrzykiwanie skryptu treści po kliknięciu

Typowym wzorcem w przypadku rozszerzeń jest udostępnianie ich głównej funkcji za pomocą działania rozszerzenia. Ten wzorzec ilustruje poniższy przykład. Gdy użytkownik kliknie działanie, rozszerzenie wstrzyknie skrypt treści na bieżącą stronę. Następnie skrypt treści wyświetla alert, aby sprawdzić, czy wszystko działa zgodnie z oczekiwaniami.

// manifest.json {   "name": "Action script injection demo",   "version": "1.0",   "manifest_version": 3,   "action": {     "default_title": "Click to show an alert"   },   "permissions": ["activeTab", "scripting"],   "background": {     "service_worker": "background.js"   } } 

// background.js chrome.action.onClicked.addListener((tab) => {   chrome.scripting.executeScript({     target: {tabId: tab.id},     files: ['content.js']   }); }); 

// content.js alert('Hello, world!'); 

Emulowanie działań za pomocą declarativeContent

Ten przykład pokazuje, jak logika w tle rozszerzenia może (a) domyślnie wyłączać działanie i (b) używać declarativeContent, aby włączać działanie w określonych witrynach.

// service-worker.js  // Wrap in an onInstalled callback to avoid unnecessary work // every time the service worker is run chrome.runtime.onInstalled.addListener(() => {   // Page actions are disabled by default and enabled on select tabs   chrome.action.disable();    // Clear all rules to ensure only our expected rules are set   chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {     // Declare a rule to enable the action on example.com pages     let exampleRule = {       conditions: [         new chrome.declarativeContent.PageStateMatcher({           pageUrl: {hostSuffix: '.example.com'},         })       ],       actions: [new chrome.declarativeContent.ShowAction()],     };      // Finally, apply our new array of rules     let rules = [exampleRule];     chrome.declarativeContent.onPageChanged.addRules(rules);   }); }); 

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

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

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)