chroom.actie

Beschrijving

Beschikbaarheid

Manifest

Als u de chrome.action API wilt gebruiken, geeft u een "manifest_version" van 3 op 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 (samen met de kinderen) is optioneel. Als deze niet is opgenomen, wordt uw extensie nog steeds weergegeven in de werkbalk om toegang te geven tot het menu van de extensie. Om deze reden raden wij u aan altijd minimaal de toetsen "action" en "default_icon" op te nemen.

Concepten en gebruik

Delen van de gebruikersinterface

Icon

Het pictogram is de hoofdafbeelding op de werkbalk van uw extensie en wordt ingesteld met de sleutel "default_icon" in de "action" -sleutel 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 overeenkomst wordt gevonden, selecteert Chrome de dichtstbijzijnde beschikbare en schaalt deze zodat deze bij de afbeelding past, wat de beeldkwaliteit kan beïnvloeden.

Omdat apparaten met minder gebruikelijke schaalfactoren zoals 1,5x of 1,2x steeds vaker voorkomen, raden we u aan 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 grootte biedt, kan de sleutel "default_icon" ook worden ingesteld op een tekenreeks met het pad naar een enkel pictogram in plaats van naar 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 een dynamisch gegenereerd pictogram op te geven met behulp van het HTML canvas-element , of, indien ingesteld door een extensieservicemedewerker, 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 de meeste formaten hebben die de Blink-rendering-engine kan weergeven, inclusief 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. Het is 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 dit ook programmatisch instellen door action.setTitle() aan te roepen.

Kenteken

Acties kunnen optioneel een "badge" weergeven: een stukje tekst over het pictogram heen. Hiermee kunt u de actie bijwerken zodat een kleine hoeveelheid informatie over de status van de extensie wordt weergegeven, zoals een teller. De badge heeft een tekstcomponent en een achtergrondkleur. Omdat de ruimte beperkt is, raden we aan dat badgetekst vier of minder tekens gebruikt.

Als u een badge wilt maken, stelt u deze programmatisch in door action.setBadgeBackgroundColor() en action.setBadgeText() aan te roepen. Er is geen standaardbadge-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.

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 ervan. De grootte van de pop-up moet tussen 25x25 en 800x600 pixels zijn.

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

Gebruiksgevallen

Staat per tabblad

Extensieacties kunnen voor elk tabblad een verschillende status hebben. Als u een waarde voor een afzonderlijk tabblad wilt instellen, gebruikt u de eigenschap tabId in de instellingsmethoden van de action API. Als u bijvoorbeeld de badgetekst voor een specifiek tabblad wilt instellen, 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. Tabspecifieke instellingen hebben voorrang op algemene instellingen.

Ingeschakelde status

Standaard zijn werkbalkacties op elk tabblad ingeschakeld (klikbaar). U kunt dit regelen met de methoden action.enable() en action.disable() . Dit heeft alleen invloed op de vraag of de pop-up (indien aanwezig) of action.onClicked -gebeurtenis naar uw extensie wordt verzonden; het heeft geen invloed op de aanwezigheid van de actie in de werkbalk.

Voorbeelden

In de volgende voorbeelden ziet u enkele veelvoorkomende manieren waarop acties in extensies worden gebruikt. Als u deze API wilt proberen, installeert u het Action API-voorbeeld uit de chrome-extension-samples -repository.

Laat een pop-up zien

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 wanneer u klikt

Een gebruikelijk patroon voor extensies is om hun primaire kenmerk bloot te leggen met behulp van de actie van de extensie. Het volgende voorbeeld demonstreert dit patroon. Wanneer de gebruiker op de actie klikt, injecteert de extensie een inhoudsscript in de huidige pagina. Het inhoudsscript geeft vervolgens een waarschuwing weer om te verifiëren dat alles werkte 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
chrome.action.onClicked.addListener((tab) => {
  chrome.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
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,
)