browser.actie

Beschrijving

Beschikbaarheid

Manifest

Om de browser.action API te gebruiken, moet u een "manifest_version" van 3 opgeven en de sleutel "action" in uw manifestbestand opnemen.

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

De sleutel "action" (en de bijbehorende subsleutels) is optioneel. Als deze niet is opgenomen, wordt uw extensie nog steeds in de werkbalk weergegeven om toegang te bieden tot het menu van de extensie. Daarom raden we aan om altijd ten minste de sleutels "action" en "default_icon" op te nemen.

Concepten en gebruik

Onderdelen van de gebruikersinterface

Icon

Het pictogram is de hoofdafbeelding op de werkbalk van uw extensie en wordt ingesteld door de sleutel "default_icon" in de sleutel "action" van uw manifest. Pictogrammen moeten 16 apparaatonafhankelijke pixels (DIP's) breed en hoog zijn.

De sleutel "default_icon" is een woordenboek met formaten en bijbehorende afbeeldingspaden. Chrome gebruikt deze pictogrammen om te bepalen welke afbeeldingsschaal moet worden gebruikt. Als er geen exacte overeenkomst wordt gevonden, selecteert Chrome het dichtstbijzijnde beschikbare pictogram en schaalt dit om de afbeelding te passen, wat de beeldkwaliteit kan beïnvloeden.

Omdat apparaten met minder gangbare schaalfactoren zoals 1,5x of 1,2x steeds vaker voorkomen, raden we u aan om meerdere formaten voor uw pictogrammen op te geven. Dit maakt uw extensie ook toekomstbestendig tegen mogelijke wijzigingen in de weergavegrootte van pictogrammen. Als u echter slechts één formaat opgeeft, kan de sleutel "default_icon" ook worden ingesteld op een tekenreeks met het pad naar een enkel pictogram in plaats van een woordenboek.

Je kunt ook action.setIcon() aanroepen om het pictogram van je extensie programmatisch in te stellen door een ander afbeeldingspad op te geven of een dynamisch gegenereerd pictogram te leveren met behulp van het HTML-canvas-element , of, als je het instelt vanuit een extension service worker, de offscreen canvas API.

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

Voor gecomprimeerde extensies (geïnstalleerd vanuit een .crx-bestand) kunnen afbeeldingen in de meeste formaten zijn die de Blink-renderingengine kan weergeven, waaronder PNG, JPEG, BMP, ICO en andere. SVG wordt niet ondersteund. Niet-gecomprimeerde extensies moeten PNG-afbeeldingen gebruiken.

Tooltip (titel)

De tooltip, ofwel de titel, verschijnt wanneer de gebruiker de muiswijzer boven het pictogram van de extensie in de werkbalk houdt. Deze is ook opgenomen in de toegankelijke tekst die door schermlezers wordt voorgelezen wanneer de knop de focus krijgt.

De standaard tooltip wordt ingesteld met behulp van het veld "default_title" van de sleutel "action" in manifest.json . Je kunt deze ook programmatisch instellen door action.setTitle() aan te roepen.

Badge

Acties kunnen optioneel een 'badge' weergeven — een stukje tekst dat over het pictogram heen wordt geplaatst. Hiermee kunt u de actie bijwerken om een ​​kleine hoeveelheid informatie over de status van de extensie weer te geven, zoals een teller. De badge heeft een tekstcomponent en een achtergrondkleur. Omdat de ruimte beperkt is, raden we aan dat de badge-tekst maximaal vier tekens bevat.

Om een ​​badge te maken, stel je deze programmatisch in door action.setBadgeBackgroundColor() en action.setBadgeText() aan te roepen. Er is geen standaard badge-instelling in het manifest. Badgekleurwaarden kunnen een array van vier gehele getallen tussen 0 en 255 zijn die de RGBA-kleur van de badge vormen, of een tekenreeks met een CSS- kleurwaarde.

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

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

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

Pop-up

Een pop-upvenster voor een actie wordt weergegeven wanneer de gebruiker op de actieknop van de extensie in de werkbalk klikt. Het pop-upvenster kan willekeurige HTML-inhoud bevatten en wordt automatisch aangepast aan de inhoud. De afmetingen van het pop-upvenster moeten tussen 25x25 en 800x600 pixels liggen.

De pop-up wordt in eerste instantie ingesteld door de eigenschap "default_popup" in de sleutel "action" in het manifest.json bestand. Indien aanwezig, moet deze eigenschap verwijzen naar een relatief pad binnen de extensiemap. Deze kan ook dynamisch worden bijgewerkt naar een ander relatief pad met behulp van de methode action.setPopup() .

Gebruiksvoorbeelden

Status per tabblad

Extensie-acties kunnen verschillende statussen hebben voor elk tabblad. Om een ​​waarde voor een individueel tabblad in te stellen, gebruikt u de eigenschap tabId in de instellingsmethoden van de action API. Om bijvoorbeeld de badge-tekst voor een specifiek tabblad in te stellen, doet u iets als het volgende:

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

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

Als de eigenschap tabId wordt weggelaten, wordt de instelling als een algemene instelling beschouwd. Tabbladspecifieke instellingen hebben voorrang op algemene instellingen.

Ingeschakelde status

Standaard zijn de acties in de werkbalk op elk tabblad ingeschakeld (klikbaar). U kunt deze standaardinstelling wijzigen door de eigenschap default_state in de ` action sleutel van het manifest in te stellen. Als default_state is ingesteld op "disabled" , is de actie standaard uitgeschakeld en moet deze programmatisch worden ingeschakeld om klikbaar te zijn. Als default_state is ingesteld op "enabled" (de standaardwaarde), is de actie standaard ingeschakeld en klikbaar.

Je kunt de status programmatisch beheren met de methoden action.enable() en action.disable() . Dit heeft alleen invloed op het al dan niet verzenden van de pop-up (indien aanwezig) of action.onClicked -gebeurtenis naar je extensie; het heeft geen invloed op de aanwezigheid van de actie in de toolbar.

Voorbeelden

De volgende voorbeelden laten enkele veelvoorkomende manieren zien waarop acties in extensies worden gebruikt. Om deze API uit te proberen, installeer je het Action API-voorbeeld uit de chrome-extension-samples- repository.

Toon een pop-upvenster

Het is gebruikelijk dat een extensie een pop-upvenster weergeeft wanneer de gebruiker op een actie van de extensie klikt. Om dit in je eigen extensie te implementeren, declareer je de pop-up in je manifest.json en geef je aan welke inhoud Chrome in de pop-up moet weergeven.

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

Voeg een contentscript in bij een klik.

Een veelvoorkomend patroon voor extensies is om hun belangrijkste functionaliteit te tonen via de actie van de extensie. Het volgende voorbeeld illustreert dit patroon. Wanneer de gebruiker op de actie klikt, voegt de extensie een contentscript toe aan de huidige pagina. Dit contentscript geeft vervolgens een melding weer om te controleren of alles naar behoren werkt.

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

Emuleer acties met declarativeContent.

Dit voorbeeld laat zien hoe de achtergrondlogica van een extensie (a) een actie standaard kan uitschakelen en (b) declarativeContent kan gebruiken om de actie op specifieke sites in te schakelen.

// 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);
  });
});

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