Decompondo widgets: Backdrop

Entenda a composição de widgets do Flutter examinando como o widget Backdrop do Material é construído.

Embora seja fácil criar widgets personalizados no Flutter, muitas vezes é útil examinar widgets existentes para entender melhor como compor widgets e criar outros mais complexos.

Hans Muller e Mary Xia criaram o Backdrop, um widget que implementa o componente Backdrop do Material, usado na Flutter Gallery, no curso da Udacity sobre Flutter e na palestra sobre Material Design com Flutter na I/O 2018. O Backdrop gerencia uma camada da frente que fica sobre uma camada de trás e pode ser aberta e fechada.

App Unit Converter, do curso da Udacity sobre Flutter
App Unit Converter, do curso da Udacity sobre Flutter

O Backdrop usa vários widgets do Flutter para isso: Stack, Expanded, LayoutBuilder, Animation, Tween e PositionedTransition. Ele serve como um bom exemplo de como compor widgets padrão do Flutter para criar algo mais complexo.

Extraí o código-fonte do Backdrop e escrevi alguns exemplos para demonstrar como ele funciona. O código revisado está disponível no GitHub, e recomendo que você passe alguns minutos experimentando e examinando o código antes de mergulhar na desconstrução abaixo.

Também trabalhei com ValueNotifier e ScopedModel para demonstrar algumas técnicas diferentes de gerenciamento de estado em apps Flutter.

Vamos explorar como esse widget funciona.

Backdrop

Backdrop é um StatefulWidget cujo state gerencia a posição e a animação da camada da frente. Vamos começar focando na função build() do Backdrop.

dart
AnimationController _controller;
​
Widget build(BuildContext context) {
  return LayoutBuilder(builder: (context, constraints) {
    final panelSize = constraints.biggest;
    final closedPercentage = widget.frontHeaderVisibleClosed
        ? (panelSize.height - widget.frontHeaderHeight) / panelSize.height
        : 1.0;
    final openPercentage = widget.frontPanelOpenHeight / panelSize.height;
​
final panelDetailsPosition = Tween<Offset>(
      begin: Offset(0.0, closedPercentage),
      end: Offset(0.0, openPercentage),
    ).animate(_controller.view);
​
return Container(
      child: Stack(
        children: <Widget>[
          widget.backLayer,
          SlideTransition(
            position: panelDetailsPosition,
            child: _BackdropPanel(
              child: widget.frontLayer,
              // panel configs
            ),
          ),
        ],
      ),
    );
  });
}

O widget é formado por uma camada da frente móvel, empilhada sobre uma camada de trás imóvel. O widget backLayer é colocado primeiro no Stack, para ficar por baixo, seguido por _BackdropPanel, que contém o frontLayer, envolvido em um SlideTransition. A versão original do Backdrop usava PositionTransition, mas isso foi alterado para evitar problemas de overflow ao ocultar completamente a camada da frente.

O LayoutBuilder determina quanto espaço vertical está disponível em tempo de execução, o que pode variar conforme o tamanho e a densidade da tela. Esse valor é então usado para calcular quanto da camada de trás fica coberta pela camada da frente quando aberta. O Tween define as posições aberta e fechada da camada da frente e usa o AnimationController para gerenciar o movimento.

O widget BackdropPanel implementa a camada da frente com uma Column contendo o cabeçalho, o divisor e o child. O child é envolvido em um Expanded para garantir que preencha o espaço disponível.

O widget Material decora o painel com uma sombra projetada e bordas chanfradas, usando BorderRadius.

dart
Widget build(BuildContext context) {
  return Material(
    elevation: 12.0,
    borderRadius: BorderRadius.only(
      topLeft: Radius.circular(16.0),
      topRight: Radius.circular(16.0),
    ),
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: <Widget>[
        GestureDetector(
          // ...
          child: Container(
            // ...
            height: titleHeight,
            child: title,
          ),
        ),
        Divider(height: 1.0,),
        Expanded(child: child,),
      ],
    ),
  );
}

O restante do código do Backdrop implementa principalmente o arrastar e as animações. O BackdropState tem um AnimationController em que o valor 1 abre a camada da frente e o valor 0 a fecha.

dart
_controller = AnimationController(
      duration: Duration(milliseconds: 300),
      // 0 hides the panel; 1 shows the panel
      value: (widget.panelVisible?.value ?? true) ? 1.0 : 0.0,
      vsync: this,
    );

O status do controller pode ser consultado para determinar o estado da camada:

dart
bool get _backdropPanelVisible =>
      _controller.status == AnimationStatus.completed ||
      _controller.status == AnimationStatus.forward;

fling() pode ser chamado para abrir ou fechar a camada:

dart
void _toggleBackdropPanelVisibility() => _controller.fling(
    velocity: _backdropPanelVisible
        ? -_kFlingVelocity
        : _kFlingVelocity
    );

Arrastar a camada é suportado por _handleDragUpdate(). _handleDragEnd() determina se a camada deve animar para abrir ou fechar, dependendo da direção, da velocidade e da posição do arraste. Essas funções são usadas pelo widget GestureDetector em BackdropPanel.

