browser.action

Beschrijving

Gebruik de chrome.action API om het icoon van de extensie in de Google Chrome-werkbalk te beheren.

De actie-iconen worden getoond in de browserwerkbalk naast de omnibox. Na de installatie verschijnen deze in het menu Extensies (het puzzelstukje). Gebruikers kunnen je extensie-icoon vastzetten op de werkbalk.

Beschikbaarheid

Chrome 88+ browser.* sinds Chrome 148 MV3+

Manifest

De volgende sleutels moeten in het manifest worden gedefinieerd om deze API te gebruiken.

"action"

Als je de browser.action API wilt gebruiken, voer je een "manifest_version" van 3 in en neem je de "action"-sleutel op in je manifestbestand.

{
  "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 onderliggende sleutels) is optioneel. Als je dit niet opneemt, wordt je extensie nog steeds getoond in de werkbalk om toegang te bieden tot het menu van de extensie. Daarom raden we je aan altijd minstens de sleutels "action" en "default_icon" op te nemen.

Concepten en gebruik

Onderdelen van de UI

Icoon

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

De sleutel "default_icon" is een woordenboek met formaten voor afbeeldingspaden. Chrome gebruikt deze iconen om te kiezen welke afbeeldingsschaal moet worden gebruikt. Als er geen exacte overeenkomst wordt gevonden, selecteert Chrome de dichtstbijzijnde beschikbare afbeelding en schaalt deze zodat deze in de afbeelding past. Dit kan de afbeeldingskwaliteit beïnvloeden.

Omdat apparaten met minder gebruikelijke schaalfactoren zoals 1,5x of 1,2x steeds vaker voorkomen, raden we je aan meerdere formaten voor je iconen te bieden. Zo is je extensie ook toekomstbestendig tegen mogelijke wijzigingen in de weergavegrootte van iconen. Als je maar één formaat aanbiedt, kun je de sleutel "default_icon" ook instellen op een tekenreeks met het pad naar één icoon in plaats van een woordenboek.

Je kunt ook action.setIcon() aanroepen om het icoon van je extensie programmatisch in te stellen door een ander afbeeldingspad op te geven of een dynamisch gegenereerd icoon te leveren via het HTML-canvaselement of, als je dit instelt vanuit een extensie-serviceworker, 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 ingepakte extensies (geïnstalleerd vanuit een .crx-bestand) kunnen afbeeldingen de meeste indelingen hebben die de Blink-rendering-engine kan weergeven, waaronder png, jpeg, bmp en ico. Svg wordt niet ondersteund. Uitgepakte extensies moeten png-afbeeldingen gebruiken.

Tooltip (titel)

De tooltip of titel verschijnt als de gebruiker de cursor op het icoon van de extensie in de werkbalk houdt. De tekst is ook opgenomen in de toegankelijke tekst die door schermlezers wordt uitgesproken als de knop de focus krijgt.

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

Badge

Acties kunnen optioneel een badge tonen: een stukje tekst over het icoon. Hiermee kun je de actie updaten om een kleine hoeveelheid informatie over de status van de extensie te tonen, zoals een teller. De badge heeft een tekstcomponent en een achtergrondkleur. Omdat de ruimte beperkt is, raden we je aan badgetekst van maximaal 4 tekens te gebruiken.

Als je een badge wilt maken, stel je deze programmatisch in door action.setBadgeBackgroundColor() en action.setBadgeText() aan te roepen. Er is geen standaard badge-instelling in het manifest. De kleurwaarden van de badge kunnen een array zijn van 4 gehele getallen tussen 0 en 255 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
  () => { /* ... */ },
);

De pop-up van een actie wordt getoond als de gebruiker op de actieknop van de extensie in de werkbalk klikt. De pop-up kan elke gewenste HTML-content bevatten en wordt automatisch aangepast aan de content. Het formaat van de pop-up moet tussen 25 x 25 en 800 x 600 pixels zijn.

De pop-up wordt in eerste instantie ingesteld door de property "default_popup" in de sleutel "action" in het bestand manifest.json. Als deze property aanwezig is, moet deze verwijzen naar een relatief pad in de extensiemap. Je kunt de methode action.setPopup() gebruiken om de relatieve paden dynamisch te updaten.

