chrome.action

Opis

Dostępność

Plik manifestu

Aby użyć interfejsu API chrome.action, określ "manifest_version" o wartości 3 i umieść 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" (razem ze swoimi elementami podrzędnymi) jest opcjonalny. Jeśli rozszerzenie nie zostanie dodane, będzie nadal widoczne na pasku narzędzi, co umożliwi dostęp do menu rozszerzenia. Dlatego zalecamy, aby zawsze uwzględniać co najmniej klucze "action" i "default_icon".

Pojęcia i wykorzystanie

Części interfejsu użytkownika

Ikona

Jest to główny obraz rozszerzenia na pasku narzędzi. Jest ona 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 obrazów. Za pomocą tych ikon Chrome wybiera skalę obrazu. Jeśli nie znajdzie dopasowania ścisłego, Chrome wybiera najbliższą dostępną wartość i przeskaluje je, by pasowało do obrazu, co może mieć wpływ na jego jakość.

Urządzenia z mniej powszechnymi współczynnikami skali, np. 1,5x czy 1,2x, stają się coraz bardziej popularne, dlatego zachęcamy do utworzenia ikon w kilku rozmiarach. Zapewnia to również rozszerzeniu na przyszłość przed potencjalnymi zmianami rozmiaru wyświetlanych ikon. Jeśli jednak podajesz tylko 1 rozmiar, klucz "default_icon" można też ustawić jako ciąg ze ścieżką do pojedynczej ikony zamiast do słownika.

Aby ustawić ikonę rozszerzenia w sposób zautomatyzowany, możesz też wywołać funkcję action.setIcon(), określając inną ścieżkę obrazu lub dynamicznie generującą ikonę za pomocą elementu kanw HTML lub – w przypadku ustawienia przy użyciu skryptu usługi 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);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

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

Etykietka (tytuł)

Etykietka (tytuł) pojawia się, gdy użytkownik najedzie kursorem na 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 zostanie aktywowany.

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

Plakietka

Działania mogą opcjonalnie wyświetlać „plakietkę” – nałożoną na ikonę tekstu kropkę tekstu. Dzięki temu możesz zaktualizować działanie tak, aby wyświetlać niewielką ilość informacji o stanie rozszerzenia, np. licznik. Plakietka zawiera tekst i kolor tła. Ilość miejsca jest ograniczona, więc tekst plakietki powinien składać się z maksymalnie 4 znaków.

Aby utworzyć plakietkę, ustaw ją automatycznie, wywołując action.setBadgeBackgroundColor() i action.setBadgeText(). W pliku manifestu nie ma domyślnego ustawienia plakietki. Wartości koloru plakietki mogą być tablicą czterech liczb całkowitych z zakresu od 0 do 255, które składają się na kolor RGBA plakietki, lub ciągiem znaków z wartością kolor 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 wyświetla się, 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 dostosowywane do jego zawartości. Rozmiar wyskakującego okienka musi wynosić 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 dostępna, powinna wskazywać ścieżkę względną w katalogu rozszerzeń. Można go też aktualizować dynamicznie, aby wskazywał inną ścieżkę względną za pomocą metody action.setPopup().

Przykłady zastosowań

Stan według karty

Działania rozszerzenia mogą mieć inny stan na poszczególnych kartach. 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 dla konkretnej karty, wykonaj te czynności:

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

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

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

Stan włączenia

Domyślnie działania na pasku narzędzi są włączone (klikalne) na każdej karcie. Możesz to kontrolować za pomocą metod action.enable() i action.disable(). Ta wartość ma wpływ tylko na to, czy do rozszerzenia zostanie wysłane wyskakujące okienko (jeśli takie istnieje) czy zdarzenie action.onClicked. Nie ma to wpływu na obecność działania na pasku narzędzi.

Przykłady

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

Pokaż wyskakujące okienko

Rozszerzenie często wyświetla wyskakujące okienko, gdy użytkownik kliknie jego działanie. Aby zaimplementować tę funkcję w swoim rozszerzeniu, zadeklaruj wyskakujące okienko w manifest.json i określ treści, które Chrome ma wyświetlać w wyskakującym okienku.

// 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>

Wstawianie skryptu treści po kliknięciu

Częstym wzorcem stosowania rozszerzeń jest ujawnianie ich głównej funkcji za pomocą działania rozszerzenia. Poniższy przykład ilustruje ten wzorzec. Gdy użytkownik kliknie to działanie, rozszerzenie wstawia skrypt treści na bieżącej stronie. Następnie skrypt 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!');

Emuluj działania za pomocą funkcji declarativeContent

Ten przykład pokazuje, jak działająca w tle logika rozszerzenia może (a) domyślnie wyłączyć działanie i (b) użyć declarativeContent, aby umożliwić działanie tego działania na konkretnych stronach.

// 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,
  callback?: function,
)

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

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