Executar scripts em todas as páginas

Crie sua primeira extensão que insira um novo elemento na página.

Visão geral

Este tutorial cria uma extensão que adiciona o tempo de leitura esperado a qualquer extensão do Chrome e Página de documentação da Chrome Web Store.

Extensão de tempo de leitura na página de boas-vindas da extensão
Lendo a extensão de tempo na página de boas-vindas da extensão.

Neste guia, explicaremos os seguintes conceitos:

  • O manifesto da extensão.
  • Os tamanhos de ícone usados por uma extensão.
  • Como injetar código em páginas usando scripts de conteúdo.
  • Como usar padrões de correspondência.
  • Permissões da extensão.

Antes de começar

Este guia pressupõe que você tenha experiência básica em desenvolvimento na Web. Recomendamos consultar Tutorial Hello world para uma introdução ao fluxo de trabalho de desenvolvimento de extensões.

Criar a extensão

Para começar, crie um novo diretório chamado reading-time para armazenar os arquivos da extensão. Se você Se preferir, faça o download do código-fonte completo no GitHub.

Etapa 1: adicionar informações sobre a extensão

O arquivo JSON de manifesto é o único arquivo obrigatório. Ele contém informações importantes sobre a . Crie um arquivo manifest.json na raiz do projeto e adicione o seguinte código:

{
  "manifest_version": 3,
  "name": "Reading time",
  "version": "1.0",
  "description": "Add the reading time to Chrome Extension documentation articles"
}

Essas chaves contêm metadados básicos para a extensão. Eles controlam como a extensão aparece na página de extensões e, quando publicada, na Chrome Web Store. Para saber mais, confira o Chaves "name", "version" e "description" no Página de visão geral do manifesto.

💡 Outros fatos sobre o manifesto de extensões

  • Ele precisa estar localizado na raiz do projeto.
  • As únicas chaves obrigatórias são "manifest_version", "name" e "version".
  • Ela suporta comentários (//) durante o desenvolvimento, mas devem ser removidos antes de fazer o upload do seu código para a Chrome Web Store.

Etapa 2: fornecer os ícones

Então, por que você precisa de ícones? Embora os ícones sejam opcionais durante o desenvolvimento, eles obrigatório se você planeja distribuir sua extensão na Chrome Web Store. Eles também aparecem em outros em outros lugares, como a página de gerenciamento de extensões.

Crie uma pasta images e coloque os ícones dentro dela. Você pode fazer o download dos ícones GitHub. Em seguida, adicione o código destacado ao manifesto para declarar os ícones:

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

Recomendamos o uso de arquivos PNG, mas outros formatos são permitidos, exceto arquivos SVG.

💡 Onde esses ícones de tamanhos diferentes são exibidos?

Tamanho do ícone Uso de ícones
16x16 Favicon nas páginas e no menu de contexto da extensão.
32x32 Computadores Windows geralmente exigem esse tamanho.
48x48 Aparece na página "Extensões".
128x128 Aparece na instalação e na Chrome Web Store.

Etapa 3: declarar o script de conteúdo

As extensões podem executar scripts que leem e modificam o conteúdo de uma página. Eles são chamados de conteúdo scripts. Eles vivem em um mundo isolado, o que significa que podem fazer alterações no ambiente JavaScript sem entrar em conflito com a página do host ou com outras extensões scripts de conteúdo.

Adicione o seguinte código ao manifest.json para registrar um script de conteúdo chamado content.js.

{
  "content_scripts": [
    {
      "js": ["scripts/content.js"],
      "matches": [
        "https://developer.chrome.com/docs/extensions/*",
        "https://developer.chrome.com/docs/webstore/*"
      ]
    }
  ]
}

O campo "matches" pode ter um ou mais padrões de correspondência. Isso permite que o navegador identificar em quais sites injetar os scripts de conteúdo. Os padrões de correspondência são compostos por três partes: <scheme>://<host><path>: Eles podem conter "*" caracteres.

💡 Essa extensão exibe um aviso de permissão?

Quando um usuário instala uma extensão, o navegador informa o que a extensão pode fazer. Os scripts de conteúdo solicitam permissão para serem executados em sites que atendem aos critérios do padrão de correspondência.

Neste exemplo, o usuário veria o seguinte aviso de permissão:

Aviso de permissão que vai aparecer para o usuário ao instalar a extensão de tempo de leitura
Aviso de permissão de tempo de leitura.

Para saber mais sobre as permissões de extensões, consulte Como declarar permissões e avisar os usuários.

Etapa 4: calcular e inserir o tempo de leitura

Os scripts de conteúdo podem usar o Modelo de objeto de documentos (DOM) padrão para ler e alterar o o conteúdo de uma página. A extensão verificará primeiro se a página contém o elemento <article>. Em seguida, ele conta todas as palavras desse elemento e cria um parágrafo que exibe o total o tempo de leitura.

Crie um arquivo com o nome content.js dentro de uma pasta chamada scripts e adicione o seguinte código:

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 usado neste código

  • Normal expressões usadas para contar apenas as palavras dentro do elemento <article>.
  • insertAdjacentElement() é usado para inserir o nó de tempo de leitura após o elemento.
  • A propriedade classList usada para adicionar nomes de classe CSS ao atributo de classe de elemento.
  • Encadeamento opcional usado para acessar uma propriedade de objeto que pode ser indefinida ou nula.
  • A coalescência nula vai retornar <heading> se a <date> for nula ou indefinida.

Testar se funciona

Verifique se a estrutura de arquivos do seu projeto é semelhante a esta:

O conteúdo da pasta de tempo de leitura: manifest.json, content.js na pasta de scripts e pasta de imagens.

Carregar sua extensão localmente

Para carregar uma extensão descompactada no modo de desenvolvedor, siga as etapas em Desenvolvimento Noções básicas.

Abrir uma extensão ou a documentação da Chrome Web Store

Aqui estão algumas páginas que você pode abrir para ver quanto tempo levará para ler cada artigo.

Ele será parecido com o seguinte:

Tempo de execução da página de boas-vindas
Página de recepção da extensão com a extensão de tempo de leitura

🎯 Possíveis melhorias

Com base no que você aprendeu hoje, tente implementar uma das seguintes opções:

  • Adicione outro padrão de correspondência ao manifest.json para oferecer suporte a outros desenvolvedores do Chrome. páginas, como o Chrome DevTools ou o Workbox.
  • Adicione um novo script de conteúdo que calcule o tempo de leitura de qualquer um de seus blogs favoritos ou sites de documentação.
.

Continue criando

Parabéns por concluir este tutorial 🎉. Continue desenvolvendo suas habilidades realizando outros tutoriais desta série:

Extensão O que você vai aprender
Modo sem distrações Para executar o código na página atual depois de clicar na ação da extensão.
Gerenciador de guias Criar um pop-up que gerencie guias do navegador.

Continue descobrindo

Esperamos que você tenha gostado de criar esta extensão do Google Chrome e estamos animados para continuar usando o Chrome e desenvolvimento de software. Recomendamos o seguinte programa de aprendizado: