chrome.browserAction

refresh date: 2026-09-25 robots: noindex

Beschrijving

Gebruik browseracties om iconen in de hoofdwerkbalk van Google Chrome te plaatsen, rechts van de adresbalk. Naast het icoon kan een browseractie een tooltip, een badge en een pop-up hebben.

Beschikbaarheid

≤ MV2

In de volgende afbeelding is het veelkleurige vierkant rechts van de adresbalk het icoon voor een browseractie. Onder het icoon staat een pop-up.

Als je een icoon wilt maken dat niet altijd actief is, gebruik je een pagina-actie in plaats van een browseractie.

Manifest

Registreer je browseractie als volgt in het extensiemanifest:

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

Je kunt een icoon van elk formaat opgeven voor gebruik in Chrome. Chrome selecteert het icoon dat het dichtst bij het juiste formaat ligt en schaalt het naar het juiste formaat om de ruimte van 16 dip te vullen. Als het exacte formaat niet wordt verstrekt, kan deze schaling ertoe leiden dat het icoon details verliest of er wazig uitziet.

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. Dit zorgt er ook voor dat als de weergavegrootte van het icoon ooit wordt gewijzigd, je geen extra werk hoeft te doen om verschillende iconen te leveren.

De oude syntaxis voor de registratie van het standaardicoon wordt nog steeds ondersteund:

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Onderdelen van de UI

Een browseractie kan een icoon, een tooltip, een badge en een pop-up hebben.

Icoon

De iconen voor browseracties in Chrome zijn 16 dips (apparaatonafhankelijke pixels) breed en hoog. Grotere iconen worden aangepast, maar voor de beste resultaten gebruik je een vierkant icoon van 16 dip.

Je kunt het icoon op 2 manieren instellen: met een statische afbeelding of met het HTML5-canvaselement. Het gebruik van statische afbeeldingen is makkelijker voor eenvoudige apps, maar je kunt dynamischere UI's maken, zoals vloeiende animaties, met het canvaselement.

Statische afbeeldingen kunnen elke indeling hebben die WebKit kan weergeven, waaronder bmp, gif, ico, jpeg of png. Voor uitgepakte extensies moeten afbeeldingen de png-indeling hebben.

Als je het icoon wilt instellen, gebruik je het veld default_icon van browser_action in het manifest of roep je de methode browserAction.setIcon aan.

Als je het icoon correct wilt weergeven als de pixeldichtheid van het scherm (verhouding size_in_pixel / size_in_dip) niet 1 is, kun je het icoon definiëren als een set afbeeldingen met verschillende formaten. De werkelijke afbeelding die wordt getoond, wordt geselecteerd uit de set die het beste past bij de pixelgrootte van 16 dip. De iconenset kan iconen van elke grootte bevatten. Chrome selecteert het meest geschikte icoon.

Tooltip

Als je de tooltip wilt instellen, gebruik je het veld default_title van browser_action in het manifest of roep je de methode browserAction.setTitle aan. Je kunt landspecifieke tekenreeksen opgeven voor het veld default_title. Ga naar Internationalisering voor meer informatie.

Badge

Browseracties kunnen optioneel een badge tonen: een stukje tekst dat over het icoon is geplaatst. Met badges kun je de browseractie makkelijk updaten om een kleine hoeveelheid informatie over de status van de extensie te tonen.

Omdat de badge beperkte ruimte heeft, mag deze maximaal 4 tekens bevatten.

Stel de tekst en kleur van de badge in met respectievelijk browserAction.setBadgeText en browserAction.setBadgeBackgroundColor.

Als een browseractie een pop-up heeft, verschijnt de pop-up wanneer de gebruiker op het icoon van de extensie klikt. De pop-up kan elke gewenste HTML-content bevatten en wordt automatisch aangepast aan de content. De pop-up mag niet kleiner zijn dan 25 x 25 en niet groter dan 800 x 600.

Als je een pop-up aan je browseractie wilt toevoegen, maak je een HTML-bestand met de content van de pop-up. Voer het HTML-bestand in het veld default_popup van browser_action in het manifest in of roep de methode browserAction.setPopup aan.

Tips

Volg deze richtlijnen voor de beste visuele impact:

  • Wel doen: Gebruik browseracties voor functies die op de meeste pagina's zinvol zijn.
  • Gebruik geen browseracties voor functies die maar voor een paar pagina's zinvol zijn. Gebruik in plaats daarvan pagina-acties.
  • Wel doen: Gebruik grote, kleurrijke iconen die de ruimte van 16 x 16 dip optimaal benutten. Iconen voor browseracties moeten iets groter en zwaarder lijken dan iconen voor pagina-acties.
  • Probeer niet het monochrome menu-icoon van Google Chrome na te bootsen. Dat werkt niet goed met thema's en extensies moeten toch een beetje opvallen.
  • Gebruik alfa-transparantie om zachte randen aan je icoon toe te voegen. Omdat veel mensen thema's gebruiken, moet je icoon er goed uitzien op verschillende achtergrondkleuren.
  • Animeer je icoon niet voortdurend. Dat is gewoon irritant.

