Desenvolvimento moderno de plugins Flutter
Explore a arquitetura moderna de plugins Flutter, incluindo plugins federados e implementações por plataforma.
Escrito por Amir Hardon, Chris Sells, Collin Jackson, Harry Terkelsen e Matt Carroll
2019 foi um ano de grandes avanços na tecnologia para autores de plugins Flutter. Lançamos a Android Plugin API 2.0, que oferece uma forma mais robusta e completa de implementar suporte ao Android nos seus plugins. Atualizamos o formato
pubspec.yaml para deixar claro como especificar suporte a Android e iOS, mas também a web, macOS, Windows e Linux. Além disso, como estamos levando o Flutter a suportar múltiplas plataformas, habilitamos a federação, possibilitando que várias equipes com diferentes expertises reúnam seu código em uma experiência integrada para o desenvolvedor Flutter que usa o plugin. E, por fim, avançamos bastante nos testes de plugins, com mais por vir.
Android Plugin API 2.0
Em dezembro de 2019, o Flutter publicou uma nova versão do seu embedding para Android. Este é o código Android responsável por integrar o Flutter dentro de um app Android. Ele inclui classes como
FlutterActivity, FlutterFragment, FlutterView e FlutterEngine. O embedding v2 para Android oferece suporte aos eventos padrão do ciclo de vida do Android e à separação da execução do Flutter da UI do Android, que faltavam no embedding v1. Durante o desenvolvimento do embedding v2 para Android, ficou claro que a API existente para plugins do Flutter era insuficiente para lidar com as novas capacidades do embedding v2. Era necessária uma nova API de plugins para Android. Vamos discutir essa API e como usá-la.
Primeiro, é importante entender a classe FlutterEngine no embedding v2 para Android. Um objeto FlutterEngine representa um único contexto de execução do Flutter. Isso significa que um FlutterEngine controla um isolate do Dart (o seu código Dart que começa com um entrypoint como main). Também significa que um FlutterEngine configura uma série de platform channels padrão que todos os apps Flutter exigem; ele inclui suporte a platform views, sabe como pintar uma textura com uma UI do Flutter e trata todos os outros requisitos fundamentais para executar um único app Flutter/Dart. Além disso, um app Android pode conter vários FlutterEngines ao mesmo tempo.
O conceito fundamental de “adicionar um plugin” a um app Flutter significa aplicar esse plugin a um único FlutterEngine. Por exemplo, se um app Flutter precisar acessar uma câmera, essa capacidade é obtida registrando um plugin de câmera em uma instância específica de FlutterEngine. Esse registro é feito automaticamente para você por meio de um GeneratedPluginRegistrant, mas é importante entender que cada FlutterEngine mantém seu próprio conjunto de plugins Flutter.

