chrome.action

Beschreibung

Verfügbarkeit

Manifest

Wenn Sie die chrome.action API verwenden möchten, geben Sie als "manifest_version" den Wert 3 an und fügen Sie den Schlüssel "action" in deiner Manifestdatei.

{
  "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
  },
  ...
}

Der Schlüssel "action" (zusammen mit seinen untergeordneten Elementen) ist optional. Ist die Erweiterung nicht darin enthalten, wird sie trotzdem in der Symbolleiste angezeigt, damit Sie auf das Menü der Erweiterung zugreifen können. Aus diesem Grund empfehlen wir, immer mindestens die Schlüssel "action" und "default_icon" anzugeben.

Konzepte und Verwendung

Bestandteile der Benutzeroberfläche

Symbol

Das Symbol ist das Hauptbild in der Symbolleiste für Ihre Erweiterung und wird durch die Taste "default_icon" festgelegt in den "action"-Schlüssel deines Manifests. Symbole müssen 16 geräteunabhängige Pixel (DIPs) breit und hoch sein.

Der Schlüssel "default_icon" ist ein Wörterbuch der Größen für Bildpfade. Chrome verwendet diese Symbole um auszuwählen, welcher Bildmaßstab verwendet werden soll. Wird keine genaue Übereinstimmung gefunden, wählt Chrome die am ehesten passende Übereinstimmung aus. und skaliert es, um es an das Bild anzupassen, was die Bildqualität beeinträchtigen kann.

Weil Geräte mit weniger gängigen Skalierungsfaktoren wie 1,5- oder 1,2-fachen immer mehr empfehlen wir Ihnen, mehrere Größen für Ihre Symbole zur Verfügung zu stellen. Dies gilt auch für So wird Ihre Erweiterung zukunftssicher, um potenzielle Änderungen der Symbolanzeigegröße zu verhindern. Sie können jedoch Wenn Sie nur eine Größe angeben, kann der Schlüssel "default_icon" auch auf eine mit dem Pfad zu einem einzelnen Symbol anstelle eines Wörterbuchs.

Sie können auch action.setIcon() aufrufen, um das Symbol der Erweiterung programmatisch festzulegen indem Sie einen anderen Bildpfad angeben oder mithilfe des HTML-Canvas-Elements ein dynamisch generiertes Symbol bereitstellen. oder bei der Einstellung durch einen Erweiterungs-Service-Worker das offscreen-Element Canvas API erstellen.

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}, () => { /* ... */ });

Bei gepackten Erweiterungen (aus einer CRX-Datei installiert) können Bilder in den meisten Formaten vorliegen, die von Blink Rendering-Modul zur Anzeige von Inhalten, einschließlich PNG, JPEG, BMP, ICO usw. SVG wird nicht unterstützt. Für entpackte Erweiterungen müssen PNG-Bilder verwendet werden.

Kurzinfo (Titel)

Die Kurzinfo bzw. der Titel wird angezeigt, wenn der Nutzer den Mauszeiger über das Symbol der Erweiterung in der Ansicht in der Symbolleiste. Sie ist auch in dem barrierefreien Text enthalten, der von Screenreadern vorgelesen wird, wenn die Schaltfläche fokussiert.

Die Standard-Kurzinfo wird mit dem Feld "default_title" des Schlüssels "action" in manifest.json festgelegt. Sie können sie auch programmatisch festlegen, indem Sie action.setTitle() aufrufen.

Badge

In Aktionen kann optional ein Logo angezeigt werden – ein Text, der über das Symbol gelegt wird. So können Sie aktualisieren Sie die Aktion so, dass einige Informationen zum Status der Erweiterung angezeigt werden, wie etwa einen Zähler. Das Logo hat eine Textkomponente und eine Hintergrundfarbe. Da der Platz begrenzt ist, empfehlen wir, maximal vier Zeichen zu verwenden.

Zum Erstellen eines Logos können Sie es programmatisch einrichten, indem Sie action.setBadgeBackgroundColor() aufrufen und action.setBadgeText(). Im Manifest gibt es keine Standardeinstellung für das Badge. Werte für Logofarben kann entweder ein Array von vier Ganzzahlen zwischen 0 und 255 sein, aus denen die RGBA-Farbe des Logo oder einen String mit einem CSS-Farbwert aus.

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

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

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

Pop-up

Das Pop-up einer Aktion wird angezeigt, wenn der Nutzer auf die Aktionsschaltfläche der Erweiterung in der in der Symbolleiste. Das Pop-up-Fenster kann beliebige HTML-Inhalte enthalten und wird automatisch an die Größe angepasst. deren Inhalt. Das Pop-up muss zwischen 25 x 25 und 800 x 600 Pixel groß sein.

Das Pop-up wird anfangs durch das Attribut "default_popup" im Schlüssel "action" im manifest.json-Datei. Wenn diese Eigenschaft vorhanden ist, sollte sie auf einen relativen Pfad innerhalb der Erweiterung verweisen. -Verzeichnis. Er kann auch dynamisch aktualisiert werden, um mithilfe der Methode action.setPopup()-Methode.

Anwendungsfälle

Status pro Tab

Erweiterungsaktionen können für jeden Tab einen anderen Status haben. Um einen Wert für eine Einzelperson festzulegen das Attribut tabId in den Einstellungsmethoden der action API. Zum Beispiel Badge-Text für einen bestimmten Tab festlegen möchten, gehen Sie in etwa so vor:

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

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

Wird das Attribut tabId weggelassen, wird die Einstellung als globale Einstellung behandelt. Tabspezifisch Vorrang vor globalen Einstellungen.

Aktiviert

Standardmäßig sind Symbolleistenaktionen auf jedem Tab aktiviert (anklickbar). Sie können dies über die action.enable()- und action.disable()-Methoden. Dies betrifft nur, ob das Pop-up (falls vorhanden) oder action.onClicked Ereignis wird an Ihre Erweiterung gesendet. wirkt sich dies nicht auf die Anwesenheit der Aktion aus, in der Symbolleiste.

Beispiele

Die folgenden Beispiele zeigen einige gängige Verwendungsmöglichkeiten von Aktionen in Erweiterungen. Um diese API auszuprobieren, das Action API-Beispiel aus chrome-extension-samples installieren zu erstellen.

Pop-up anzeigen

Es ist üblich, dass eine Erweiterung ein Pop-up anzeigt, wenn der Nutzer auf die Aktion der Erweiterung klickt. Bis Implementieren Sie dies in Ihrer eigenen Erweiterung, deklarieren Sie das Pop-up in Ihrer manifest.json und geben Sie Inhalt, den Chrome im Pop-up-Fenster anzeigen soll.

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

Inhaltsskript per Klick einfügen

Erweiterungen werden häufig nach dem Muster die Hauptfunktion der Erweiterung Aktion ausführen. Das folgende Beispiel veranschaulicht dieses Muster. Wenn der Nutzer auf die Aktion klickt, fügt ein Inhaltsskript in die aktuelle Seite ein. Das Content-Skript zeigt dann eine Benachrichtigung an, dass alles wie erwartet funktioniert hat.

// 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!');

Aktionen mit deklarativeContent emulieren

Dieses Beispiel zeigt, wie die Hintergrundlogik einer Erweiterung (a) eine Aktion standardmäßig deaktivieren und (b) Verwenden Sie declarativeContent, um die Aktion für bestimmte Websites zu aktivieren.

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