chroom.actie

Beschrijving

Beschikbaarheid

Manifest

Als u de chrome.action API wilt gebruiken, geeft u 3 op voor "manifest_version" en neemt u de sleutel "action" op in uw 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 "action" -toets (en de bijbehorende subtoetsen) is optioneel. Wanneer deze niet is opgenomen, wordt uw extensie nog steeds weergegeven in de werkbalk om toegang te bieden tot het menu van de extensie. Daarom raden we aan om altijd ten minste de toetsen "action" en "default_icon" op te nemen.

Begrippen en gebruik

Onderdelen van de gebruikersinterface

Icon

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

De sleutel "default_icon" is een woordenboek met afmetingen voor afbeeldingspaden. Chrome gebruikt deze pictogrammen om te kiezen welke afbeeldingsschaal moet worden gebruikt. Als er geen exacte match wordt gevonden, selecteert Chrome de dichtstbijzijnde beschikbare en schaalt deze naar de afbeelding, wat de beeldkwaliteit kan beïnvloeden.

Omdat apparaten met minder gebruikelijke schaalfactoren zoals 1,5x of 1,2x steeds gebruikelijker worden, raden we u aan meerdere groottes voor uw pictogrammen op te geven. Dit beschermt uw extensie ook tegen mogelijke wijzigingen in de weergavegrootte van pictogrammen in de toekomst. Als u echter slechts één grootte opgeeft, kan de sleutel "default_icon" ook worden ingesteld op een tekenreeks met het pad naar één pictogram in plaats van een woordenboek.

U kunt ook action.setIcon() aanroepen om het pictogram van uw extensie programmatisch in te stellen door een ander afbeeldingspad op te geven of door een dynamisch gegenereerd pictogram te verstrekken met behulp van het HTML-canvaselement of, als u de instelling uitvoert via een extensieserviceworker, 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);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

Voor ingepakte 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. Uitgepakte extensies moeten PNG-afbeeldingen gebruiken.

Tooltip (titel)

De tooltip, of titel, verschijnt wanneer de gebruiker de muisaanwijzer op het pictogram van de extensie in de werkbalk houdt. Deze wordt ook opgenomen in de toegankelijke tekst die door schermlezers wordt uitgesproken 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 . U kunt deze ook programmatisch instellen door action.setTitle() aan te roepen.

Insigne

Acties kunnen optioneel een 'badge' weergeven: een stukje tekst over het pictogram. Hiermee kunt u de actie bijwerken en een kleine hoeveelheid informatie over de status van de extensie weergeven, zoals een teller. De badge heeft een tekstcomponent en een achtergrondkleur. Omdat de ruimte beperkt is, raden we aan om de badgetekst vier of minder tekens te laten bevatten.

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

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

De pop-up van een actie wordt weergegeven wanneer de gebruiker op de actieknop van de extensie in de werkbalk klikt. De pop-up kan elke gewenste HTML-inhoud bevatten en wordt automatisch aangepast aan de inhoud. De grootte van de pop-up moet tussen 25x25 en 800x600 pixels liggen.

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

Gebruiksscenario's

Status per tabblad

Extensieacties kunnen voor elk tabblad een verschillende status hebben. Om een ​​waarde voor een afzonderlijk tabblad in te stellen, gebruikt u de eigenschap tabId in de instellingsmethoden van de action API. Om bijvoorbeeld de badgetekst voor een specifiek tabblad in te stellen, doet u het volgende:

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

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

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

Ingeschakelde status

Standaard zijn acties op de werkbalk ingeschakeld (klikbaar) op elk tabblad. U kunt deze standaardinstelling wijzigen door de eigenschap default_state in de action 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 standaardinstelling), is de actie standaard ingeschakeld en 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 uw extensie wordt verzonden; het heeft geen invloed op de aanwezigheid van de actie in de werkbalk.

Voorbeelden

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

Pop-up weergeven

Het is gebruikelijk dat een extensie een pop-up weergeeft wanneer de gebruiker op de actie van de extensie klikt. Om dit in uw eigen extensie te implementeren, declareert u de pop-up in uw manifest.json en specificeert u de inhoud die 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>

Injecteer een inhoudsscript bij een klik

Een veelvoorkomend patroon voor extensies is het beschikbaar stellen van hun primaire functie via de actie van de extensie. Het volgende voorbeeld illustreert dit patroon. Wanneer de gebruiker op de actie klikt, injecteert de extensie een contentscript in de huidige pagina. Het 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
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

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

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)