No antigo embedding v1 para Android, todos os plugins eram inicializados e configurados logo no início do app Android, e havia sempre apenas uma experiência Flutter. No embedding v2, não presumimos quando um plugin será inicializado, e um plugin precisa ser inicializado uma vez por
FlutterEngine. Como resultado, todos os plugins Flutter para Android agora precisam oferecer suporte a instanciação em vez de inicialização estática, e precisam suportar ser anexados e desanexados de um
FlutterEngine. Os exemplos de código a seguir demonstram a diferença entre a implementação antiga de inicialização de plugins da v1 e o novo processo de inicialização da v2.
Inicialização antiga de plugin
class MyOldPlugin {
public static void registerWith(PluginRegistrar registrar) {
// Obtain any references that the plugin requires from the
// registrar.
//
// This plugin is now considered "initialized" and "attached"
// to a Flutter experience.
}
}
Nova inicialização de plugin
class MyNewPlugin implements FlutterPlugin {
public MyNewPlugin() {
// All Android plugin classes must support a no-args
// constructor. A no-arg constructor is provided by
// default without declaring one, but we include it here for
// clarity.
//
// At this point your plugin is instantiated, but it
// isn't attached to any Flutter experience. You should not
// attempt to do any work here that is related to obtaining
// resources or manipulating Flutter.
}
@override
public void onAttachedToFlutterEngine(FlutterPluginBinding binding) {
// Your plugin is now attached to a Flutter experience
// represented by the given FlutterEngine.
//
// You can obtain the associated FlutterEngine with
// binding.getFlutterEngine()
//
// You can obtain a BinaryMessenger with
// binding.getBinaryMessenger()
//
// You can obtain the Application context with
// binding.getApplicationContext()
//
// You cannot access an Activity here because this
// FlutterEngine is not necessarily displayed within an
// Activity. See the ActivityAware interface for more info.
}
@override
public void onDetachedFromFlutterEngine(FlutterPluginBinding binding) {
// Your plugin is no longer attached to a Flutter experience.
// You need to clean up any resources and references that you
// established in onAttachedToFlutterEngine().
}
}
Como mostrado na nova API de plugins, seu plugin precisa esperar até que onAttachedToFlutterEngine() seja concluído antes de executar qualquer ação significativa, e deve respeitar
onDetachedFromFlutterEngine() liberando todos os recursos. É possível que seu plugin seja anexado e desanexado várias vezes.
Além disso, seu plugin não pode depender de uma referência de Activity dentro de onAttachedToFlutterEngine(). Só porque seu plugin está anexado a uma experiência Flutter não significa que essa experiência esteja sendo exibida em uma Activity.
Esta é uma das diferenças mais significativas entre as APIs antiga e nova de plugins.
Na API antiga de plugins da v1, os autores podiam depender de um Activity estar disponível imediata e permanentemente. Isso não é mais verdade.
Plugins que precisam de acesso a um Activity devem implementar uma segunda interface, chamada ActivityAware. A
interface ActivityAware adiciona callbacks à sua classe de plugin que informam quando ela está em um
Activity, quando esse Activity passa por mudanças de configuração e quando seu plugin não está mais em um
Activity. Seu plugin deve respeitar esses callbacks. O exemplo a seguir mostra o esboço de um plugin
ActivityAware:
class MyNewPlugin implements FlutterPlugin, ActivityAware {
@override
public void onAttachedToFlutterEngine(FlutterPluginBinding binding) {
// ...
}
@override
public void onDetachedFromFlutterEngine(FlutterPluginBinding binding) {
// ...
}
@override
public void onAttachedToActivity(ActivityPluginBinding binding) {
// Your plugin is now associated with an Android Activity.
//
// If this method is invoked, it is always invoked after
// onAttachedToFlutterEngine().
//
// You can obtain an Activity reference with
// binding.getActivity()
//
// You can listen for Lifecycle changes with
// binding.getLifecycle()
//
// You can listen for Activity results, new Intents, user
// leave hints, and state saving callbacks by using the
// appropriate methods on the binding.
}
@override
public void onDetachedFromActivityForConfigChanges() {
// The Activity your plugin was associated with has been
// destroyed due to config changes. It will be right back
// but your plugin must clean up any references to that
// Activity and associated resources.
}
@override
public void onReattachedToActivityForConfigChanges(
ActivityPluginBinding binding
) {
// Your plugin is now associated with a new Activity instance
// after config changes took place. You may now re-establish
// a reference to the Activity and associated resources.
}
@override
public void onDetachedFromActivity() {
// Your plugin is no longer associated with an Activity.
// You must clean up all resources and references. Your
// plugin may, or may not ever be associated with an Activity
// again.
}
}
A nova API de plugins reconhece explicitamente que um plugin pode ou não ter um Activity associado, e que qualquer
Activity pode ser destruído e recriado a qualquer momento por causa de mudanças de configuração. Essas questões devem ser familiares a todos os desenvolvedores Android.
A chave para escrever um plugin para o embedding Android v2 do Flutter é respeitar cada callback do ciclo de vida que o seu plugin implementa. Desde que você espere o momento certo para estabelecer referências e as libere no momento apropriado, seu plugin vai funcionar como esperado.