Voorbeelden

In de directory examples/api/browserAction vind je eenvoudige voorbeelden van het gebruik van browseracties. Ga naar Samples voor andere voorbeelden en hulp bij het bekijken van de broncode.

Typen

TabDetails

Chrome 88+

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.

Methoden

disable()

Promise 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

Zet de browseractie voor een tabblad uit.

Parameters

  • tabId

    number optioneel

    De ID van het tabblad waarvoor de browseractie moet worden aangepast.

  • callback

    functie optioneel

    Chrome 67+

    De parameter callback ziet er zo uit: 

    () => void

Retourzendingen

  • Promise<void>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

enable()

Promise 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

Hiermee wordt de browseractie voor een tabblad aangezet. Staat standaard aan.

Parameters

  • tabId

    number optioneel

    De ID van het tabblad waarvoor de browseractie moet worden aangepast.

  • callback

    functie optioneel

    Chrome 67+

    De parameter callback ziet er zo uit: 

    () => void

Retourzendingen

  • Promise<void>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

Haalt de achtergrondkleur van de browseractie op.

Parameters

Retourzendingen

  • Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getBadgeText()

Promise 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

Haalt de badgetekst van de browseractie op. Als er geen tabblad is opgegeven, wordt de niet-tabbladspecifieke badgetekst geretourneerd.

Parameters

  • details

    TabDetails

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (result: string) => void

    • resultaat

      tekenreeks

Retourzendingen

  • Promise<string>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getPopup()

Promise 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

Parameters

  • details

    TabDetails

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (result: string) => void

    • resultaat

      tekenreeks

Retourzendingen

  • Promise<string>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getTitle()

Promise 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

Haalt de titel van de browseractie op.

Parameters

  • details

    TabDetails

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (result: string) => void

    • resultaat

      tekenreeks

Retourzendingen

  • Promise<string>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): 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. Kan ook een tekenreeks zijn met een hexadecimale CSS-kleurwaarde, bijvoorbeeld #FF0000 of #F00 (rood). Geeft kleuren weer met volledige dekking.

    • tabId

      number optioneel

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

  • callback

    functie optioneel

    Chrome 67+

    De parameter callback ziet er zo uit: 

    () => void

Retourzendingen

  • Promise<void>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

setBadgeText()

Promise 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

Stelt de badgetekst voor de browseractie 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.

  • callback

    functie optioneel

    Chrome 67+

    De parameter callback ziet er zo uit: 

    () => void

Retourzendingen

  • Promise<void>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

setIcon()

Promise 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

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

Parameters

  • details

    object

    • imageData

      ImageData | object optioneel

      Een ImageData-object of een woordenboek {size -> ImageData} dat een icoon vertegenwoordigt dat moet worden ingesteld. Als het icoon is gespecificeerd als een woordenboek, wordt de gebruikte afbeelding gekozen op basis van de pixeldichtheid van het scherm. Als het aantal afbeeldingspixels dat in één schermruimte-eenheid past gelijk is aan scale, wordt een 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 een icoon dat moet worden ingesteld. Als het icoon is gespecificeerd als een woordenboek, wordt de gebruikte afbeelding gekozen op basis van de pixeldichtheid van het scherm. Als het aantal afbeeldingspixels dat in één schermruimte-eenheid past gelijk is aan scale, wordt een 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.

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    () => void

Retourzendingen

  • Promise<void>

    Chrome 116 of hoger

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

setPopup()

Promise 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

Stelt het html-document in dat als pop-up moet worden geopend wanneer de gebruiker op het icoon voor de browseractie 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.

  • callback

    functie optioneel

    Chrome 67+

    De parameter callback ziet er zo uit: 

    () => void

Retourzendingen

  • Promise<void>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

setTitle()

Promise 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

Hiermee wordt de titel van de browseractie ingesteld. Deze titel verschijnt 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 browseractie moet tonen als de muisaanwijzer erop wordt geplaatst.

  • callback

    functie optioneel

    Chrome 67+

    De parameter callback ziet er zo uit: 

    () => void

Retourzendingen

  • Promise<void>

    Chrome 88+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

Evenementen

onClicked

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

Wordt geactiveerd als er op een icoon voor een browseractie wordt geklikt. Wordt niet geactiveerd als de browseractie een pop-up heeft.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

    (tab: tabs.Tab) => void