browser.action

Opis

Dostępność

Plik manifestu

Aby używać interfejsu API browser.action, 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 kluczami podrzędnymi) jest opcjonalny. Jeśli nie zostanie uwzględniony, rozszerzenie będzie nadal 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 użycie

Elementy interfejsu

Ikona

Ikona to główny obraz na pasku narzędzi rozszerzenia, który jest ustawiany przez klucz "default_icon" w kluczu "action" pliku manifestu. Ikony muszą mieć 16 pikseli niezależnych od urządzenia (DIP) szerokości i wysokości.

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 znajdzie dokładnego dopasowania, wybierze najbliższy dostępny rozmiar i przeskaluje go, aby dopasować do obrazu, co może wpłynąć na jakość obrazu.

Urządzenia o mniej typowych współczynnikach skalowania, takich jak 1,5x czy 1,2x, stają się coraz bardziej popularne, dlatego zachęcamy do udostępniania ikon w różnych rozmiarach. Dzięki temu ikona rozszerzenia będzie też dobrze wyglądać w przyszłości, nawet jeśli zmieni się rozmiar wyświetlania ikon. Jeśli jednak podajesz tylko 1 rozmiar, klucz "default_icon" można też ustawić na ciąg znaków ze ścieżką do pojedynczej ikony zamiast słownika.

Możesz też wywołać funkcję action.setIcon(), aby ustawić ikonę rozszerzenia automatycznie, podając inną ścieżkę do obrazu lub ikonę wygenerowaną dynamicznie za pomocą elementu canvas HTML, a jeśli ustawiasz ją z poziomu skryptu service worker rozszerzenia – interfejsu API 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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

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

Etykietka (tytuł)

Etykietka lub tytuł pojawia się, gdy użytkownik najeżdża wskaźnikiem myszy na ikonę rozszerzenia na pasku narzędzi. Jest on też uwzględniany w tekście odczytywanym przez czytniki ekranu, gdy przycisk jest zaznaczony.

Domyślna etykietka jest ustawiana za pomocą pola "default_title" klucza "action" w pliku manifest.json. Możesz też ustawić go automatycznie, wywołując action.setTitle().

Plakietka

Działania mogą opcjonalnie wyświetlać „plakietkę” – tekst nałożony na ikonę. Dzięki temu możesz zaktualizować działanie, aby wyświetlać niewielką ilość informacji o stanie rozszerzenia, np. licznik. Plakietka zawiera komponent tekstowy i kolor 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 kolorów 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.

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Wyskakujące okienko

Wyskakujące okienko działania jest wyświetlane, gdy użytkownik kliknie przycisk polecenia 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.

Wyskakujące okienko jest początkowo ustawiane 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 go też dynamicznie aktualizować, aby wskazywał inną ścieżkę względną, za pomocą metody action.setPopup().

Przypadki użycia

Stan poszczególnych kart

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

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

browser.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

Jeśli właściwość tabId zostanie pominięta, ustawienie będzie traktowane jako globalne. Ustawienia dotyczące kart mają pierwszeństwo przed ustawieniami globalnymi.

Stan włączenia

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ąć.

Stanem możesz sterować programowo za pomocą metod action.enable() i action.disable(). Wpływa to tylko na to, czy wyskakujące okienko (jeśli istnieje) 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ą kilka typowych sposobów używania działań w rozszerzeniach. Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu Action API z repozytorium chrome-extension-samples.

wyświetlić wyskakujące okienko,

Często zdarza się, że rozszerzenie wyświetla wyskakujące okienko, gdy użytkownik kliknie działanie rozszerzenia. Aby zaimplementować to we własnym rozszerzeniu, zadeklaruj wyskakujące okienko w pliku manifest.json i określ treść, którą Chrome ma w nim wyświetlać.

// 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 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 wstrzykuje skrypt treści na bieżącej stronie. 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
browser.action.onClicked.addListener((tab) => {
  browser.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 działania rozszerzenia w tle może (a) domyślnie wyłączyć działanie i (b) użyć declarativeContent, aby włączyć 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
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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