Toepassingen

Status per tabblad

Extensieacties kunnen voor elk tabblad verschillende statussen hebben. Als je een waarde voor een afzonderlijk tabblad wilt instellen, gebruik je de property tabId in de instellingsmethoden van de action API. Als je bijvoorbeeld de badgetekst voor een specifiek tabblad wilt instellen, doe je iets als dit:

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

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

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

Aangezette status

Standaard staan werkbalkacties aan (klikbaar) op elk tabblad. Je kunt deze standaardinstelling wijzigen door de property default_state in te stellen in de sleutel action van het manifest. Als default_state is ingesteld op "disabled", staat de actie standaard uit en moet deze programmatisch worden aangezet om klikbaar te zijn. Als default_state is ingesteld op "enabled" (de standaardinstelling), staat de actie standaard aan en is deze klikbaar.

U kunt de status programmatisch beheren met de methoden action.enable() en action.disable(). Dit heeft alleen invloed op de vraag of de pop-up (indien aanwezig) of de gebeurtenis action.onClicked naar je extensie wordt gestuurd. Het heeft geen invloed op de aanwezigheid van de actie in de werkbalk.

Voorbeelden

In de volgende voorbeelden zie je een aantal veelvoorkomende manieren waarop acties in extensies worden gebruikt. Als je deze API wilt proberen, installeer je het voorbeeld van de Action API uit de repository chrome-extension-samples.

Een pop-up tonen

Het is gebruikelijk dat een extensie een pop-up toont als de gebruiker op de actie van de extensie klikt. Als je dit in je eigen extensie wilt implementeren, declareer je de pop-up in je manifest.json en geef je de content aan die Chrome in de pop-up moet tonen.

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

Een contentscript injecteren bij een klik

Een veelvoorkomend patroon voor extensies is om hun primaire functie beschikbaar te maken via de actie van de extensie. In het volgende voorbeeld wordt dit patroon getoond. Als de gebruiker op de actie klikt, injecteert de extensie een contentscript in de huidige pagina. Het contentscript toont dan een melding om te verifiëren dat alles werkt zoals verwacht.

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

Acties emuleren met declarativeContent

In dit voorbeeld zie je hoe de achtergrondlogica van een extensie (a) een actie standaard kan uitzetten en (b) declarativeContent kan gebruiken om de actie op specifieke sites aan te zetten.

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

Typen

OpenPopupOptions

Chrome 99 of hoger browser.* sinds Chrome 148

Eigenschappen

  • windowId

    number optioneel

    De ID van het venster waarin de actiepop-up moet worden geopend. De standaardwaarde is het momenteel actieve venster als er geen waarde is ingevoerd.

TabDetails

Eigenschappen

  • tabId

    number optioneel

    De ID van het tabblad waarvoor je de status wilt opvragen. Als er geen tabblad is opgegeven, wordt de niet-tabbladspecifieke status geretourneerd.

UserSettings

Chrome 91+ browser.* sinds Chrome 148

De verzameling door de gebruiker ingevoerde instellingen voor de actie van een extensie.

Eigenschappen

  • isOnToolbar

    booleaans

    Of het actie-icoon van de extensie zichtbaar is op de werkbalk op het hoogste niveau van browservensters (dat wil zeggen of de extensie is vastgezet door de gebruiker).

UserSettingsChange

Chrome 130+ browser.* sinds Chrome 148

Eigenschappen

  • isOnToolbar

    booleaans optioneel

    Of het actie-icoon van de extensie zichtbaar is op de werkbalk op het hoogste niveau van browservensters (dat wil zeggen of de extensie is vastgezet door de gebruiker).

Methoden

disable()

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

Zet de actie voor een tabblad uit.

Parameters

  • tabId

    number optioneel

    De ID van het tabblad waarvoor je de actie wilt aanpassen.

Retourzendingen

  • Promise<void>

enable()

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

Zet de actie voor een tabblad aan. Acties staan standaard aan.

Parameters

  • tabId

    number optioneel

    De ID van het tabblad waarvoor je de actie wilt aanpassen.

Retourzendingen

  • Promise<void>

getBadgeBackgroundColor()

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

Haalt de achtergrondkleur van de actie op.

Parameters

