Dica de design de API para widgets Flutter complexos
Pedir que um widget seja algo versus pedir que ele faça algo
Ao escrever widgets que gerenciam estado não trivial, às vezes fica difícil manter uma API limpa. Acredito que, em muitos casos, isso acontece porque se chega aos limites de expressividade das APIs baseadas em construtores. Lidamos com esses casos na equipe principal do Flutter e, embora não seja um problema super complexo, acho que desconhecer esses limites pode ser doloroso. Nomear o problema e levar esses limites em conta tem sido útil para mim, então quero compartilhar essas lições.
Vou começar com um exemplo: digamos que estamos construindo um widget WebView que mostra conteúdo web incorporado. Para simplificar, vamos começar com uma superfície de API mínima. Queremos poder carregar uma URL específica e especificar se o JavaScript está habilitado. Queremos que a API seja “Fluttery”, então criamos um widget com parâmetros de construtor para esses 2 controles. Que API simples! Todo desenvolvedor Flutter vai se sentir em casa de imediato! Quer carregar a página inicial do YouTube? É só construir o widget:
WebView(url: 'https://youtube.com', javascriptEnabled: true)
Você quer desabilitar o JavaScript? Basta reconstruir o widget:
WebView(url: 'https://youtube.com', javascriptEnabled: false)
Espera, digamos que, antes de reconstruirmos o WebView com javascriptEnabled=false, o usuário clicou em um link e o WebView navegou para uma URL diferente. Antes da reconstrução, o WebView estava em
https://flutter.dev. O que o widget deveria fazer quando for reconstruído com
(url: 'https://youtube.com', javascriptEnabled: false)? Deveria voltar para https://youtube.com? Deveria permanecer na mesma página? Nenhuma dessas opções é ideal, pois diferentes apps podem querer algo diferente em momentos diferentes. O app precisa poder expressar qual das 2 possibilidades deve acontecer.
(Outro exercício de raciocínio interessante: como você projetaria uma API baseada em parâmetros de widget para atualizar a página atual?)
Ser algo ou fazer algo?
Um app usa a API de um widget para pedir que ele faça coisas.
Podemos, de forma um tanto informal, categorizar as coisas que um app pede a um widget para fazer em 2 categorias:
Ser algo, ou fazer algo (às vezes chamados de level triggers e edge triggers, respectivamente).
Quando um app diz a um widget para ter uma certa cor ou, por exemplo, quando diz ao widget WebView para habilitar o JavaScript, eu penso nisso como um pedido de “ser algo”. Por exemplo, ser um widget com fundo vermelho. Para pedidos de “ser algo” existe um contrato especial entre o app e o widget: um pedido de “ser algo” vale para o widget até o próximo pedido diferente do app para o mesmo parâmetro. Voltando ao exemplo da cor, o widget não pode mudar sua propriedade de cor internamente, nem por qualquer outro mecanismo além do próximo pedido de “ser algo” do app. Então, depois que o app pede que o widget seja vermelho, o app sabe que o widget é vermelho (*) até pedir que ele seja outra cor.
Pedidos de “ser algo” se modelam bem como parâmetros de widget: construir um widget com um conjunto de parâmetros é a forma como o app pede que ele seja algo. Depois de construir um widget
Container(color: red), o app sabe que o contêiner é vermelho desde que não reconstrua o contêiner com um parâmetro diferente. Não há motivo para fazer o mesmo pedido de “ser algo” de novo, pois o widget já está garantido como o widget que cumpre o pedido anterior.
Pedidos de fazer algo são pedidos que não exigem que o widget mantenha as garantias descritas acima. Pedir a um widget WebView para mostrar uma URL específica pode ser modelado de forma adequada como um pedido de “fazer algo”. Não há problema se o usuário navegar para outra página, e a URL atual deixar de ser a última que o app pediu ao WebView para mostrar. O app não presume que, só porque pediu ao WebView para mostrar uma URL específica, ele ainda esteja mostrando essa URL.
Pedidos de “fazer algo” não se modelam bem como parâmetros de widget, porque o widget não consegue controlar quando e como ele é reconstruído; ele não consegue “reconstruir a si mesmo” com uma nova URL sempre que o usuário clica em um link.
Então, como criar uma API para pedidos de “fazer algo”? Até agora, o que mais funciona para mim é fazer chamadas imperativas. No exemplo da URL, isso significa ter um controller para o WebView e fazer uma chamada
webViewController.loadUrl(..). Isso mesmo: nem tudo precisa ser controlado por parâmetros de widget, e não há problema algum em usar controllers (aliás, o Flutter usa alguns controllers no próprio framework, como o
PageController, e o WebViewController no plugin
webview_flutter).
Existe uma decisão de compromisso a ser tomada
Tenha em mente que é possível obter a mesma funcionalidade de uma API de “fazer algo” com uma API de “ser algo”. Por exemplo, no caso da URL do WebView, podemos extrair o gerenciamento da propriedade “localização atual” para fora do widget: quando o usuário clica em um link, o widget invoca um manipulador de eventos que reconstrói o widget com a nova localização, deixando basicamente o gerenciamento de estado da “localização atual” para o app. Para o caso do “loadUrl”, gerenciar o estado da “localização atual” é bem complexo (imagine uma página web com vários iframes, cada um com uma posição de rolagem diferente. Um usuário clica em um link em um desses iframes; o novo estado que o app precisa passar ao WebView é longe de trivial e difícil de manter), então optamos por torná-la uma API de “fazer algo”.
Mas eu só quero mostrar uma URL específica
Continuando com o exemplo da URL do WebView, para o caso simples (e comum) em que o app só quer mostrar uma única página, sem links (talvez uma página de licença), pode ser interessante evitar exigir que o desenvolvedor gerencie uma instância de controller.
No webview_flutter, incluímos um parâmetro de widget initialUrl para essa finalidade. Na primeira vez que o widget é construído, o initialUrl é carregado. Alterações posteriores nesse valor são ignoradas ao reconstruir o widget.
Embora isso seja prático para casos simples, pode confundir desenvolvedores que tentam mudar o valor de initialUrl depois. (Veja esta issue no GitHub para uma ideia de quão confuso isso pode ser.)
Ao avaliar se deve adicionar um parâmetro initialFoo, tenha em mente que, embora eles sejam úteis para alguns casos simples, podem ser confusos para os desenvolvedores.
É isso que eu tinha para hoje. Descobri que separar esses diferentes tipos de pedidos a um widget (“ser algo” versus “fazer algo”) ajuda ao projetar APIs para widgets complexos (como um WebView ou um Map). Espero que isso ajude você também!
Isso não é exatamente correto; por exemplo, ao considerar widgets de animação implícita como AnimatedOpacity, o app não sabe que o widget está com opacidade ‘1.0’ depois de reconstruí-lo, mas ainda pode ser considerado um pedido de “ser algo”: ser o widget que anima a opacidade para 1.0 (esteja essa animação já concluída ou ainda em andamento).