Alguns plugins, como um plugin de câmera, só fazem sentido quando um Activity está disponível. Então, o que esses plugins devem fazer? No caso de plugins apenas de UI, eles podem esperar até que
onAttachedToActivity() seja executado antes de fazer qualquer trabalho. Depois, em onDetachedFromActivity(), esses plugins podem limpar todas as referências e, essencialmente, desativar a si mesmos. Não há exigência de que um plugin faça algo especial dentro de
onAttachedToFlutterEngine(). Tudo bem que um plugin só faça trabalho quando estiver anexado a um Activity.
Para mais detalhes sobre como migrar o seu plugin Android da API v1 para a API v2, veja Suporte às novas APIs de plugins Android no flutter.dev.
Novo formato pubspec
Tradicionalmente, um plugin Flutter era um único pacote que permitia que apps Flutter rodando em Android e iOS acessassem funcionalidades específicas da plataforma; tecnicamente, um plugin era composto de código Dart apoiado por código específico de Android e de iOS. Mesmo que a suposição de que qualquer plugin Flutter suporta Android e iOS não fosse precisa (por exemplo, o plugin
android_intent suporta apenas Android), decidiu-se projetar inicialmente o ecossistema de plugins com base nessa suposição. A suposição estava majoritariamente correta, o que significava que o custo geral dos poucos casos em que ela estava errada era baixo, e a simplificação permitiu progresso rápido e foco.
Com o Flutter crescendo para suportar muitas outras plataformas, decidimos abandonar essa suposição simplificadora, já que:
-
Esperamos que muitos plugins suportem apenas um subconjunto das plataformas suportadas pelo Flutter (ainda mais com os plugins federados, descritos abaixo).
-
Queremos liberar recursos de ferramentas que exigem conhecimento das plataformas suportadas por um plugin (como uma busca mais inteligente no pub.dev e operações de ferramentas informadas pela plataforma).
A peça principal que faltava era uma indicação clara de quais plataformas um plugin suporta, por isso redesenhamos o schema
pubspec do plugin Flutter em torno do suporte multiplataforma.
No schema pubspec anterior, a chave flutter.plugin continha as diferentes configurações do plugin; agora introduzimos uma nova chave por plataforma sob a chave
flutter.plugin.platforms, com a configuração específica da plataforma. Por exemplo, veja como fica o
pubspec de um plugin que suporta Android, iOS, macOS e web:
flutter:
plugin:
platforms:
android:
package: com.example.hello
pluginClass: HelloPlugin
ios:
pluginClass: HelloPlugin
macos:
pluginClass: HelloPlugin
web:
pluginClass: HelloPlugin
fileName: hello_web.dart
environment:
sdk: ">=2.1.0 <3.0.0"
# Flutter versions prior to 1.10 did not support
# the flutter.plugin.platforms map.
flutter: ">=1.10.0"
Um plugin que suporta um subconjunto dessas plataformas pode omitir as chaves de plataforma do mapa de plataformas, por exemplo:
flutter:
plugin:
platforms:
android:
package: com.example.hello
pluginClass: HelloPlugin
ios:
pluginClass: HelloPlugin
environment:
sdk: ">=2.1.0 <3.0.0"
# Flutter versions prior to 1.10 did not support
# the flutter.plugin.platforms map.
flutter: ">=1.10.0"
Observe que é necessário um Flutter SDK superior a 1.10.0 para usar o novo schema, já que essa é a primeira versão em que a ferramenta do Flutter oferece suporte a ele.
Migrando um plugin existente para o novo schema
Esta seção usa o plugin battery como exemplo e percorre a migração de um plugin de exemplo do schema anterior para o novo.
O mais importante ao migrar é declarar suporte apenas às plataformas que o plugin realmente suporta (isso não era possível antes, o que obrigava plugins que suportavam só Android a incluir uma implementação iOS sem operação, e vice-versa).
Estas são as partes relevantes do arquivo pubspec.yaml de um plugin de exemplo antes da migração:
name: sample
version: 0.3.1+5
flutter:
plugin:
androidPackage: io.flutter.plugins.sample
iosPrefix: FLT
pluginClass: SamplePlugin
environment:
flutter: ">=1.6.7 <2.0.0"
Supondo que o plugin suporte Android e iOS, atualizar para o novo schema envolve:
-
Aumentar a versão mínima exigida do Flutter para 1.10.0 (que é a primeira versão que suporta o novo schema).
Um aumento de versão minor
Substituir os campos atuais em
flutter.pluginpelo novo campo platforms.-
Se o campo
iosPrefixfoi usado antes, renomear o arquivo principal do plugin iOS (mais detalhes abaixo).
O pubspec atualizado para este plugin fica assim:
name: sample
version: 0.3.2
flutter:
plugin:
platforms:
android:
package: io.flutter.plugins.sample
pluginClass: SamplePlugin
ios:
pluginClass: FLTSamplePlugin
environment:
flutter: ">=1.10.0 <2.0.0"
Observe que, como o plugin suporta Android e iOS, estas são as únicas chaves em flutter.plugin.platforms. O valor do campo
flutter.plugin.androidPackage no schema antigo passa a ser o valor de flutter.plugin.platforms.android.package. O novo schema não tem equivalente para o campo
iosPrefix, já que o pluginClass do iOS tem uma chave dedicada, e podemos usar o prefixo no campo
flutter.plugin.platforms.ios.pluginClass, que é definido como FLTSamplePlugin.
Plugins que usavam anteriormente o campo iosPrefix
O schema anterior implicava uma inconsistência entre o nome da interface principal do plugin iOS e o nome do seu arquivo; por exemplo, para este plugin de exemplo definido com o schema anterior, haveria um arquivo SamplePlugin.h que declara uma interface FLTSamplePlugin. Esse tipo de inconsistência não é mais suportado, então o arquivo SamplePlugin.h deve ser renomeado para FLTSamplePlugin.h ao atualizar para o novo schema. Plugins que não usaram a chave
iosPrefix não precisam renomear nenhum arquivo.
Para mais informações sobre pacotes de plugins em desenvolvimento que suportam qualquer número de plataformas, veja Desenvolvendo pacotes de plugin no flutter.dev.
Federação
O novo schema pubspec não só permite especificar exatamente quais plataformas o seu plugin suporta, como também dá flexibilidade para distribuir as implementações por vários pacotes. No passado, o código Dart do plugin, o código Android (Java ou Kotlin) e o código iOS (Objective-C ou Swift) precisavam estar no mesmo pacote Dart. Agora, se quisermos adicionar suporte a outra plataforma (Web, macOS, Windows etc.), ela não precisa estar no mesmo pacote. Plugins distribuídos em vários pacotes são chamados de plugins federados.
Plugins federados têm várias vantagens sobre plugins de pacote único, incluindo:
-
Quem mantém o plugin não precisa ter domínio de todas as plataformas Flutter suportadas (Android, iOS, Web, macOS etc.).
-
Você pode adicionar suporte a uma nova plataforma sem que o autor original do plugin precise revisar e incorporar o seu código.
Cada pacote pode ser mantido e testado separadamente.
Então, como exatamente você cria um plugin federado? Vamos começar com alguma terminologia:
-
Pacote voltado ao app: este é o pacote que você importaria no seu app para usar o plugin. Por exemplo,
package:url_launcheré um pacote voltado ao app. O pacote voltado ao app declara a API voltada ao app e trabalha com vários pacotes de plataforma para executar funcionalidades específicas de cada plataforma. -
Pacote de plataforma: é um pacote que implementa a funcionalidade específica da plataforma de que o pacote voltado ao app precisa. Um exemplo é o
package:url_launcher_web: este pacote é usado pelopackage:url_launcherpara abrir URLs quando o app Flutter roda na plataforma web. Pacotes de plataforma não devem ser importados no app; eles servem apenas para que o pacote voltado ao app chame o código específico da plataforma necessário. -
Pacote de interface de plataforma: é a cola que mantém juntos o pacote voltado ao app e os pacotes de plataforma. Enquanto o pacote voltado ao app declara uma API que pode ser chamada por um app Flutter, o pacote de interface de plataforma declara uma interface que cada pacote de plataforma deve implementar para dar suporte ao pacote voltado ao app. Ter um único pacote que define essa interface garante que todos os pacotes de plataforma implementem a mesma funcionalidade de forma uniforme.