Retourzendingen

getBadgeText()

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

Haalt de badgetekst van de actie op. Als er geen tabblad is opgegeven, wordt de niet-tabbladspecifieke badgetekst geretourneerd. Als displayActionCountAsBadgeText aanstaat, wordt er een tijdelijke aanduidingstekst geretourneerd, tenzij het recht declarativeNetRequestFeedback aanwezig is of er tabbladspecifieke badgetekst is verstrekt.

Parameters

Retourzendingen

  • Promise<string>

getBadgeTextColor()

Chrome 110 of hoger browser.* sinds Chrome 148 
browser.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

Haalt de tekstkleur van de actie op.

Parameters

Retourzendingen

getPopup()

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

Haalt het HTML-document op dat is ingesteld als de pop-up voor deze actie.

Parameters

Retourzendingen

  • Promise<string>

getTitle()

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

Haalt de titel van de actie op.

Parameters

Retourzendingen

  • Promise<string>

getUserSettings()

Chrome 91+ browser.* sinds Chrome 148 
browser.action.getUserSettings(): Promise<UserSettings>

Retourneert de door de gebruiker ingevoerde instellingen voor de actie van een extensie.

Retourzendingen

isEnabled()

Chrome 110 of hoger browser.* sinds Chrome 148 
browser.action.isEnabled(
  tabId?: number,
): Promise<boolean>

Geeft aan of de extensieactie aanstaat voor een tabblad (of wereldwijd als er geen tabId is verstrekt). Acties die alleen met declarativeContent zijn aangezet, retourneren altijd onwaar.

Parameters

  • tabId

    number optioneel

    De ID van het tabblad waarvoor je de aangezette status wilt controleren.

Retourzendingen

  • Promise<boolean>

openPopup()

Chrome 127+ browser.* sinds Chrome 148 
browser.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

Opent de pop-up van de extensie. Tussen Chrome 118 en Chrome 126 is dit alleen beschikbaar voor extensies die via beleid zijn geïnstalleerd.

Parameters

  • opties

    OpenPopupOptions optioneel

    Hiermee geef je opties op om de pop-up te openen.

Retourzendingen

  • Promise<void>

setBadgeBackgroundColor()

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

Hiermee stelt u de achtergrondkleur van de badge in.

Parameters

  • details

    object

    • kleur

      string | ColorArray

      Een matrix van 4 gehele getallen in het bereik [0,255] die de RGBA-kleur van de badge vormen. Ondoorzichtig rood is bijvoorbeeld [255, 0, 0, 255]. Kan ook een tekenreeks met een CSS-waarde zijn, waarbij ondoorzichtig rood #FF0000 of #F00 is.

    • tabId

      number optioneel

      Beperkt de wijziging tot wanneer een bepaald tabblad is geselecteerd. Wordt automatisch gereset als het tabblad wordt gesloten.

Retourzendingen

  • Promise<void>

setBadgeText()

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

Stelt de badgetekst voor de actie in. De badge wordt boven het icoon getoond.

Parameters

  • details

    object

    • tabId

      number optioneel

      Beperkt de wijziging tot wanneer een bepaald tabblad is geselecteerd. Wordt automatisch gereset als het tabblad wordt gesloten.

    • tekst

      tekenreeks optioneel

      U kunt een onbeperkt aantal tekens doorgeven, maar er passen er maar ongeveer 4 in de ruimte. Als er een lege tekenreeks ('') wordt doorgegeven, wordt de badgetekst gewist. Als tabId is ingevoerd en text is null, wordt de tekst voor het ingevoerde tabblad gewist en wordt de algemene badgetekst gebruikt.

Retourzendingen

  • Promise<void>

setBadgeTextColor()

Chrome 110 of hoger browser.* sinds Chrome 148 
browser.action.setBadgeTextColor(
  details: object,
): Promise<void>

Stelt de tekstkleur voor de badge in.

