chrome.action

Opis

Dostępność

Plik manifestu

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

Pojęcia i wykorzystanie

Elementy interfejsu

Ikona

Ikona jest głównym obrazem na pasku narzędzi rozszerzenia i jest ustawiana za pomocą klucza "default_icon" w kluczu "action" w pliku manifestu. Ikony muszą mieć 16 pikseli na szerokość i wysokość.

Klucz "default_icon" to słownik rozmiarów i ścieżek obrazów. Chrome używa tych ikon aby wybrać skalę obrazu. Jeśli nie znajdzie dopasowania ścisłego, Chrome wybiera najbliższy i skaluje go tak, aby pasował do obrazu, co może mieć wpływ na jego jakość.

Ponieważ urządzenia z mniej powszechnymi współczynnikami skali, np. 1,5x czy 1,2x, stają się coraz bardziej popularne popularny, zachęcamy do zastosowania różnych rozmiarów ikon. To także zabezpiecza rozszerzenie przed potencjalnymi zmianami rozmiaru wyświetlanych ikon. Pamiętaj jednak: Jeśli podajesz tylko jeden rozmiar, klucz "default_icon" można również ustawić na ze ścieżką do pojedynczej ikony zamiast słownika.

Możesz też wywołać funkcję action.setIcon(), aby ustawić ikonę rozszerzenia programowo, podając inną ścieżkę obrazu lub podając ikonę wygenerowaną dynamicznie za pomocą elementu HTML canvas lub, jeśli ustawienie pochodzi z elementu workera rozszerzenia, za pomocą 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 skompresowanych 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 inne. Format SVG nie jest obsługiwany. Rozpakowane rozszerzenia muszą używać obrazów PNG.

Etykieta (tytuł)

Etykieta lub tytuł wyświetla się, gdy użytkownik najedzie kursorem na ikonę rozszerzenia na pasku narzędzi. Jest on też uwzględniony w tekstach na potrzeby ułatwień dostępu odczytywanych przez czytniki ekranu, gdy przycisk jest aktywny.

Domyślny tekst podpowiedzi jest ustawiany 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ę” — fragment tekstu nałożony na ikonę. Dzięki temu możesz: zaktualizować działanie, aby wyświetlić niewielką ilość informacji o stanie rozszerzenia; takich jak licznik. Plakietka zawiera tekst i kolor tła. Ilość miejsca jest ograniczona, zalecamy, aby tekst plakietki zawierał maksymalnie 4 znaki.

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ą 4 liczb całkowitych z zakresu od 0 do 255, które tworzą kolor RGBA plakietki, lub ciągiem znaków z wartością kolorów 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

Gdy użytkownik kliknie przycisk działania rozszerzenia na pasku narzędzi, wyświetli się wyskakujące okienko działania. Wyskakujące okienko może zawierać dowolną treść w języku HTML i zostanie automatycznie dopasowywane do rozmiaru jej treści. Rozmiar wyskakującego okienka musi wynosić od 25 x 25 do 800 x 600 pikseli.

Pojawiający się okno jest początkowo ustawiane przez właściwość "default_popup" w kluczu "action" w pliku manifest.json. Jeśli jest obecna, powinna wskazywać ścieżkę względną w katalogu rozszerzeń. Może ona też być aktualizowana dynamicznie, aby wskazywać inną ścieżkę względną za pomocą metody action.setPopup().

Przypadki użycia

Stan 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 zmienić tekst plakietki na konkretnej karcie, wykonaj te czynności:

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

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

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

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ą Metody action.enable() i action.disable(). Ma to wpływ tylko na to, czy wyskakujące okienko (jeśli jest dostępne) Do rozszerzenia zostało wysłane zdarzenie action.onClicked. Nie ma to wpływu na działanie działania na pasku narzędzi.

Przykłady

Przykłady poniżej pokazują typowe sposoby używania działań w rozszerzeniach. Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs Action API ze strony chrome-extension-samples. z repozytorium.

Pokaż wyskakujące okienko

Rozszerzenie często wyświetla wyskakujące okienko, gdy użytkownik kliknie jego działanie. Do użyj go w swoim rozszerzeniu, zadeklaruj wyskakujące okienko w manifest.json i podaj w nim parametr które Chrome ma wyświetlić 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

Typowym wzorcem jest udostępnianie głównej funkcji rozszerzenia za pomocą jego działania. Poniższy przykład ilustruje ten wzorzec. Gdy użytkownik kliknie działanie, rozszerzenie wstawia skrypt treści na bieżącej stronie. Następnie skrypt treści wyświetla alert do weryfikacji aby wszystko działało 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ą deklaratywnego kodu

Ten przykład pokazuje, jak dzięki funkcji logicznej działania rozszerzenia w tle mogą (a) domyślnie wyłączyć działanie oraz (b) użyj metody declarativeContent, aby umożliwić wykonywanie działań w przypadku konkretnych witryn.

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

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