Crea la tua prima estensione che inserisce un nuovo elemento nella pagina.
Panoramica
Questo tutorial crea un'estensione che aggiunge il tempo di lettura previsto a qualsiasi estensione di Chrome e alla pagina della documentazione del Chrome Web Store.
In questa guida illustreremo i seguenti concetti:
- Il file manifest dell'estensione.
- Le dimensioni delle icone utilizzate da un'estensione.
- Come inserire il codice nelle pagine utilizzando script di contenuti.
- Come utilizzare i pattern di corrispondenza.
- Autorizzazioni delle estensioni.
Prima di iniziare
Questa guida presuppone che tu abbia esperienza di base nello sviluppo web. Ti consigliamo di seguire il tutorial Hello World per un'introduzione al flusso di lavoro per lo sviluppo delle estensioni.
Crea l'estensione
Per iniziare, crea una nuova directory denominata reading-time in cui inserire i file dell'estensione. Se preferisci, puoi scaricare il codice sorgente completo da GitHub.
Passaggio 1: aggiungi informazioni sull'estensione
Il file manifest JSON è l'unico file richiesto. Contiene informazioni importanti
sull'estensione. Crea un file manifest.json nella directory principale del progetto e aggiungi il codice seguente:
{
"manifest_version": 3,
"name": "Reading time",
"version": "1.0",
"description": "Add the reading time to Chrome Extension documentation articles"
}
Queste chiavi contengono metadati di base per l'estensione. Controllano il modo in cui l'estensione viene visualizzata nella pagina delle estensioni e, una volta pubblicata, nel Chrome Web Store. Per saperne di più, consulta le chiavi "name", "version" e "description" nella pagina della panoramica del file manifest.
💡 Altre informazioni sul file manifest dell'estensione
- Deve trovarsi nella principale del progetto.
- Le uniche chiavi obbligatorie sono
"manifest_version","name"e"version". - Supporta i commenti (
//) durante lo sviluppo, ma è necessario rimuoverli prima di caricare il codice sul Chrome Web Store.
Passaggio 2: fornisci le icone
Perché sono necessarie le icone? Anche se le icone sono facoltative durante lo sviluppo, sono obbligatorie se prevedi di distribuire l'estensione sul Chrome Web Store. Inoltre, vengono visualizzate in altre posizioni, come la pagina Gestione delle estensioni.
Crea una cartella images e posiziona le icone al suo interno. Puoi scaricare le icone su GitHub. Quindi, aggiungi il codice evidenziato al file manifest per dichiarare le icone:
{
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}
Consigliamo di utilizzare i file PNG, ma sono consentiti altri formati di file, ad eccezione dei file SVG.
💡 Dove vengono visualizzate queste icone di dimensioni diverse?
| Dimensioni icona | Utilizzo delle icone |
|---|---|
| 16x16 | Favicon nelle pagine e nel menu contestuale dell'estensione. |
| 32x32 | I computer Windows spesso richiedono queste dimensioni. |
| 48x48 | Vengono visualizzate nella pagina Estensioni. |
| 128x128 | Vengono visualizzati al momento dell'installazione e nel Chrome Web Store. |
Passaggio 3: dichiara lo script dei contenuti
Le estensioni possono eseguire script che leggono e modificano i contenuti di una pagina. Questi sono chiamati script di contenuti. Vivono in un mondo isolato, vale a dire che possono apportare modifiche al proprio ambiente JavaScript senza entrare in conflitto con gli script dei contenuti della pagina host o di altre estensioni.
Aggiungi il codice seguente a manifest.json per registrare uno script di contenuti chiamato
content.js.
{
"content_scripts": [
{
"js": ["scripts/content.js"],
"matches": [
"https://developer.chrome.com/docs/extensions/*",
"https://developer.chrome.com/docs/webstore/*"
]
}
]
}
Il campo "matches" può avere uno o più pattern di corrispondenza. che consentono al browser di identificare i siti in cui inserire gli script di contenuti. I pattern di corrispondenza sono costituiti da tre parti:
<scheme>://<host><path>. Possono contenere i caratteri "*".
💡 Questa estensione mostra un avviso di autorizzazione?
Quando un utente installa un'estensione, il browser gli comunica cosa può fare l'estensione. Gli script di contenuti richiedono l'autorizzazione per l'esecuzione su siti che soddisfano i criteri del pattern di corrispondenza.
In questo esempio, l'utente visualizza il seguente avviso di autorizzazione:
Per saperne di più sulle autorizzazioni per le estensioni, vedi Dichiarare le autorizzazioni e avvisare gli utenti.
Passaggio 4: calcola e inserisci il tempo di lettura
Gli script di contenuti possono utilizzare il Document Object Model (DOM) standard per leggere e modificare i contenuti di una pagina. L'estensione controlla innanzitutto se la pagina contiene l'elemento <article>.
Quindi, conterà tutte le parole all'interno dell'elemento e creerà un paragrafo che mostra il tempo totale di lettura.
Crea un file denominato content.js all'interno di una cartella denominata scripts e aggiungi il seguente codice:
const article = document.querySelector("article");
// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
const text = article.textContent;
const wordMatchRegExp = /[^\s]+/g; // Regular expression
const words = text.matchAll(wordMatchRegExp);
// matchAll returns an iterator, convert to array to get word count
const wordCount = [...words].length;
const readingTime = Math.round(wordCount / 200);
const badge = document.createElement("p");
// Use the same styling as the publish information in an article's header
badge.classList.add("color-secondary-text", "type--caption");
badge.textContent = `⏱️ ${readingTime} min read`;
// Support for API reference docs
const heading = article.querySelector("h1");
// Support for article docs with date
const date = article.querySelector("time")?.parentNode;
(date ?? heading).insertAdjacentElement("afterend", badge);
}
💡 JavaScript interessante utilizzato in questo codice
- Espressioni
regolari utilizzate per conteggiare solo le parole all'interno dell'elemento
<article>. insertAdjacentElement()utilizzato per inserire il nodo del tempo di lettura dopo l'elemento.- La proprietà classList utilizzata per aggiungere nomi delle classi CSS all'attributo classe dell'elemento.
- Concatenazione facoltativa utilizzata per accedere a una proprietà dell'oggetto che può essere non definita o nulla.
- La coalescenza di null restituisce
<heading>se<date>è nullo o non definito.
Verifica che funzioni
Verifica che la struttura dei file del progetto sia la seguente:
Carica l'estensione localmente
Per caricare un'estensione non pacchettizzata in modalità sviluppatore, segui i passaggi descritti in Nozioni di base sullo sviluppo.
Apri un'estensione o la documentazione del Chrome Web Store
Di seguito sono riportate alcune pagine che puoi aprire per verificare quanto tempo occorrerà per leggere ciascun articolo.
Dovrebbe avere il seguente aspetto:
🎯 Potenziali miglioramenti
Sulla base di quanto hai appreso oggi, prova a implementare una delle seguenti soluzioni:
- Aggiungi un altro pattern di corrispondenza nel file manifest.json per supportare altre pagine per gli sviluppatori di Chrome, ad esempio Chrome DevTools o Workbox.
- Aggiungi un nuovo script di contenuti che calcoli il tempo di lettura per uno dei tuoi blog o siti di documentazione preferiti.
Continua a creare
Congratulazioni per aver completato questo tutorial 🎉. Continua a sviluppare le tue competenze completando altri tutorial di questa serie:
| Estensione | Cosa imparerai a fare |
|---|---|
| Modalità Niente distrazioni | Per eseguire il codice nella pagina corrente dopo aver fatto clic sull'azione dell'estensione. |
| 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 felici di continuare il tuo percorso di apprendimento sullo sviluppo di Chrome. Ti consigliamo il seguente percorso di apprendimento:
- La guida per gli sviluppatori contiene decine di link aggiuntivi a documenti pertinenti alla creazione di estensioni avanzate.
- Le estensioni hanno accesso ad API potenti oltre a quelle disponibili sul web aperto. La documentazione sulle API di Chrome illustra ogni singola API.