Progettare l'interfaccia utente

L'interfaccia utente dell'estensione deve essere mirata e minimalista. Come le estensioni stesse, l'interfaccia utente deve personalizzare o migliorare l'esperienza di navigazione senza distrarre l'utente.

Questa guida esplora le funzionalità dell'interfaccia utente obbligatorie e facoltative. Utilizzala per capire come e quando implementare diversi elementi dell'interfaccia utente all'interno di un'estensione.

Attivare l'estensione su tutte le pagine

Utilizza un'browser_action quando le funzionalità di un'estensione sono funzionali nella maggior parte delle situazioni.

Registrare l'azione del browser

Il campo "browser_action" è registrato nel manifest.

{
  "name": "My Awesome browser_action Extension",
  ...
  "browser_action": {
    ...
  }
  ...
}

La dichiarazione di "browser_action" mantiene l'icona colorata, indicando che l'estensione è disponibile per gli utenti.

Aggiungere un badge

I badge mostrano un banner colorato con un massimo di quattro caratteri sopra l'icona del browser. Possono essere utilizzati solo dalle estensioni che dichiarano "browser_action" nel manifest.

Utilizza i badge per indicare lo stato dell'estensione. L'esempio di evento Bevi acqua mostra una medaglia con "ON" per indicare all'utente che ha impostato correttamente una sveglia e non mostra nulla quando l'estensione è inattiva.

Imposta il testo del badge chiamando chrome.browserAction.setBadgeText e il colore del banner chiamando chrome.browserAction.setBadgeBackgroundColor .

chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});

Attivare l'estensione su pagine selezionate

Utilizza page_action quando le funzionalità di un'estensione sono disponibili solo in circostanze definite.

Dichiarare l'azione della pagina

Il campo "page_action" è registrato nel manifest.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    ...
  }
  ...
}

La dichiarazione di "page_action" colora l'icona solo quando l'estensione è disponibile per gli utenti, altrimenti viene visualizzata in scala di grigi.

Definire le regole per l'attivazione dell'estensione

Definisci le regole per quando l'estensione è utilizzabile chiamando chrome.declarativeContent nel runtime.onInstalled listener in uno script in background. L'estensione di esempio Azione della pagina per URL imposta una condizione in base alla quale l'URL deve includere una "g". Se la condizione è soddisfatta, l'estensione chiama declarativeContent.ShowPageAction().

chrome.runtime.onInstalled.addListener(function() {
  // Replace all rules ...
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    // With a new rule ...
    chrome.declarativeContent.onPageChanged.addRules([
      {
        // That fires when a page's URL contains a 'g' ...
        conditions: [
          new chrome.declarativeContent.PageStateMatcher({
            pageUrl: { urlContains: 'g' },
          })
        ],
        // And shows the extension's page action.
        actions: [ new chrome.declarativeContent.ShowPageAction() ]
      }
    ]);
  });
});

Attivare o disattivare l'estensione

Le estensioni che utilizzano "page_action" possono essere attivate e disattivate dinamicamente chiamando pageAction.show e pageAction.hide.

L'estensione di esempio Mappy esegue la scansione di una pagina web per trovare un indirizzo e ne mostra la posizione su una mappa statica nel popup. Poiché l'estensione dipende dai contenuti della pagina, non può dichiarare regole per prevedere quali pagine saranno pertinenti. Se viene trovato un indirizzo in una pagina, chiama pageAction.show per colorare l'icona e segnalare che l'estensione è utilizzabile in quella scheda.

chrome.runtime.onMessage.addListener(function(req, sender) {
  chrome.storage.local.set({'address': req.address})
  chrome.pageAction.show(sender.tab.id);
  chrome.pageAction.setTitle({tabId: sender.tab.id, title: req.address});
});

Fornire le icone dell'estensione

Le estensioni richiedono almeno un'icona per rappresentarle. Fornisci le icone in formato PNG per ottenere i migliori risultati visivi, anche se è accettato qualsiasi formato supportato da WebKit, inclusi BMP, GIF, ICO e JPEG.

Designare le icone della barra degli strumenti

Le icone specifiche della barra degli strumenti sono registrate nel campo "default_icon" in browser_action o page_action nel manifest. È consigliabile includere più dimensioni per scalare lo spazio di 16 dip. Sono consigliate almeno le dimensioni 16x16 e 32x32.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    "default_icon": {
      "16": "extension_toolbar_icon16.png",
      "32": "extension_toolbar_icon32.png"
    }
  }
  ...
}

Tutte le icone devono essere quadrate, altrimenti potrebbero essere distorte. Se non vengono fornite icone, Chrome ne aggiungerà una generica alla barra degli strumenti.