A figura acima mostra o grafo de dependências entre o app, o pacote voltado ao app, os pacotes de plataforma e o pacote de interface de plataforma. O app só importa o pacote voltado ao app (neste caso,
package:url_launcher).
Como a interface de plataforma faz a ligação entre o pacote voltado ao app e o pacote de plataforma correto? No passado, não havia “pacotes de plataforma”, apenas uma subpasta para o código Android e outra para o código iOS. O pacote voltado ao app se comunicava com o código da plataforma por meio de um
MethodChannel. Você pode pensar no MethodChannel como a “interface de plataforma” de fato, porque o pacote voltado ao app chama o
MethodChannel, e o código da plataforma correspondente precisa estar escutando, em um MethodChannel
, pelos métodos corretos com os argumentos corretos. Não há como confirmar estaticamente que o código Android ou iOS está escutando as chamadas MethodChannel corretas.
Forma antiga de abrir uma URL
Future<void> launch(String url) {
channel.invokeMethod('launch', {
'url': url,
});
}
Na estrutura de plugin federado, o pacote de interface de plataforma substitui o MethodChannel. A funcionalidade específica da plataforma de que o pacote voltado ao app precisa dos pacotes de plataforma fica encapsulada em uma interface de plataforma. No nosso exemplo, o pacote voltado ao app é o package:url_launcher, e a única funcionalidade específica da plataforma de que ele precisa é a capacidade de abrir uma URL em cada plataforma. Uma interface de plataforma (bem) simples ficaria assim:
abstract class UrlLauncherPlatform {
/// Launches the given [url].
Future<void> launch(String url);
/// The live "instance" of this platform interface.
///
/// This is set when the platform package is registered,
/// usually when the platform is initializing.
///
/// For example, the web platform package
/// (package:url_launcher_web) would extend this class with an
/// implementation that launched the URL in a new tab,
/// and at initialization time would set itself to be the live
/// instance with:
///
/// UrlLauncherPlatform.instance = WebUrlLauncher();
static UrlLauncherPlatform instance;
}
Agora, em vez de chamar o MethodChannel, o pacote voltado ao app chamaria a interface de plataforma.
Nova forma de abrir uma URL
Future<void> launch(String url) {
return UrlLauncherPlatform.instance.launch(url);
}
Então, o pacote voltado ao app chama a interface de plataforma. Como a interface de plataforma se conecta aos pacotes de plataforma? Os pacotes de plataforma implementam a interface de plataforma e se registram como a instância padrão dela quando a plataforma está sendo inicializada.
Por exemplo, se quiséssemos escrever package:url_launcher_web, bastaria escrever uma classe que estenda
UrlLauncherPlatform e abra uma URL para a plataforma web. O código ficaria mais ou menos assim:
class UrlLauncherWeb extends UrlLauncherPlatform {
/// The web platform automatically calls this when the app
/// initializes.
static void registerWith(Registrar registrar) {
var webLauncher = UrlLauncherWeb();
UrlLauncherPlatform.instance = webLauncher;
}
@override
Future<void> launch(String url) => window.open(url, '');
}
O bom de migrar para uma estrutura de plugin federado é que, uma vez configurados o pacote voltado ao app e o pacote de interface de plataforma, adicionar suporte a uma nova plataforma é simples (e você nem precisa fazer isso sozinho!). Basta criar um novo pacote de plataforma que estenda a interface de plataforma declarada no pacote de interface de plataforma.
Para mais detalhes sobre plugins federados, veja Federar plugins no flutter.dev.
Testando plugins
Ao escrever novos plugins multiplataforma ou adicionar plataformas a plugins existentes, você pode economizar tempo e dores de cabeça futuras escrevendo testes. Testes automatizados protegem o seu plugin contra regressões funcionais, para que você possa desenvolver novos recursos rapidamente e integrar contribuições.
Um plugin bem testado normalmente inclui vários tipos de teste espalhados por vários pacotes. É fácil perder tempo escrevendo testes instáveis (flaky) ou que quase nunca falham, então concentre-se nos testes que dão confiança de que os principais casos de uso continuam funcionando.
Testes com AutomatedWidgetsFlutterBinding
Testes que usam AutomatedWidgetsFlutterBinding rodam na máquina de desenvolvimento, e não em um dispositivo ou navegador. Por isso, rodam mais rápido, e parte da funcionalidade precisa ser fornecida por mocks.
No pacote voltado ao app (como o myplugin), os testes unitários do pacote garantem que as chamadas à API voltada ao app resultem nas interações esperadas com o pacote de interface de plataforma. Esses testes normalmente importam o
package:mockito para fornecer uma interface de plataforma falsa e verificar se ela recebe as chamadas corretas. Aqui está um exemplo de teste
do package:url_launcher:
test('returns true', () async {
when(mock.canLaunch('foo')).thenAnswer((_) =>
Future<bool>.value(true));
final bool result = await canLaunch('foo');
expect(result, isTrue);
});
No pacote de interface de plataforma (como o myplugin_platform_interface), uma interface de plataforma é uma classe abstrata e não pode ser instanciada diretamente. No entanto, o pacote de interface de plataforma normalmente também contém a implementação via method channel da interface, então é isso que você deve testar. Os testes desse pacote devem focar nas invocações de method channel que resultam das chamadas à interface de plataforma e ao method channel. Esses testes normalmente usam o
setMockMethodCallHandler
com o matcher isMethodCall
para verificar o comportamento.
test('canLaunch', () async {
await launcher.canLaunch('http://example.com/');
expect(
log,
<Matcher>[
isMethodCall('canLaunch', arguments: <String, Object>{
'url': 'http://example.com/',
})
],
);
});
Nos testes de plataforma (como myplugin_web), você pode aproveitar funcionalidades específicas da plataforma. No SDK atual do Flutter, o flutter test oferece uma flag --platform experimental que permite escolher rodar os testes em um ambiente semelhante ao Chrome, onde o dart:html está disponível.
Esse modo de teste é útil para escrever testes no pacote de implementação de plataforma (por exemplo, myplugin_web).
test('cannot launch "tel" URLs', () {
expect(canLaunch('tel:5551234567'), completion(isFalse));
});
Além disso, você pode rodar seus testes de interface gráfica no Chrome usando o suporte experimental a testes com ‘flutter drive’ na web.
Para mais informações sobre testes de plugins, veja Testando o seu plugin no flutter.dev.
Resumo
Como você pode ver, há muitos recursos novos para o desenvolvedor de plugins Flutter, permitindo criar plugins mais completos e robustos em mais plataformas. Se você tiver interesse em detalhes específicos da web, recomendo a série em duas partes de Harry Terkelsen sobre Como escrever um plugin Flutter para web (parte 1 e parte 2). Para mais informações sobre como escrever plugins em geral, a documentação Desenvolvendo pacotes de plugin no flutter.dev também é um ótimo recurso.