Parameters

  • details

    object

    • kleur

      string | ColorArray

      Een matrix van 4 gehele getallen in het bereik [0,255] die de RGBA-kleur van de badge vormen. Ondoorzichtig rood is bijvoorbeeld [255, 0, 0, 255]. Kan ook een tekenreeks met een CSS-waarde zijn, waarbij ondoorzichtig rood #FF0000 of #F00 is. Als je deze waarde niet instelt, wordt er automatisch een kleur gekozen die contrasteert met de achtergrondkleur van de badge, zodat de tekst zichtbaar is. Kleuren met alfawaarden die gelijk zijn aan 0, worden niet ingesteld en retourneren een fout.

    • tabId

      number optioneel

      Beperkt de wijziging tot wanneer een bepaald tabblad is geselecteerd. Wordt automatisch gereset als het tabblad wordt gesloten.

Retourzendingen

  • Promise<void>

setIcon()

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

Stelt het icoon voor de actie in. Het icoon kan worden gespecificeerd als het pad naar een afbeeldingsbestand of als de pixelgegevens van een canvaselement, of als woordenboek van een van beide. De property path of imageData moet worden opgegeven.

Parameters

  • details

    object

    • imageData

      ImageData | object optioneel

      Een ImageData-object of een woordenboek {size -> ImageData} dat het icoon vertegenwoordigt dat moet worden ingesteld. Als het icoon is gespecificeerd als een woordenboek, wordt de daadwerkelijke afbeelding die wordt gebruikt, gekozen op basis van de pixeldichtheid van het scherm. Als het aantal afbeeldingspixels dat in één schermruimte-eenheid past gelijk is aan scale, wordt de afbeelding met de grootte scale * n geselecteerd, waarbij n de grootte van het icoon in de UI is. Er moet minstens één afbeelding worden ingevoerd. Let op: 'details.imageData = foo' is gelijk aan 'details.imageData = {'16': foo}'

    • pad

      string | object optioneel

      Een relatief afbeeldingspad of een woordenboek {size -> relative image path} dat verwijst naar het icoon dat moet worden ingesteld. Als het icoon is gespecificeerd als een woordenboek, wordt de daadwerkelijke afbeelding die wordt gebruikt, gekozen op basis van de pixeldichtheid van het scherm. Als het aantal afbeeldingspixels dat in één schermruimte-eenheid past gelijk is aan scale, wordt de afbeelding met de grootte scale * n geselecteerd, waarbij n de grootte van het icoon in de UI is. Er moet minstens één afbeelding worden ingevoerd. 'details.path = foo' is gelijk aan 'details.path = {'16': foo}'

    • tabId

      number optioneel

      Beperkt de wijziging tot wanneer een bepaald tabblad is geselecteerd. Wordt automatisch gereset als het tabblad wordt gesloten.

Retourzendingen

  • Promise<void>

    Chrome 96+ browser.* sinds Chrome 148

setPopup()

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

Stelt in dat het HTML-document wordt geopend als pop-up wanneer de gebruiker op het icoon van de actie klikt.

Parameters

  • details

    object

    • pop-up

      tekenreeks

      Het relatieve pad naar het HTML-bestand dat in een pop-up moet worden getoond. Als je dit beleid instelt op de lege tekenreeks (''), wordt er geen pop-up getoond.

    • tabId

      number optioneel

      Beperkt de wijziging tot wanneer een bepaald tabblad is geselecteerd. Wordt automatisch gereset als het tabblad wordt gesloten.

Retourzendingen

  • Promise<void>

setTitle()

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

Hiermee wordt de titel van de actie ingesteld. Dit wordt getoond in de tooltip.

Parameters

  • details

    object

    • tabId

      number optioneel

      Beperkt de wijziging tot wanneer een bepaald tabblad is geselecteerd. Wordt automatisch gereset als het tabblad wordt gesloten.

    • titel

      tekenreeks

      De tekenreeks die de actie moet tonen als de muisaanwijzer erop wordt geplaatst.

Retourzendingen

  • Promise<void>

Evenementen

onClicked

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

Wordt geactiveerd als er op een actie-icoon wordt geklikt. Deze gebeurtenis wordt niet geactiveerd als de actie een pop-up heeft.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

    (tab: tabs.Tab) => void

onUserSettingsChanged

Chrome 130+ browser.* sinds Chrome 148 
browser.action.onUserSettingsChanged.addListener(
  callback: function,
)

Wordt geactiveerd als door de gebruiker ingevoerde instellingen voor de actie van een extensie worden gewijzigd.

Parameters