Extensões do Dart e Flutter DevTools
Um guia para criar ferramentas personalizadas no Dart e Flutter DevTools
Você já quis criar ferramentas para desenvolvedores de Dart e Flutter, mas não sabia por onde começar? Ou talvez não quisesse passar por todo o trabalho de estabelecer uma conexão com um app Dart ou Flutter em execução para acessar os dados de depuração? Mesmo que você tenha criado uma ferramenta de desenvolvimento, como implantá-la ou dar aos usuários acesso fácil a ela? Bem, temos boas notícias: agora você pode criar ferramentas para desenvolvedores sem todos esses obstáculos.
Com o novo framework de extensões do Dart & Flutter DevTools, você pode criar facilmente ferramentas para desenvolvedores que são fortemente integradas ao conjunto de ferramentas existente do DevTools. As extensões são construídas com Flutter web e aproveitam frameworks e utilitários existentes do DevTools para simplificar a experiência de criação de ferramentas.
Como funcionam as extensões do DevTools?
As extensões são distribuídas como parte de um pacote pub. Você pode adicionar uma extensão do DevTools a um pacote pub existente ou criar um novo pacote que forneça apenas uma extensão do DevTools. Nos dois casos, o usuário final precisa declarar uma dependência do pacote que fornece a extensão do DevTools para vê-la no DevTools.
Por exemplo, imagine que temos alguns package:foo, e este pacote fornece uma extensão do DevTools. Quando um usuário depende de package:foo no app dele, ele ganha automaticamente acesso à extensão do DevTools fornecida por este pacote. Quando o DevTools detecta que a extensão package:foo está disponível, com base em informações do app do usuário ou da IDE dele, uma nova aba “Foo” será adicionada ao DevTools, contendo as ferramentas de desenvolvimento fornecidas por package:foo.

