Como escrever um plugin web para Flutter: Parte 2
Um guia para escrever plugins web modernos para Flutter
Introdução
Na Parte 1 deste guia, você aprendeu a adicionar suporte web a um plugin Flutter usando as mesmas tecnologias que os plugins Android e iOS usam:
MethodChannels. Embora esse seja um método viável para adicionar suporte web a um plugin Flutter, ele tem algumas desvantagens.
Por um lado, há sobrecarga desnecessária ao enviar chamadas de método do plugin por um MethodChannel. Na web, todo o seu app é compilado em um único bundle JavaScript, então o código do plugin serializa sem necessidade a chamada de método em um array de bytes, que é imediatamente desserializado pelo plugin web.
Outra desvantagem de usar um MethodChannel é que ele dificulta a remoção (por tree-shaking) de código de plugin não utilizado pelo compilador. O plugin web chama o método apropriado com base no nome da chamada de método passada pelo
MethodChannel, então o compilador precisa presumir que todos os métodos do plugin estão ativos, e nenhum deles pode ser removido por tree-shaking.
Neste artigo, você vai aprender uma forma diferente de adicionar suporte web a um plugin Flutter. Se você planeja adicionar suporte web a um dos plugins mantidos pela equipe do Flutter (ou seja, um plugin do repositório flutter/plugins ou FirebaseExtended/flutterfire
), então você deve implementá-lo desta forma.
Plugins federados
Antes de mostrar como implementar um plugin, vale discutir como estruturamos plugins multiplataforma na equipe do Flutter. Queremos que os plugins mantidos pela equipe do Flutter sejam modelos que mostrem as melhores práticas para implementar plugins Flutter. A principal diferença entre a forma antiga e a nova de escrever plugins Flutter é que as implementações específicas de cada plataforma ficam em pacotes diferentes. Chamamos um plugin implementado dessa forma de plugin federado.
Vantagens
Por que separar as várias implementações em múltiplos pacotes em vez de juntá-las em um único pacote? Há algumas razões pelas quais isso é melhor para a manutenibilidade e o crescimento de longo prazo de um plugin:
-
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.
Reestruturar seu plugin como um plugin federado permite que qualquer pessoa implemente suporte a novas plataformas sem exigir que você faça isso. Por exemplo, se o Flutter oferecer suporte ao Nintendo Switch no futuro, um especialista em Switch pode adicionar suporte ao seu plugin sem que você precise aprender todas as APIs novas. Você pode até revisar o novo plugin para Switch e, se ele atender aos seus padrões, torná-lo uma “implementação endossada”, o que significa que quem usa o seu plugin nem precisará depender dele explicitamente para usá-lo!
Interfaces de plataforma
Como podemos implementar suporte web para um plugin sem usar um MethodChannel? Criando uma abstração que descreve exatamente o que o pacote do plugin (como
package:url_launcher) exige de suas implementações específicas de plataforma (como package:url_launcher_web). Essa abordagem abstrai
como o pacote do plugin se comunica com a implementação da plataforma e a substitui por uma descrição de
o que comportamento e dados o pacote do plugin exige da plataforma. No contexto dos plugins Flutter, chamamos essa abstração de
interface de plataforma.
Exemplo: url_launcher Esboço de interface de plataforma
Para dar um exemplo concreto de interface de plataforma, vamos olhar uma interface de plataforma que poderia ser definida para
package:url_launcher. Nossa primeira implementação web de url_launcher configurou um
MethodChannel que escutava chamadas ao método launch, que recebia um parâmetro
url. Então, para que um backend específico de plataforma funcione com package:url_launcher, ele precisa implementar um método com a assinatura
Future<bool> launch(String url). Uma interface de plataforma razoável para package:url_launcher seria assim:
abstract class UrlLauncherPlatform {
/// Launches the given [url]. Completes to [true] if the launch was successful.
Future<bool> launch(String url);
}
Migrando um plugin para usar uma interface de plataforma
No repositório GitHub flutter/plugins, adotamos um estilo para escrever plugins federados com interfaces de plataforma. Você deve seguir esse estilo se quiser que um Pull Request adicionando suporte a uma nova plataforma seja aceito em um dos plugins oficialmente suportados. Migrar um plugin para o novo formato de interface de plataforma federada é feito em 3 passos (3 PRs):
Adicione o pacote
<plugin name>_platform_interface.Migre o plugin para usar a interface de plataforma.
Adicione um pacote
<plugin name>_webque estenda a interface de plataforma.
Vamos trabalhar em um exemplo de como isso seria feito para um plugin real.
Exemplo: migrando o package:url_launcher

Passo 1: criando o pacote da interface de plataforma
No primeiro passo, vamos criar o pacote da interface de plataforma e reorganizar o código existente para usar nosso layout de diretórios de plugin federado. Para fins deste exemplo, estamos assumindo que o plugin está em um repositório com layout semelhante ao repositório GitHub
flutter/plugins (ou seja, o plugin fica em um diretório como
packages/url_launcher). Especificamente, estamos assumindo um layout que se parece com isto:
- README.md
- packages/
- some_other_plugin/
…
- url_launcher/
- pubspec.yaml
- lib/
…
- android/
…
- ios/
…
A ideia central dessa refatoração é criar um diretório que contenha não só o pacote do plugin, mas também o pacote da interface de plataforma e o pacote web. Queremos mover
packages/url_launcher para packages/url_launcher/url_launcher e criar outro pacote
packages/url_launcher/url_launcher_platform_interface (e, depois, criar mais um pacote
packages/url_launcher/url_launcher_web).
Mova url_launcher para seu próprio subdiretório
Estando no diretório packages/, você pode mover o plugin url_launcher para um subdiretório federado executando o seguinte:
$ git mv url_launcher url_launcher_tmp
$ mkdir url_launcher
$ git mv url_launcher_tmp url_launcher/url_launcher
$ git commit -m "Move url_launcher to url_launcher/url_launcher"
Crie o pacote url_launcher_platform_interface
Vá para o diretório packages/url_launcher que criamos no passo anterior. Em seguida, crie o pacote da interface de plataforma executando:
$ mkdir url_launcher_platform_interface
Agora, você precisa adicionar alguns arquivos em url_launcher_platform_interface para torná-lo um pacote de verdade. Para o arquivo de licença, normalmente você pode git cp a LICENSE do “pacote do plugin” (nesse caso, package:url_launcher). Você deve criar um arquivo CHANGELOG.md com o seguinte conteúdo:
## 1.0.0
- Initial open-source release.
Você também precisa definir um pubspec.yaml; você pode usar o pubspec.yaml
do package:url_launcher_platform_interface real como modelo. A observação sobre evitar breaking changes deve ser incluída na
pubspec.yaml de todo pacote de interface de plataforma.
Por fim, você também precisa de um arquivo README.md. Novamente, você pode usar o README.md
do package:url_launcher_platform_interface real como modelo.
Vamos ao código de fato. Edite o arquivo lib/url_launcher_platform_interface.dart e cole o seguinte código:
import 'dart:async';
import 'package:plugin_platform_interface/plugin_platform_interface.dart';
import 'method_channel_url_launcher.dart';
/// The interface that implementations of url_launcher must implement.
///
/// Platform implementations should extend this class rather than implement it as `url_launcher`
/// does not consider newly added methods to be breaking changes. Extending this class
/// (using `extends`) ensures that the subclass will get the default implementation, while
/// platform implementations that `implements` this interface will be broken by newly added
/// [UrlLauncherPlatform] methods.
abstract class UrlLauncherPlatform extends PlatformInterface {
/// Constructs a UrlLauncherPlatform.
UrlLauncherPlatform() : super(token: _token);
static final Object _token = Object();
static UrlLauncherPlatform _instance = MethodChannelUrlLauncher();
/// The default instance of [UrlLauncherPlatform] to use.
///
/// Defaults to [MethodChannelUrlLauncher].
static UrlLauncherPlatform get instance => _instance;
/// Platform-specific plugins should set this with their own platform-specific
/// class that extends [UrlLauncherPlatform] when they register themselves.
static set instance(UrlLauncherPlatform instance) {
PlatformInterface.verifyToken(instance, _token);
_instance = instance;
}
/// Launches the given [url]. Completes to [true] if the launch was successful.
Future<bool> launch(String url) {
throw UnimplementedError('launch() has not been implemented.');
}
}
Nos comentários do código acima, mais uma vez, as implementações de plataforma são instruídas a usar
extends em vez de implements para escrever suas implementações de UrlLauncherPlatform. Este é o mesmo aviso dos arquivos
pubspec.yaml e README.md. A classe não só avisa quem implementa para usar
extends em vez de implements, como também impõe isso estendendo PlatformInterface. Se você tiver interesse em ver como
PlatformInterface garante que subtipos usem extends em vez de implements, confira
package:plugin_platform_interface. O principal a levar do código acima é que você precisa ter o mesmo boilerplate nas suas classes de interface de plataforma para impedir que as implementações usem
implements.
Observe também o getter e o setter instance na interface de plataforma. Novas plataformas podem oferecer suporte a um plugin extendando a interface de plataforma e definindo sua classe específica de plataforma como instância padrão. A instância padrão de qualquer interface de plataforma deve sempre ser uma que use
MethodChannel para enviar a chamada de método pelo canal ao backend da plataforma. Usar como padrão uma implementação baseada em um
MethodChannel significa que as implementações existentes de Android e iOS continuarão funcionando por padrão (assim como as implementações web, se tiverem sido feitas usando
MethodChannel, como mostrado em Parte 1
deste guia).
O último ponto a observar é que todos os métodos da interface de plataforma devem ter uma implementação padrão que apenas lança um
UnimplementedError. Como toda implementação de UrlLauncherPlatform precisa usar
extends, se um novo método for adicionado à interface, não será uma breaking change que quebre apps. Se uma implementação usasse
implements, seria uma breaking change, porque essa implementação deixaria de implementar todos os métodos da interface.
Criando method_channel_url_launcher.dart
Definimos a UrlLauncherPlatform padrão como MethodChannelUrlLauncher no último passo. Agora precisamos escrever
MethodChannelUrlLauncher. Edite lib/method_channel_url_launcher.dart e cole o seguinte:
import 'dart:async';
import 'package:flutter/services.dart';
import 'url_launcher_platform_interface.dart';
const MethodChannel _channel = MethodChannel('plugins.flutter.io/url_launcher');
/// An implementation of [UrlLauncherPlatform] that uses method channels.
class MethodChannelUrlLauncher extends UrlLauncherPlatform {
@override
Future<bool> launch(String url) {
return _channel.invokeMethod<bool>(
'launch',
<String, Object>{
'url': url,
},
);
}
}
Se você seguiu a Parte 1 deste guia, vai reconhecer o código para invocar o método no
MethodChannel acima. No próximo passo, quando refatorarmos package:url_launcher
para usar package:url_launcher_platform_interface, como a interface de plataforma padrão usa
MethodChannel para despachar as chamadas, todas as plataformas já existentes para package:url_launcher
devem continuar funcionando.
Finalizando o package:url_launcher_platform_interface
Com esse código escrito, terminamos package:url_launcher_platform_interface. Tudo o que falta é fazer o commit do novo código, enviá-lo para o controle de versão (por exemplo, fazer merge de um PR no GitHub) e publicar o novo pacote no pub.dev. Você deve publicar esse pacote no pub.dev antes de avançar para o próximo passo, porque vamos refatorar
package:url_launcher para depender desse novo pacote.
Passo 2: refatorando o package:url_launcher para usar a interface de plataforma
Agora que o nosso pacote de interface de plataforma, da Etapa 1, foi publicado no pub.dev, vamos usá-lo em package:url_launcher.
Atualizando dependências
Em pubspec.yaml de package:url_launcher, adicione uma dependência de url_launcher_platform_interface
conforme mostrado abaixo:
name: url_launcher
version: <bump to next minor version>
# …
dependencies:
flutter:
sdk: flutter
url_launcher_platform_interface: ^1.0.0
# …
Refatorando todos os usos de MethodChannel
Se você se lembra da Parte 1 deste guia, nosso package:url_launcher (simplificado)
continha o seguinte método launch():
const MethodChannel _channel = MethodChannel('plugins.flutter.io/url_launcher');
Future<bool> launch(String urlString) async {
assert(urlString != null);
final bool result = await _channel.invokeMethod<bool>(
'launch',
<String, Object>{
'url': urlString,
},
);
...
return result;
}
Precisamos refatorar isso para usar a interface de plataforma que acabamos de definir. Altere para o seguinte:
Future<bool> launch(String urlString) async {
assert(urlString != null);
final bool result = await UrlLauncherPlatform.instance.launch(urlString);
...
return result;
}
Como vimos na seção anterior, como o UrlLauncherPlatform padrão usa MethodChannel, essa refatoração é segura. Não estamos mudando o comportamento com essa alteração, apenas preparando o caminho para que as plataformas implementem
package:url_launcher sem usar method channels.
Não deixe de adicionar uma entrada no CHANGELOG.md dizendo que você está migrando package:url_launcher
para usar a interface de plataforma. Com essa pequena refatoração concluída, você pode fazer commit das suas alterações, enviar
package:url_launcher para o pub.dev e seguir para a implementação de package:url_launcher
para a plataforma web.
Etapa 3: implementando o package:url_launcher_web usando a interface de plataforma
Na Parte 1 deste guia, criamos um
package:url_launcher_web que usa MethodChannel para se comunicar com o plugin. Vamos refatorar esse plugin para usar a interface de plataforma.
Substitua o conteúdo de lib/url_launcher_web.dart pelo seguinte:
import 'dart:async';
import 'dart:html' as html;
import 'package:flutter_web_plugins/flutter_web_plugins.dart';
import 'package:meta/meta.dart';
import 'package:url_launcher_platform_interface/url_launcher_platform_interface.dart';
/// The web implementation of [UrlLauncherPlatform].
///
/// This class implements the `package:url_launcher` functionality for the web.
class UrlLauncherPlugin extends UrlLauncherPlatform {
/// Registers this class as the default instance of [UrlLauncherPlatform].
static void registerWith(Registrar registrar) {
UrlLauncherPlatform.instance = UrlLauncherPlugin();
}
@override
Future<bool> launch(String url) {
return Future<bool>.value(html.window.open(url, '') != null);
}
}
Repare que mudamos UrlLauncherPlugin para extend UrlLauncherPlatform. Ainda temos o método
registerWith() de antes, mas agora, em vez de registrar um MethodChannel, registramos que esta é a instância padrão de
UrlLauncherPlatform. Agora, em package:url_launcher, quando ele chamar UrlLauncherPlatform.instance.launch()
vai chamar o método launch() que definimos aqui.
Já falamos sobre as vantagens de usar uma interface de plataforma, mas aqui podemos ver isso com mais clareza. Repare que não estamos mais serializando e desserializando cada chamada de método do plugin, apenas chamamos um método. Escrever implementações específicas de plataforma para um plugin não exige mais entender as APIs
MethodChannel do Flutter; fica claro que esta classe implementa toda a funcionalidade necessária para fazer
package:url_launcher funcionar na web.
Princípios de design da interface de plataforma
O exemplo acima é bem simples; a interface de plataforma tem apenas um método. Nesta seção, vamos abordar alguns princípios gerais para ter em mente ao criar um pacote de interface de plataforma para um plugin. Se você mantiver esses princípios em mente, criar um pacote de interface de plataforma para um plugin será direto na quase totalidade dos casos.
Faça um mapeamento 1:1 com as chamadas de MethodChannel
No caso ideal, você pode projetar uma interface de plataforma para um plugin encontrando todos os lugares em que o plugin chama o
MethodChannel e criando um método na interface de plataforma correspondente a cada chamada. Foi isso que fizemos no exemplo
package:url_launcher acima. Isso torna muito simples implementar a implementação padrão da interface de plataforma apoiada por um
MethodChannel, já que cada método da interface de plataforma corresponde exatamente a uma chamada de MethodChannel. Isso também torna trivial refatorar o pacote do plugin para usar a interface de plataforma: basta substituir cada chamada
MethodChannel pela chamada correspondente na interface de plataforma.
Mantenha o pacote da interface de plataforma mínimo
Evite trazer abstrações do pacote do plugin para o pacote da interface de plataforma. Isso permite que o pacote do plugin seja mais flexível.
Para dar um exemplo, suponha que, em vez de um método launch(), a interface package:url_launcher
tivesse esta aparência:
class UrlLauncher {
final String url;
const UrlLauncher(this.url);
Future<bool> launch() {
// Contains a method channel call to launch the url
}
}
Suponha ainda que imitamos essa API na interface de plataforma, resultando em algo como:
class UrlLauncherPlatform {
Launcher createLauncher(String url);
}
class Launcher {
Future<bool> launch();
}
Agora não vamos conseguir refatorar package:url_launcher para uma API diferente sem também refatorar
package:url_launcher_platform_interface. Se package:url_launcher_platform_interface
tivesse seguido o conselho acima e tivesse apenas um método para cada chamada de MethodChannel, então a API falsa para
package:url_launcher acima e a API real seriam ambas simples de implementar pela implementação da plataforma.
Force que as implementações usem extends
Já mencionamos isso algumas vezes neste artigo, mas é um ponto muito importante que merece ser repetido. Certifique-se de usar
package:plugin_platform_interface para garantir que as implementações da sua interface de plataforma usem
extends em vez de implements. Leia mais sobre como implementar plugins federados
para informações de base sobre por que implements é uma má ideia para interfaces de plataforma.
Conclusão
Seja você escrevendo um plugin novo ou adicionando suporte à web a um existente, usar uma interface de plataforma vai deixar seu plugin preparado para o futuro e muito mais fácil de estender e manter a longo prazo. Neste artigo, você aprendeu a refatorar seu plugin para usar uma interface de plataforma e a escrever um plugin web usando essa interface. Agora, mãos à obra e escreva seus plugins!