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.

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?

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:

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:

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.

• Publicar na Chrome Web Store
• Noções básicas sobre scripts de conteúdo

Ele será parecido com o seguinte:

🎯 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:

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:

• O Guia para desenvolvedores tem dezenas de links adicionais para documentações relevantes para a criação avançada de extensões.
• As extensões têm acesso a APIs poderosas além daquelas disponíveis na Web aberta. A documentação das APIs do Chrome explica cada API.