Alguns exemplos de pacotes que adicionaram uma extensão do DevTools a um pacote existente são package:provider, package:patrol e package:drift.
Quais tipos de ferramentas são suportados?
Com o framework de extensões do DevTools, você pode criar muitos tipos de ferramentas, incluindo:
Ferramentas complementares para pacotes existentes
Novas ferramentas distribuídas como pacote próprio
Ferramentas que interagem com um app em execução
Ferramentas que não interagem com um app em execução
Ferramentas que interagem com arquivos de projeto abertos na IDE
-
Planejado para o futuro: ferramentas que interagem com o servidor de análise (vote nesta issue se quiser essa funcionalidade mais cedo!)
O framework de extensões do DevTools vem com recursos prontos que tornam a distribuição da sua extensão para os usuários simples:
Os usuários podem usar sua ferramenta a partir do DevTools no navegador
Os usuários podem usar sua ferramenta incorporada diretamente na IDE deles
Os usuários podem descobrir e abrir sua ferramenta a partir de IDEs compatíveis com Dart e Flutter
Agora vamos começar!
Escrevendo uma extensão do DevTools: um guia passo a passo
Antes de começar
O que você vai precisar:
SDK do Flutter
>= 3.17.0–0.0.pree SDK do Dart>= 3.2.-
Um pacote Pub (existente ou novo) ao qual adicionar uma extensão do DevTools.
Para usar os pacotes mais recentes devtools_extensions e devtools_app_shared, é aceitável desenvolver sua extensão a partir do canal master ou beta do Flutter.
Passo 1: configure a hierarquia dos seus pacotes
Extensões independentes
Para uma extensão independente (uma extensão que não é distribuída como parte de um pacote pub existente), é aceitável incluir o código-fonte da extensão no mesmo pacote com o qual ela é distribuída. Isso simplifica o desenvolvimento e, como os usuários do seu pacote vão adicionar uma dependência ao seu pacote como dev_dependency, o tamanho do pacote não afetará o tamanho do app do usuário. A estrutura do seu pacote ficará assim:
my_new_tool
extension/
devtools/
build/
... # pre-compiled output of the Flutter web app under lib/
config.yaml
lib/ # source code for your extension Flutter web app
src/
...
Como a extensão precisa ser construída como um app web Flutter, use flutter create para gerar o pacote da sua extensão do DevTools:
flutter create --template app --platforms web my_new_tool
Agora, use o pacote my_new_tool para configurar sua extensão na próxima etapa.
Extensões complementares
Para uma extensão complementar (uma extensão distribuída como parte de um pacote pub existente), recomendamos colocar o código-fonte da extensão fora do seu pacote pub. Isso ajuda a manter o tamanho do pacote o menor possível, já que você vai querer evitar inflar o tamanho dos apps dos usuários que dependem do seu pacote. Esta é a estrutura de pacote recomendada:
foo/ # formerly the repository root of your pub package
packages/
foo/ # your pub package
extension/
devtools/
build/
... # pre-compiled output of foo_devtools_extension/lib
config.yaml
foo_devtools_extension/
lib/ # source code for your extension Flutter web app
Passo 2: configure sua extensão
No pacote Dart que vai fornecer a extensão do DevTools aos usuários, adicione um diretório extension no nível raiz:
foo/
extension/
lib/
...
Dentro do diretório extension, crie a seguinte estrutura exatamente como mostrado:
extension/
devtools/
build/
config.yaml
O arquivo config.yaml contém os metadados que o DevTools precisa para carregar a extensão:
name: foo
version: 0.0.1
issueTracker: <link_to_your_issue_tracker.com>
materialIconCodePoint: '0xe0b1'
requiresConnection: true # optional field - defaults to true
Copie o conteúdo do arquivo config.yaml acima e cole no arquivo config.yaml que você acabou de criar no seu pacote. É importante usar exatamente o nome do arquivo e os nomes dos campos como mostrado, senão sua extensão pode não
carregar no DevTools.
Para cada chave, preencha o valor apropriado para o seu pacote.
-
name: o nome do pacote ao qual esta extensão do DevTools pertence. O valor deste campo é usado na barra de título da página da extensão. [obrigatório] -
version: a versão da sua extensão do DevTools. Este número de versão deve evoluir ao longo do tempo, à medida que você lança novos recursos da extensão. O valor deste campo é usado na barra de título da página da extensão. [obrigatório] -
issueTracker: a URL do seu rastreador de issues. Quando o usuário clica no link “Reportar um problema” na interface do DevTools, ele é direcionado para esta URL. [obrigatório]
-
materialIconCodePoint: corresponde ao valor de codepoint de um ícone de material/icons.dart. Este ícone é usado na aba da extensão na barra de abas do DevTools no nível superior. [obrigatório]
-
requiresConnection: se a extensão requer um app Dart ou Flutter conectado para ser usada. Este é um campo opcional que terá como padrãotruese não for especificado. [opcional]
Para a documentação mais atualizada da especificação config.yaml, veja extension_config_spec.md.
Agora é hora de construir sua extensão.
Passo 3: construa sua extensão
- Crie o app web Flutter.
Observação: pule esta etapa se estiver construindo uma extensão independente, já que você já fez isso ao configurar a hierarquia dos seus pacotes.
No diretório onde você quer que o código-fonte da sua extensão fique, execute o seguinte comando, substituindo
foo_devtools_extension por <your_package_name>_devtools_extension:
flutter create --template app --platforms web foo_devtools_extension
- Adicione a dependência
package:devtools_extensionsao seu app web Flutter da extensão.
flutter pub add devtools_extensions
Você provavelmente também vai querer adicionar uma dependência do package:devtools_app_shared, que contém serviços, utilitários e componentes de interface compartilhados para você usar ao construir sua extensão. Veja devtools_app_shared/example para exemplos de uso.
flutter pub add devtools_app_shared
- Adicione o widget
DevToolsExtensionna raiz do seu app web Flutter.
Em lib/main.dart, adicione o seguinte:
import 'package:devtools_extensions/devtools_extensions.dart';
import 'package:flutter/material.dart';
void main() {
runApp(const DevToolsExtension());
}
class FooDevToolsExtension extends StatelessWidget {
const FooDevToolsExtension({super.key});
@override
Widget build(BuildContext context) {
return const DevToolsExtension(
child: Placeholder(), // Build your extension here
);
}
}
O widget DevToolsExtension executa automaticamente toda a inicialização da extensão necessária para interagir com o DevTools. De qualquer lugar do seu app web da extensão, você pode acessar os globals:
-
extensionManager: um gerenciador para interagir com o DevTools ou com o framework de extensões. -
serviceManager: um gerenciador para interagir com o serviço de VM conectado, se houver. dtdManager: um gerenciador para interagir com o Dart Tooling Daemon, se houver.
Passo 4: depure sua extensão
Ao desenvolver e manter sua extensão do DevTools, você vai querer executar, depurar e testar seu app web Flutter da extensão. Você tem algumas opções diferentes para isso, descritas abaixo.
Opção A: use o ambiente simulado do DevTools (recomendado para desenvolvimento)
Para fins de depuração, você provavelmente vai querer usar o “ambiente simulado do DevTools”. Trata-se de um ambiente que permite construir sua extensão sem precisar desenvolvê-la como um iFrame incorporado ao DevTools. Executar sua extensão desta forma a envolve com um ambiente que simula a conexão entre o DevTools e a extensão. Também dá acesso ao hot restart e a um ciclo de desenvolvimento mais rápido.
Sua extensão do DevTools.
-
O URI do serviço de VM de um app de teste com o qual sua extensão do DevTools vai interagir. Este app deve depender do pacote pai da sua extensão (package:foo neste exemplo).
Botões para executar ações que o usuário pode disparar a partir do DevTools.
Logs mostrando as mensagens que serão enviadas entre sua extensão e o DevTools.
O ambiente simulado é habilitado pelo parâmetro de ambiente use_simulated_environment. Para executar seu app web da extensão com essa flag habilitada, adicione uma configuração ao seu arquivo launch.json no VS Code:
{
// ...
"configurations": [
// ...
{
"name": "foo_devtools_extension + simulated environment",
"cwd": "packages/foo_devtools_extension",
"request": "launch",
"type": "dart",
"args": [
"--dart-define=use_simulated_environment=true"
],
},
// ...
]
}
ou inicie seu app pela linha de comando com a flag adicionada:
flutter run -d chrome - dart-define=use_simulated_environment=true
Opção B: use um ambiente real do DevTools
Quando você tiver desenvolvido sua extensão até o ponto em que estiver pronto para testar suas mudanças em um ambiente real do DevTools, precisará executar uma série de etapas de configuração:
-
Desenvolva sua extensão até o ponto em que estiver pronto para testar as mudanças em um ambiente real do DevTools. Construa seu app web Flutter e copie os assets gerados de
your_extension_web_app/build/webpara o diretórioextension/devtools/builddo seu pacote pub.
Use o comando build_and_copy de package:devtools_extensions para ajudar com esta etapa.
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions build_and_copy --source=. --dest=path/to/your_pub_package/extension/devtools
Observação: se você estiver usando a estrutura de pacote recomendada acima para adicionar uma extensão a um pacote pub existente, o valor de
--destdeve ser../your_pub_package/extension/devtools.
Para garantir que sua extensão esteja configurada corretamente para ser carregada no DevTools, execute o comando validate de package:devtools_extensions. O argumento --package deve apontar para a raiz do pacote Dart com o qual esta extensão será publicada.
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions validate --package=path/to/your_pub_package
-
Prepare um ambiente de teste com uma dependência do seu pacote pub que fornece a extensão.
No projeto Dart ou Flutter em que você está adicionando uma dependência do seu pacote, adicione uma dependência path que aponte para o código-fonte local do seu pacote (o pacote que contém o diretório
extension/devtools/com os assets da sua extensão). Depois disso, executepub getno pacote.Se sua extensão requer um app em execução, então você vai precisar executar o app que depende da sua extensão.
Se sua extensão não requer um app em execução, então você vai precisar abrir o projeto Dart ou Flutter de teste que depende do seu pacote em uma IDE compatível (VS Code ou IntelliJ / Android Studio).
-
Inicie o DevTools de uma das seguintes formas:
Se sua extensão requer um app em execução, você pode abrir o DevTools pelo URI que foi impresso na linha de comando quando você executou o app de teste, ou pela IDE em que executou o app de teste.
Se sua extensão não requer um app em execução, você pode abrir o projeto Dart ou Flutter de teste que depende do seu pacote em uma IDE compatível (VS Code ou IntelliJ / Android Studio). Abra o DevTools pela IDE para ver sua extensão no navegador.
Se você precisar de alterações locais ou não lançadas do DevTools, vai precisar compilar e executar o DevTools a partir do código-fonte. Veja o CONTRIBUTING.md para um guia de como fazer isso. Você vai precisar compilar o DevTools com o servidor e o front-end para testar extensões — veja as instruções.
-
Depois de abrir o DevTools, você deve ver uma aba na barra de aplicativos do DevTools para a sua extensão. O estado habilitado ou desabilitado da sua extensão é gerenciado pelo DevTools, que o expõe em um menu “Extensions”, disponível nos botões de ação no canto superior direito da tela.
Passo 5: publique seu pacote com uma extensão do DevTools
Para que um pacote forneça uma extensão do DevTools aos seus usuários, ele precisa ser publicado com o conteúdo esperado no diretório
your_pub_package/extension/devtools/ (veja as instruções de configuração acima).
-
Garanta que o arquivo
extension/devtools/config.yamlexista e esteja configurado de acordo com as especificações acima. Você pode executar o comandovalidatea partir depackage:devtools_extensionspara verificar.
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions validate --package=path/to/pkg_providing_your_extension_assets
-
Use o comando
build_and_copyfornecido porpackage:devtools_extensionspara compilar sua extensão e copiar a saída para o diretórioextension/devtools:
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions build_and_copy --source=. --dest=path/to/your_pub_package/extension/devtools
Depois, publique seu pacote no pub.dev: flutter pub publish. Ao executar
pub publish, você verá um aviso se não tiver o arquivo config.yaml e um diretório build não vazio, como exigido.
Para mais orientações sobre a publicação do seu pacote, veja o package:devtools_extensions
guia de publicação.
Conclusão
Pronto! Agora, quando um usuário depender da versão mais recente do seu pacote, ele terá acesso automaticamente às ferramentas que você fornece na sua extensão do DevTools.
Para problemas e pedidos de funcionalidades, abra uma issue no rastreador de issues do DevTools.
Para suporte geral e acesso à comunidade de autores de extensões do DevTools, confira o canal #devtools-extension-authors no Discord (você precisará entrar primeiro no servidor do Flutter no Discord).
