Inserisci script nella scheda attiva

Semplifica lo stile della pagina corrente facendo clic sull'icona dell'estensione nella barra degli strumenti.

Panoramica

Questo tutorial crea un'estensione che semplifica lo stile dell'estensione di Chrome e delle pagine della documentazione del Chrome Web Store in modo che siano più facili da leggere.

In questa guida, ti spiegheremo come:

  • Utilizza il service worker dell'estensione come coordinatore dell'evento.
  • Tutelare la privacy degli utenti tramite l'autorizzazione "activeTab".
  • Esegui il codice quando l'utente fa clic sull'icona della barra degli strumenti delle estensioni.
  • Inserisci e rimuovi un foglio di stile utilizzando l'API Scripting.
  • Utilizza una scorciatoia da tastiera per eseguire il codice.

Prima di iniziare

Questa guida presuppone che tu abbia esperienza di base nello sviluppo web. Ti consigliamo di consultare Hello World per un'introduzione al flusso di lavoro per lo sviluppo delle estensioni.

Crea l'estensione

Per iniziare, crea una nuova directory, denominata focus-mode, che conterrà i file dell'estensione. Se preferisci, puoi scaricare il codice sorgente completo da GitHub.

Passaggio 1: aggiungi i dati e le icone dell'estensione

Crea un file denominato manifest.json e includi il codice seguente.

{
  "manifest_version": 3,
  "name": "Focus Mode",
  "description": "Enable focus mode on Chrome's official Extensions and Chrome Web Store documentation.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

Per ulteriori informazioni su queste chiavi manifest, consulta il tutorial "Esegui script in ogni scheda" che spiega in maggiore dettaglio i metadati e le icone dell'estensione.

Crea una cartella images e scarica le icone al suo interno.

Passaggio 2: inizializza l'estensione

Le estensioni possono monitorare gli eventi del browser in background utilizzando il worker di servizio dell'estensione. I service worker sono ambienti JavaScript speciali che gestiscono gli eventi e terminano quando non sono necessari.

Per iniziare, registra il service worker nel file manifest.json:

{
  ...
  "background": {
    "service_worker": "background.js"
  },
  ...
}

Crea un file denominato background.js e aggiungi il seguente codice:

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setBadgeText({
    text: "OFF",
  });
});

Il primo evento che il nostro service worker ascolterà è runtime.onInstalled(). Questo metodo consente all'estensione di impostare uno stato iniziale o di completare alcune attività al momento dell'installazione. Le estensioni possono utilizzare l'API Storage e IndexedDB per archiviare lo stato dell'applicazione. In questo caso, tuttavia, poiché gestiamo solo due stati, utilizzeremo il testo del badge dell'azione stesso per controllare se l'estensione è attiva o non attiva.

Passaggio 3: attiva l'azione dell'estensione

L'azione dell'estensione controlla l'icona dell'estensione nella barra degli strumenti. Ogni volta che l'utente fa clic sull'icona dell'estensione, esegue un codice (come in questo esempio) o visualizza un popup. Aggiungi il seguente codice per dichiarare l'azione dell'estensione nel file manifest.json:

{
  ...
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  ...
}

Usa l'autorizzazione activeTab per proteggere la privacy dell'utente

L'autorizzazione activeTab concede all'estensione la possibilità temporanea di eseguire codice nella scheda attiva. Consente inoltre di accedere alle proprietà sensibili della scheda corrente.

Questa autorizzazione viene attivata quando l'utente richiama l'estensione. In questo caso, l'utente richiama l'estensione facendo clic sull'azione.

💡 Quali altre interazioni degli utenti attivano l'autorizzazione activeTab nella mia estensione?

  • Premere una combinazione di scorciatoie da tastiera.
  • Selezione di una voce del menu contestuale.
  • È in corso l'accettazione di un suggerimento dalla omnibox.
  • Apertura popup di un'estensione.

L'autorizzazione "activeTab" consente agli utenti di scegliere volutamente di eseguire l'estensione nella scheda attiva; in questo modo, protegge la privacy dell'utente. Un altro vantaggio è che non viene attivato un avviso di autorizzazione.

Per utilizzare l'autorizzazione "activeTab", aggiungila all'array di autorizzazioni del manifest:

{
  ...
  "permissions": ["activeTab"],
  ...
}

Passaggio 4: monitora lo stato della scheda corrente

Dopo che l'utente ha fatto clic sull'azione, l'estensione controllerà se l'URL corrisponde a una pagina della documentazione. In seguito, controllerà lo stato della scheda corrente e imposterà lo stato successivo. Aggiungi il seguente codice a background.js:

const extensions = 'https://developer.chrome.com/docs/extensions'
const webstore = 'https://developer.chrome.com/docs/webstore'

chrome.action.onClicked.addListener(async (tab) => {
  if (tab.url.startsWith(extensions) || tab.url.startsWith(webstore)) {
    // Retrieve the action badge to check if the extension is 'ON' or 'OFF'
    const prevState = await chrome.action.getBadgeText({ tabId: tab.id });
    // Next state will always be the opposite
    const nextState = prevState === 'ON' ? 'OFF' : 'ON'

    // Set the action badge to the next state
    await chrome.action.setBadgeText({
      tabId: tab.id,
      text: nextState,
    });
  }
});

Passaggio 5: aggiungi o rimuovi il foglio di stile

È arrivato il momento di modificare il layout della pagina. Crea un file denominato focus-mode.css e includi il seguente codice:

body > .scaffold > :is(top-nav, navigation-rail, side-nav, footer),
main > :not(:last-child),
main > :last-child > navigation-tree,
main .toc-container {
  display: none;
}

main > :last-child {
  margin-top: min(10vmax, 10rem);
  margin-bottom: min(10vmax, 10rem);
}

Inserisci o rimuovi il foglio di stile utilizzando l'API Scripting. Inizia dichiarando l'autorizzazione "scripting" nel manifest:

{
  ...
  "permissions": ["activeTab", "scripting"],
  ...
}

Infine, in background.js aggiungi il seguente codice per modificare il layout della pagina:

  ...
    if (nextState === "ON") {
      // Insert the CSS file when the user turns the extension on
      await chrome.scripting.insertCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    } else if (nextState === "OFF") {
      // Remove the CSS file when the user turns the extension off
      await chrome.scripting.removeCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    }
  }
});

💡 Posso utilizzare l'API Scripting per inserire codice anziché un foglio di stile?

Sì. Puoi utilizzare scripting.executeScript() per inserire JavaScript.

(Facoltativo) Assegna una scorciatoia da tastiera

Per divertire, aggiungi una scorciatoia per attivare o disattivare più facilmente la modalità Niente distrazioni. Aggiungi la chiave "commands" al file manifest.

{
  ...
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  }
}

La chiave "_execute_action" esegue lo stesso codice dell'evento action.onClicked(), quindi non è necessario alcun codice aggiuntivo.

Verifica che funzioni

Verifica che la struttura dei file del progetto sia la seguente:

I contenuti della cartella della modalità focus: manifest.json, background.js, focus-mode.css e la cartella delle immagini.

Carica l'estensione localmente

Per caricare un'estensione non pacchettizzata in modalità sviluppatore, segui i passaggi descritti in Hello World.

Testare l'estensione su una pagina della documentazione

Per prima cosa, apri una delle seguenti pagine:

Poi, fai clic sull'azione dell'estensione. Se hai impostato una scorciatoia da tastiera, puoi testarla premendo Ctrl + B o Cmd + B.

Dovrebbe essere così:

Estensione per la modalità Niente distrazioni disattivata
Estensione Modalità Niente distrazioni

In:

Estensione Modalità Niente distrazioni ATTIVA
Estensione Modalità Niente distrazioni attivata

🎯 Potenziali miglioramenti

Sulla base di quanto hai appreso oggi, prova a eseguire una delle seguenti operazioni:

  • Migliora il foglio di stile CSS.
  • Assegna una scorciatoia da tastiera diversa.
  • Modifica il layout del tuo blog o sito di documentazione preferito.

e continua a costruire.

Congratulazioni per aver completato questo tutorial 🎉. Continua a migliorare le tue competenze completando altri tutorial di questa serie:

Estensione Cosa imparerai a fare
Tempo di lettura Per inserire automaticamente un elemento in un insieme specifico di pagine.
Gestione schede Per creare un popup che gestisca le schede del browser.

Continua a esplorare

Ci auguriamo che ti sia piaciuto creare questa estensione di Chrome e siamo entusiasti di continuare il tuo percorso di apprendimento per lo sviluppo delle estensioni. Ti consigliamo i seguenti percorsi di apprendimento: