Questa pagina è stata tradotta dall'API Cloud Translation.

Iniettare script nella scheda attiva

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

Panoramica

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

In questa guida spiegheremo come:

Utilizza il worker del servizio dell'estensione come coordinatore dell'evento.
Mantieni la privacy degli utenti tramite l'autorizzazione "activeTab".
Esegui il codice quando l'utente fa clic sull'icona della barra degli strumenti dell'estensione.
Inserisci e rimuovi un foglio di stile utilizzando l'API Scripting.
Usa 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 di 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 seguente codice.

{
  "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 scoprire di più su queste chiavi manifest, consulta il tutorial "Eseguire script in ogni scheda", che spiega più in dettaglio i metadata e le icone dell'estensione.

Crea una cartella images, quindi 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 worker di servizio 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 codice seguente:

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à durante l'installazione. Le estensioni possono utilizzare l'API Storage e IndexedDB per memorizzare lo stato dell'applicazione. In questo caso, però, poiché gestiamo solo due stati, utilizzeremo il testo del badge dell'azione stesso per monitorare se l'estensione è "ON" o "OFF".

Passaggio 3: attiva l'azione dell'estensione

L'azione dell'estensione controlla l'icona della barra degli strumenti dell'estensione. Pertanto, ogni volta che l'utente fa clic sull'icona dell'estensione, viene eseguito del codice (come in questo esempio) o viene visualizzato un popup. Aggiungi il codice seguente 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"
    }
  },
  ...
}

Utilizzare l'autorizzazione activeTab per proteggere la privacy degli utenti

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 dell'estensione.

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

Premendo una combinazione di tasti di scorciatoia.
Seleziona un elemento del menu contestuale.
Accettare un suggerimento dall'omnibox.
Apertura di un popup dell'estensione.

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

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

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

Passaggio 4: monitora lo stato della scheda corrente

Dopo che l'utente ha fatto clic sull'azione dell'estensione, l'estensione controlla se l'URL corrisponde a una pagina di documentazione. Successivamente, 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

A questo punto è il momento di modificare il layout della pagina. Crea un file denominato focus-mode.css e includi il seguente codice:

* {
  display: none !important;
}

html,
body,
*:has(article),
article,
article * {
  display: revert !important;
}

[role='navigation'] {
  display: none !important;
}

article {
  margin: auto;
  max-width: 700px;
}

Inserisci o rimuovi il foglio di stile utilizzando l'API Scripting. Per iniziare, dichiara l'autorizzazione "scripting" nel file 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 iniettare codice anziché un foglio di stile?

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

(Facoltativo) Assegna una scorciatoia da tastiera

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

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

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

Verifica che funzioni

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

I contenuti della cartella della modalità di messa a fuoco: 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 in una pagina della documentazione

Innanzitutto, apri una delle seguenti pagine:

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

Dovrebbe passare da questo:

Estensione della modalità Niente distrazioni OFF — Estensione della modalità Niente distrazioni disattivata

In:

Estensione Modalità Niente distrazioni attiva — Estensione della modalità Niente distrazioni attivata

🎯 Potenziali miglioramenti

In base a quanto appreso oggi, prova a svolgere una delle seguenti attività:

Migliora il foglio di stile CSS.
Assegna una scorciatoia da tastiera diversa.
Modificare 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 gli altri tutorial di questa serie:

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

Continua a esplorare

Ci auguriamo che tu abbia apprezzato la creazione di questa estensione per Chrome e siamo entusiasti di continuare il tuo percorso di apprendimento per lo sviluppo di estensioni. Ti consigliamo i seguenti percorsi di apprendimento:

La guida per gli sviluppatori contiene dozzine di link aggiuntivi a parti della documentazione pertinenti alla creazione di estensioni avanzate.
Le estensioni hanno accesso a potenti API oltre a quelle disponibili sul web aperto. La documentazione delle API di Chrome illustra ogni API.