Creare e registrare icone aggiuntive

Includi icone aggiuntive nelle seguenti dimensioni per usi esterni alla barra degli strumenti.

Registra le icone nel manifest nel campo "icons".

{
  "name": "My Awesome Extension",
  ...
  "icons": {
    "16": "extension_icon16.png",
    "32": "extension_icon32.png",
    "48": "extension_icon48.png",
    "128": "extension_icon128.png"
  }
  ...
}

Funzionalità aggiuntive dell'interfaccia utente

Popup

Un popup è un file HTML visualizzato in una finestra speciale quando l'utente fa clic sull'icona della barra degli strumenti. Un popup funziona in modo molto simile a una pagina web: può contenere link a fogli di stile e tag script, ma non consente JavaScript in linea.

Il popup di esempio dell'evento Bevi acqua mostra le opzioni del timer disponibili. Gli utenti impostano una sveglia facendo clic su uno dei pulsanti forniti.

<html>
  <head>
    <title>Water Popup</title>
  </head>
  <body>
      <img src='./stay_hydrated.png' id='hydrateImage'>
      <button id='sampleSecond' value='0.1'>Sample Second</button>
      <button id='15min' value='15'>15 Minutes</button>
      <button id='30min' value='30'>30 Minutes</button>
      <button id='cancelAlarm'>Cancel Alarm</button>
    <script src="popup.js"></script>
  </body>
</html>

Il popup può essere registrato nel manifest, in Azione del browser o Azione della pagina.

{
  "name": "Drink Water Event",
  ...
  "browser_action": {
    "default_popup": "popup.html"
  }
  ...
}

I popup possono anche essere impostati dinamicamente chiamando browserAction.setPopup o pageAction.setPopup.

chrome.storage.local.get('signed_in', function(data) {
  if (data.signed_in) {
    chrome.browserAction.setPopup({popup: 'popup.html'});
  } else {
    chrome.browserAction.setPopup({popup: 'popup_sign_in.html'});
  }
});

Descrizione comando

Utilizza una descrizione comando per fornire brevi descrizioni o istruzioni agli utenti quando passano il mouse sopra l'icona del browser.

Le descrizioni comando sono registrate nel campo "default_title" browser_action o page_action nel manifest.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
  }
...
}

Le descrizioni comando possono anche essere impostate o aggiornate chiamando browserAction.setTitle e pageAction.setTitle.

chrome.browserAction.onClicked.addListener(function(tab) {
  chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});

Le stringhe di localizzazione specializzate vengono implementate con l'internazionalizzazione. Crea directory per ospitare i messaggi specifici della lingua all'interno di una cartella denominata _locales, come indicato di seguito:

• _locales/en/messages.json
• _locales/es/messages.json

Formatta i messaggi all'interno di messages.json di ogni lingua.

{
  "__MSG_tooltip__": {
      "message": "Hello!",
      "description": "Tooltip Greeting."
  }
}

{
  "__MSG_tooltip__": {
      "message": "Hola!",
      "description": "Tooltip Greeting."
  }
}

Includi il nome del messaggio nel campo della descrizione comando anziché il messaggio per attivare la localizzazione.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "__MSG_tooltip__"
  }
...
}

Omnibox

Gli utenti possono richiamare la funzionalità dell'estensione tramite l'Omnibox. Includi il campo "omnibox" in nel manifest e designa una parola chiave. L'estensione di esempio Ricerca nella nuova scheda di Omnibox utilizza "nt" come parola chiave.

{
  "name": "Omnibox New Tab Search",\
  ...
  "omnibox": { "keyword" : "nt" },
  "default_icon": {
    "16": "newtab_search16.png",
    "32": "newtab_search32.png"
  }
  ...
}

Quando l'utente digita "nt" in Omnibox, l'estensione viene attivata. Per segnalarlo all'utente, l'icona 16x16 fornita viene visualizzata in scala di grigi e inclusa in Omnibox accanto al nome dell'estensione.

L'estensione ascolta l'evento omnibox.onInputEntered. Una volta attivata, l'estensione apre una nuova scheda contenente una ricerca Google per la voce dell'utente.

chrome.omnibox.onInputEntered.addListener(function(text) {
  // Encode user input for special characters , / ? : @ & = + $ #
  var newURL = 'https://www.google.com/search?q=' + encodeURIComponent(text);
  chrome.tabs.create({ url: newURL });
});

Menu contestuale

Aggiungi nuove opzioni del menu contestuale concedendo l'autorizzazione "contextMenus" nel manifest.

