chrome.browserAction

Beschrijving

Gebruik browseracties om pictogrammen in de hoofdwerkbalk van Google Chrome te plaatsen, rechts van de adresbalk. Naast het pictogram kan een browseractie ook knopinfo , een badge en een pop-up bevatten.

Beschikbaarheid

≤ MV2

In de volgende afbeelding is het veelkleurige vierkant rechts van de adresbalk het pictogram voor een browseractie. Onder het pictogram bevindt zich een pop-up.

Als u een pictogram wilt maken dat niet altijd actief is, gebruikt u een paginaactie in plaats van een browseractie.

Manifest

Registreer uw 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
  },
  ...
}

U kunt elk pictogram van elk formaat opgeven dat in Chrome moet worden gebruikt, en Chrome selecteert het dichtstbijzijnde pictogram en schaalt dit naar het juiste formaat om de ruimte van 16 dips te vullen. Als de exacte grootte echter niet wordt opgegeven, kan deze schaal ertoe leiden dat het pictogram details verliest of er wazig uitziet.

Omdat apparaten met minder gebruikelijke schaalfactoren zoals 1,5x of 1,2x steeds gebruikelijker worden, wordt u aangeraden meerdere formaten voor uw pictogrammen op te geven. Dit zorgt er ook voor dat als de weergavegrootte van het pictogram ooit wordt gewijzigd, u geen werk meer hoeft te doen om verschillende pictogrammen aan te bieden!

De oude syntaxis voor het registreren van het standaardpictogram wordt nog steeds ondersteund:

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

Delen van de gebruikersinterface

Een browseractie kan een pictogram , knopinfo , een badge en een pop-up bevatten.

Icon

De browseractiepictogrammen in Chrome zijn 16 dips (apparaatonafhankelijke pixels) breed en hoog. Grotere pictogrammen worden aangepast zodat ze passen, maar voor de beste resultaten gebruikt u een vierkant pictogram met 16 dips.

U kunt het pictogram op twee manieren instellen: door een statische afbeelding te gebruiken of door het HTML5- canvaselement te gebruiken. Het gebruik van statische afbeeldingen is gemakkelijker voor eenvoudige toepassingen, maar u kunt dynamischere gebruikersinterfaces (zoals vloeiende animaties) maken met behulp van het canvaselement.

Statische afbeeldingen kunnen elk formaat hebben dat WebKit kan weergeven, inclusief BMP, GIF, ICO, JPEG of PNG. Voor uitgepakte extensies moeten afbeeldingen de PNG-indeling hebben.

Om het pictogram in te stellen, gebruikt u het veld default_icon van browser_action in het manifest of roept u de methode browserAction.setIcon aan.

Om het pictogram correct weer te geven wanneer de pixeldichtheid van het scherm (verhouding size_in_pixel / size_in_dip ) anders is dan 1, kan het pictogram worden gedefinieerd als een reeks afbeeldingen met verschillende formaten. De feitelijk weer te geven afbeelding wordt uit de set geselecteerd zodat deze het beste past bij de pixelgrootte van 16 dip. De pictogrammenset kan pictogramspecificaties van elk formaat bevatten en Chrome selecteert de meest geschikte.

Tooltip

Om de tooltip in te stellen, gebruikt u het veld default_title van browser_action in het manifest of roept u de methode browserAction.setTitle aan. U kunt landspecifieke tekenreeksen opgeven voor het veld default_title ; zie Internationalisering voor details.

Kenteken

Browseracties kunnen optioneel een badge weergeven: een stukje tekst dat over het pictogram is gelaagd. Badges maken het eenvoudig om de browseractie bij te werken en een kleine hoeveelheid informatie over de status van de extensie weer te geven.

Omdat de badge beperkte ruimte heeft, moet deze maximaal vier 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 pictogram van de extensie klikt. De pop-up kan elke gewenste HTML-inhoud bevatten en wordt automatisch aangepast aan de inhoud ervan. De pop-up mag niet kleiner zijn dan 25x25 en niet groter dan 800x600.

Om een ​​pop-up aan uw browseractie toe te voegen, maakt u een HTML-bestand met de inhoud van de pop-up. Geef het HTML-bestand op in het veld default_popup van browser_action in het manifest of roep de methode browserAction.setPopup aan.

Tips

Volg deze richtlijnen voor de beste visuele impact:

  • Gebruik browseracties voor functies die op de meeste pagina's zinvol zijn.
  • Gebruik geen browseracties voor functies die slechts voor een paar pagina's zinvol zijn. Gebruik in plaats daarvan paginaacties .
  • Gebruik grote, kleurrijke pictogrammen die de ruimte van 16x16 dips optimaal benutten. Browseractiepictogrammen moeten iets groter en zwaarder lijken dan paginaactiepictogrammen.
  • Probeer niet het monochrome menupictogram van Google Chrome na te bootsen. Dat werkt niet goed met thema's, en hoe dan ook, extensies zouden een beetje moeten opvallen.
  • Gebruik alfatransparantie om zachte randen aan uw pictogram toe te voegen. Omdat veel mensen thema's gebruiken, moet uw pictogram er mooi uitzien op verschillende achtergrondkleuren.
  • Animeer uw pictogram niet voortdurend. Dat is gewoon vervelend.

Voorbeelden

U kunt eenvoudige voorbeelden van het gebruik van browseracties vinden in de map example/api/browserAction . Zie Voorbeelden voor andere voorbeelden en voor hulp bij het bekijken van de broncode.

Soorten

ColorArray

Type

[nummer, nummer, nummer, nummer]

ImageDataType

Pixelgegevens voor een afbeelding. Moet een ImageData-object zijn; bijvoorbeeld van een canvas .

Type

Beeldgegevens

TabDetails

Chroom 88+

Eigenschappen

  • tabId

    nummer optioneel

    De ID van het tabblad waarvoor de status moet worden opgevraagd. Als er geen tabblad is opgegeven, wordt de niet-tabbladspecifieke status geretourneerd.

Methoden

disable()

Belofte
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

Schakelt de browseractie voor een tabblad uit.

Parameters

  • tabId

    nummer optioneel

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

  • terugbellen

    functie optioneel

    Chroom 67+

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

enable()

Belofte
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

Schakelt de browseractie voor een tabblad in. Standaard ingesteld op ingeschakeld.

Parameters

  • tabId

    nummer optioneel

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

  • terugbellen

    functie optioneel

    Chroom 67+

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

getBadgeBackgroundColor()

Belofte
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

Haalt de achtergrondkleur van de browseractie op.

Parameters

Retouren

  • Beloof < ColorArray >

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

getBadgeText()

Belofte
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

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

Parameters

  • details

    TabbladDetails

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (result: string) => void

    • resultaat

      snaar

Retouren

  • Beloof<tekenreeks>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

getPopup()

Belofte
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

Parameters

  • details

    TabbladDetails

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (result: string) => void

    • resultaat

      snaar

Retouren

  • Beloof<tekenreeks>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

getTitle()

Belofte
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Haalt de titel van de browseractie op.

Parameters

  • details

    TabbladDetails

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (result: string) => void

    • resultaat

      snaar

Retouren

  • Beloof<tekenreeks>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

setBadgeBackgroundColor()

Belofte
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Stelt de achtergrondkleur voor de badge in.

Parameters

  • details

    voorwerp

    • kleur

      tekenreeks | KleurArray

      Een array van vier gehele getallen in het bereik 0-255 die de RGBA-kleur van de badge vormen. Kan ook een tekenreeks zijn met een CSS-hexadecimale kleurwaarde; bijvoorbeeld #FF0000 of #F00 (rood). Geeft kleuren weer met volledige dekking.

    • tabId

      nummer optioneel

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

  • terugbellen

    functie optioneel

    Chroom 67+

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

