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:

dart
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):

  1. Adicione o pacote <plugin name>_platform_interface.

  2. Migre o plugin para usar a interface de plataforma.

  3. Adicione um pacote <plugin name>_web que 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:

bash
$ 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:

bash
$ 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:

markdown
## 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:

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

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

yaml
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():

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

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

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

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

dart
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!

Mais do Flutter