{
  "name": "Global Google Search",
  ...
  "permissions": [
    "contextMenus",
    "storage"
  ],
  "icons": {
    "16": "globalGoogle16.png",
    "48": "globalGoogle48.png",
    "128": "globalGoogle128.png"
  }
  ...
}

L'icona 16x16 viene visualizzata accanto alla nuova voce di menu.

Crea un menu contestuale chiamando contextMenus.create nello script in background. Questa operazione deve essere eseguita nell'evento runtime.onInstalled listener.

chrome.runtime.onInstalled.addListener(function() {
  for (let key of Object.keys(kLocales)) {
    chrome.contextMenus.create({
      id: key,
      title: kLocales[key],
      type: 'normal',
      contexts: ['selection'],
    });
  }
});

const kLocales = {
  'com.au': 'Australia',
  'com.br': 'Brazil',
  'ca': 'Canada',
  'cn': 'China',
  'fr': 'France',
  'it': 'Italy',
  'co.in': 'India',
  'co.jp': 'Japan',
  'com.ms': 'Mexico',
  'ru': 'Russia',
  'co.za': 'South Africa',
  'co.uk': 'United Kingdom'
};

L'esempio di menu contestuale Ricerca globale di Google crea più opzioni dall'elenco in locales.js . Quando un'estensione contiene più di un menu contestuale, Google Chrome li comprime automaticamente in un unico menu principale.

Comandi

Le estensioni possono definire comandi specifici e associarli a una combinazione di tasti. Registra uno o più comandi nel manifest nel campo "commands".

{
  "name": "Tab Flipper",
  ...
  "commands": {
    "flip-tabs-forward": {
      "suggested_key": {
        "default": "Ctrl+Shift+Right",
        "mac": "Command+Shift+Right"
      },
      "description": "Flip tabs forward"
    },
    "flip-tabs-backwards": {
      "suggested_key": {
        "default": "Ctrl+Shift+Left",
        "mac": "Command+Shift+Left"
      },
      "description": "Flip tabs backwards"
    }
  }
  ...
}

I comandi possono essere utilizzati per fornire scorciatoie del browser nuove o alternative. L'estensione di esempio Tab Flipper ascolta l'evento commands.onCommand nello script in background e definisce la funzionalità per ogni combinazione registrata.

chrome.commands.onCommand.addListener(function(command) {
  chrome.tabs.query({currentWindow: true}, function(tabs) {
    // Sort tabs according to their index in the window.
    tabs.sort((a, b) => { return a.index < b.index; });
    let activeIndex = tabs.findIndex((tab) => { return tab.active; });
    let lastTab = tabs.length - 1;
    let newIndex = -1;
    if (command === 'flip-tabs-forward')
      newIndex = activeIndex === 0 ? lastTab : activeIndex - 1;
    else  // 'flip-tabs-backwards'
      newIndex = activeIndex === lastTab ? 0 : activeIndex + 1;
    chrome.tabs.update(tabs[newIndex].id, {active: true, highlighted: true});
  });
});

I comandi possono anche creare un'associazione di tasti che funziona in modo speciale con la relativa estensione. L'esempio di estensione Hello Extensions fornisce un comando per aprire il popup.

{
  "name": "Hello Extensions",
  "description" : "Base Level Extension",
  "version": "1.0",
  "browser_action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  },
  "manifest_version": 2,
  "commands": {
    "_execute_browser_action": {
      "suggested_key": {
        "default": "Ctrl+Shift+F",
        "mac": "MacCtrl+Shift+F"
      },
      "description": "Opens hello.html"
    }
  }
}

Poiché l'estensione definisce un browser_action, può specificare "execute_browser_action" in the commands to open the popup file without including a background script. Se utilizzi page_action, puoi sostituirlo con "execute_page_action". Nella stessa estensione possono essere utilizzati sia i comandi del browser sia quelli dell'estensione.

Ignorare le pagine

Un'estensione può ignorare e sostituire la pagina web Cronologia, Nuova scheda o Segnalibri con un file HTML personalizzato. Come un popup, può includere logica e stile specializzati, ma non consente JavaScript in linea. Una singola estensione può ignorare solo una delle tre pagine possibili.

Registra una pagina di override nel manifest nel campo "chrome_url_overrides".

{
  "name": "Awesome Override Extension",
  ...

  "chrome_url_overrides" : {
    "newtab": "override_page.html"
  },
  ...
}

Quando ignori queste pagine, il campo "newtab" deve essere sostituito con "bookmarks" o "history".

<html>
  <head>
  <title>New Tab</title>
  </head>
  <body>
    <h1>Hello World</h1>
  <script src="logic.js"></script>
  </body>
</html>