dart
void _handleDragUpdate(DragUpdateDetails details) {
  if (!_controller.isAnimating)
    _controller.value -= details.primaryDelta / _backdropHeight;
}
​
void _handleDragEnd(DragEndDetails details) {
  if (_controller.isAnimating ||
      _controller.status == AnimationStatus.completed) return;
​
final double flingVelocity =
      details.velocity.pixelsPerSecond.dy / _backdropHeight;
  if (flingVelocity < 0.0)
    _controller.fling(velocity: math.max(_kFlingVelocity,
      -flingVelocity));
  else if (flingVelocity > 0.0)
    _controller.fling(velocity: math.min(-_kFlingVelocity,
      -flingVelocity));
  else
    _controller.fling(
        velocity:
            _controller.value < 0.5
              ? -_kFlingVelocity
              : _kFlingVelocity);
}

ValueNotifier

Estendi a implementação original do Backdrop para receber um ValueNotifier, que o widget usa para acompanhar o estado aberto ou fechado do painel. ValueNotifiers oferecem um mecanismo pelo qual objetos podem escutar mudanças em um valor.

O ValueNotifier está sendo usado aqui como demonstração; um callback ou outra forma de gerenciamento de estado seria igualmente válida.

Um valor booleano, que representa o estado aberto/fechado da camada, é mantido pelo ValueNotifier. Os widgets interessados no estado do painel podem se inscrever no notifier e saber quando o painel é aberto ou fechado.

Primeiro, garantimos que o valor seja atualizado quando a camada for aberta ou fechada, escutando o status do AnimationController no Backdrop:

dart
if (widget.panelVisible != null) {
  _controller.addStatusListener((status) {
    if (status == AnimationStatus.completed)
      widget.panelVisible.value = true;
    else if (status == AnimationStatus.dismissed)
      widget.panelVisible.value = false;
  });

O Backdrop também escuta mudanças no valor, para que outros widgets possam disparar uma mudança no estado da camada da frente:

dart
void _subscribeToValueNotifier() {
  if (widget.panelVisible.value != _backdropPanelVisible)
    _toggleBackdropPanelVisibility();
}

Um efeito colateral sutil, mas importante, de usar e se inscrever em ValueNotifiers é que, quando o app passa por hot reload, os widgets podem ser reconstruídos e, se você tiver se inscrito no notifier em initState(), a inscrição deixa de ser válida. Para corrigir isso, implemente o método didWidgetUpdate() do StatefulWidget e adicione um novo listener:

dart
void didUpdateWidget(Backdrop oldWidget) {
  super.didUpdateWidget(oldWidget);
  oldWidget.panelVisible?.removeListener(_subscribeToValueNotifier);
  widget.panelVisible?.addListener(_subscribeToValueNotifier);
}

SimpleExample

O widget SimpleExample mostra como usar o Backdrop no caso mais simples. Clicar no botão altera o valor no ValueNotifier e faz a camada da frente abrir ou fechar. O notifier também é usado para alterar o widget Text na camada de trás.

Exemplo simples
Exemplo simples

ComplexExample

O ComplexExample demonstra como usar o Backdrop para mostrar conteúdos diferentes na camada da frente, e usa ScopedModel para acompanhar o estado do conteúdo. Primeiro, um Model é definido para gerenciar o estado da camada da frente.

dart
enum FrontPanels { tealPanel, limePanel }
​
class FrontPanelModel extends Model {
  FrontPanelModel(this._activePanel);
  FrontPanels _activePanel;
​
FrontPanels get activePanelType => _activePanel;
​
Widget get panelTitle => _activePanel == FrontPanels.tealPanel
      ? Text('Teal Panel')
      : Text('Lime Panel');
​
Widget get activePanel =>
      _activePanel == FrontPanels.tealPanel ? TealPanel() : LimePanel();
​
void activate(FrontPanels panel) {
    _activePanel = panel;
    notifyListeners();
  }
}

O model é colocado na árvore de widgets usando um widget ScopedModel, e os widgets ScopedModelDescendant dão acesso ao model. Eles são reconstruídos sempre que o model muda, a menos que a flag rebuildOnChange seja definida como false.

dart
Widget build(BuildContext context) => ScopedModel(
    model: FrontPanelModel(FrontPanels.firstPanel),
    child: Scaffold(body: SafeArea(child: Panels())));
...
Widget build(BuildContext context) {
  return ScopedModelDescendant<FrontPanelModel>(
    builder: (context, _, model) => Backdrop(
          frontPanel: model.activePanel,
          frontHeader: model.panelTitle,
          ...
        ),
  );
}
...
Center(
    child: ScopedModelDescendant<FrontPanelModel>(
        rebuildOnChange: false,
        builder: (context, _, model) => RaisedButton(
            child: Text('show first panel'),
            onPressed: () {
              model.activate(FrontPanels.firstPanel);
              widget.frontPanelOpen.value = true;
            },
        ))),

Os botões na camada de trás controlam qual widget é exibido na camada da frente.

Exemplo completo
Exemplo completo

Considerações finais

O que parece, à primeira vista, um widget complicado é, na verdade, uma coleção de widgets padrão do Flutter combinados, cada um emprestando sua funcionalidade ao todo. Esse é um dos recursos mais poderosos do Flutter: a capacidade de criar rapidamente UIs personalizadas e complexas a partir da caixa de ferramentas de widgets oferecida pela plataforma.

Confira o código-fonte completo no GitHub e, mais uma vez, obrigado a Hans e Mary, os criadores originais do Backdrop.

Mais do Flutter