setBadgeText()

Belofte
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

Stelt de badgetekst in voor de browseractie. De badge wordt bovenaan het pictogram weergegeven.

Parameters

  • details

    voorwerp

    • tabId

      nummer optioneel

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

    • tekst

      tekenreeks optioneel

      Er kan een willekeurig aantal tekens worden doorgegeven, maar er passen er slechts ongeveer vier in de ruimte. Als een lege string ( '' ) wordt doorgegeven, wordt de badgetekst gewist. Als tabId is opgegeven en text null is, wordt de tekst voor het opgegeven tabblad gewist en wordt standaard de algemene badgetekst gebruikt.

  • terugbellen

    functie optioneel

    Chroom 67+

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

setIcon()

Belofte
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

Stelt het pictogram voor de browseractie in. Het pictogram kan worden opgegeven als het pad naar een afbeeldingsbestand, als de pixelgegevens van een canvaselement, of als een woordenboek van een daarvan. Het path of de eigenschap imageData moet worden opgegeven.

Parameters

  • details

    voorwerp

    • afbeeldingGegevens

      Beeldgegevens | object optioneel

      Een ImageData-object of een woordenboek {size -> ImageData} die een in te stellen pictogram vertegenwoordigt. Als het pictogram als woordenboek is opgegeven, wordt de gebruikte afbeelding gekozen op basis van de pixeldichtheid van het scherm. Als het aantal beeldpixels dat in één schermruimte-eenheid past gelijk is aan scale , dan wordt een afbeelding met scale * n geselecteerd, waarbij n de grootte is van het pictogram in de gebruikersinterface. Er moet ten minste één afbeelding worden opgegeven. Houd er rekening mee dat 'details.imageData = foo' gelijk is aan 'details.imageData = {'16': foo}'

    • pad

      tekenreeks | object optioneel

      Ofwel een relatief afbeeldingspad, ofwel een woordenboek {grootte -> relatief afbeeldingspad} dat naar een in te stellen pictogram verwijst. Als het pictogram als woordenboek is opgegeven, wordt de gebruikte afbeelding gekozen op basis van de pixeldichtheid van het scherm. Als het aantal beeldpixels dat in één schermruimte-eenheid past gelijk is aan scale , dan wordt een afbeelding met scale * n geselecteerd, waarbij n de grootte is van het pictogram in de gebruikersinterface. Er moet ten minste één afbeelding worden opgegeven. Houd er rekening mee dat 'details.path = foo' gelijk is aan 'details.path = {'16': foo}'

    • tabId

      nummer optioneel

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

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 116+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

setPopup()

Belofte
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

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

Parameters

  • details

    voorwerp

    • pop-up

      snaar

      Het relatieve pad naar het HTML-bestand dat in een pop-up moet worden weergegeven. Indien ingesteld op de lege tekenreeks ( '' ), wordt er geen pop-up weergegeven.

    • tabId

      nummer optioneel

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

  • terugbellen

    functie optioneel

    Chroom 67+

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

setTitle()

Belofte
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

Stelt de titel van de browseractie in. Deze titel verschijnt in de tooltip.

Parameters

  • details

    voorwerp

    • tabId

      nummer optioneel

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

    • titel

      snaar

      De tekenreeks die de browseractie moet weergeven als er met de muis overheen wordt bewogen.

  • terugbellen

    functie optioneel

    Chroom 67+

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 88+

    Beloftes worden alleen ondersteund voor Manifest V3 en hoger, andere platforms moeten callbacks gebruiken.

Evenementen

onClicked

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

Wordt geactiveerd wanneer op een browseractiepictogram wordt geklikt. Wordt niet geactiveerd als de browseractie een pop-up heeft.

Parameters

  • terugbellen

    functie

    De callback parameter ziet er als volgt uit: 

    (tab: tabs.Tab) => void