Extensão Hello World

Aprenda os conceitos básicos do desenvolvimento de extensões do Chrome criando sua primeira extensão Hello World.

Visão geral

Você vai criar um app "Hello World" exemplo, carregar a extensão localmente, localizar registros e explorar outras recomendações.

Hello World

Esta extensão vai mostrar “Hello Extensions” quando o usuário clicar no ícone da barra de ferramentas da extensão.

Extensão Hello
Pop-up da extensão Hello

Comece criando um novo diretório para armazenar seus arquivos de extensão. Se preferir, você pode fazer o download código-fonte do GitHub.

Em seguida, crie um novo arquivo nesse diretório com o nome manifest.json. Esse arquivo JSON descreve os recursos e configuração dos recursos. Por exemplo, a maioria dos arquivos de manifesto contém uma chave "action" que declara a imagem que o Chrome deve usar como o ícone de ação da extensão e a página HTML para mostrar em um pop-up quando a é clicado no ícone de ação da extensão.

{
  "manifest_version": 3,
  "name": "Hello Extensions",
  "description": "Base Level Extension",
  "version": "1.0",
  "action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  }
}

Faça o download do ícone no diretório e mude o nome para corresponder ao que está na chave "default_icon".

Para o pop-up, crie um arquivo chamado hello.html e adicione o seguinte código:

<html>
  <body>
    <h1>Hello Extensions</h1>
  </body>
</html>

A extensão agora exibe um pop-up quando o ícone de ação da extensão (ícone da barra de ferramentas) é clicado. É possível testar no Chrome, carregando-a localmente. Verifique se todos os arquivos foram salvos.

Carregar uma extensão descompactada

Para carregar uma extensão descompactada no modo de desenvolvedor:

  1. Acesse a página "Extensões" digitando chrome://extensions em uma nova guia. Por padrão, os URLs do chrome:// não podem ser vinculados.
    • Você também pode clicar no botão de quebra-cabeça do menu "Extensões" e selecionar Gerenciar extensões na parte inferior do menu.
    • Você também pode clicar no menu do Google Chrome, passar o cursor sobre Mais ferramentas e selecionar Extensões.
  2. Ative o modo de desenvolvedor clicando no botão ao lado de Modo de desenvolvedor.
  3. Clique no botão Carregar sem compactação e selecione o diretório de extensão.
    Página &quot;Extensões&quot;
    Página "Extensões" (chrome://extensions)

Pronto! A extensão foi instalada. Se nenhum ícone de extensão tiver sido incluído manifesto, um ícone genérico será criado para a extensão.

Fixar a extensão

Por padrão, quando você carregar sua extensão localmente, ela aparecerá no menu de extensões (Quebra-cabeça). Fixe sua extensão na barra de ferramentas para acessá-la rapidamente durante o desenvolvimento.

Fixar a extensão
Fixar a extensão

Clique no ícone de ação da extensão (ícone da barra de ferramentas). vai aparecer um pop-up.

extensão Hello World
Extensão Hello World

Atualizar a extensão

Volte para o código e mude o nome da extensão para "Hello Extensions of the world!". no manifesto.

{
  "manifest_version": 3,
  "name": "Hello Extensions of the world!",
  ...
}

Depois de salvar o arquivo, para ver essa alteração no navegador, você também precisa atualizar a extensão. Ir para a página "Extensões" e clique no ícone de atualização ao lado do botão de ativação/desativação on/off:

Atualizar uma extensão

Quando recarregar a extensão

A tabela a seguir mostra quais componentes precisam ser recarregados para ver as alterações:

Componente da extensão Requer a atualização da extensão
O manifesto Sim
Service Worker Sim
Scripts de conteúdo Sim (além da página de hospedagem)
O pop-up Não
Página de opções Não
Outras páginas HTML de extensão Não

Encontrar erros e registros do console

Registros do console

Durante o desenvolvimento, você pode depurar seu código acessando os registros do console do navegador. Nesse caso, vai localizar os registros do pop-up. Comece adicionando uma tag de script a hello.html.

<html>
  <body>
    <h1>Hello Extensions</h1>
    <script src="popup.js"></script>
  </body>
</html>

Crie um arquivo popup.js e adicione o seguinte código:

console.log("This is a popup!")

Para ver essa mensagem registrada no console:

  1. Abra a janela pop-up.
  2. Clique com o botão direito do mouse no pop-up.
  3. Selecione Inspecionar.
    Inspecionando o pop-up.
    Inspecionando um pop-up.
  4. No DevTools, acesse o painel Console.
    Painel de código do DevTools
    Como inspecionar um pop-up

Registros de erro

Agora vamos quebrar a extensão. Podemos fazer isso removendo as aspas de fechamento em popup.js:

console.log("This is a popup!) // ❌ broken code

Acesse a página "Extensões" e abra o pop-up. Um botão Erros será exibido.

Página de extensões com botão de erro

Clique no botão Erros para saber mais sobre o erro:

Detalhes do erro da extensão

Para saber mais sobre a depuração do service worker, da página de opções e dos scripts de conteúdo, consulte Depuração extensões padrão.

Estruturar um projeto de extensão

Há muitas maneiras de estruturar um projeto de extensão: No entanto, o único pré-requisito é colocar o manifest.json no diretório raiz da extensão, como no exemplo a seguir:

O conteúdo de uma pasta de extensão: manifest.json, background.js, pastas de scripts, pasta pop-up e pasta de imagens.

Usar o TypeScript

Se você estiver desenvolvendo com um editor de código, como VSCode ou Atom, use o npm pacote chrome-types para aproveitar o preenchimento automático do Chrome API. Esse pacote npm é atualizado automaticamente quando o código-fonte do Chromium mudanças.

🚀

Escolha um dos tutoriais a seguir para começar sua jornada de aprendizado de extensão.

Extensão O que você vai aprender
Executar scripts em todas as páginas Para inserir um elemento em cada página automaticamente.
Injetar scripts na guia ativa Para executar o código na página atual depois de clicar na ação da extensão.
Gerenciar guias Criar um pop-up que gerencie guias do navegador.
Processar eventos com service workers Como um service worker de extensão lida com eventos.