Como fazer um widget de sobreposição flutuar sobre um widget de UI (possivelmente transformado)
Imagine que você tem um widget na UI do seu app e quer sobrepor um widget flutuante por cima dele.
Sobre o autor: Jose se formou recentemente na universidade e agora trabalha no Material, um design system que ajuda equipes a criar experiências digitais de alta qualidade. A equipe do Jose mantém a biblioteca material do Flutter.
Suponha que você tenha um widget na UI do seu app e queira sobrepor um widget flutuante em cima dele. Talvez esse widget esteja rotacionado ou tenha outras transformações aplicadas. Como transmitir as informações de posição e transformação do widget de UI para o widget correspondente no overlay?
Você pode fazer isso usando os widgets CompositedTransformTarget, CompositedTransformWidget, LayerLink, Overlay e OverlayEntry.
No Flutter, o overlay permite exibir elementos visuais sobre outros widgets, inserindo-os na pilha do overlay. Você insere um widget no overlay usando um OverlayEntry e usa Positioned e AnimatedPositioned para escolher onde a entrada fica posicionada dentro do overlay. Isso é útil quando você precisa que um item apareça sobre outro widget (de forma semelhante ao widget Stack), mas você pode usar esse widget em qualquer lugar sem precisar modificar toda a base de código.
Conforme descrito neste artigo, um programador precisa implementar um recurso de sugestão automática em um campo de texto de uma página existente. Ele poderia implementar esse recurso com um Stack, mas, como menciona o artigo, essa abordagem pode ser: intrusiva, trabalhosa, propensa a erros e simplesmente parece errada. Em vez de redesenhar toda a tela em um Stack, você pode usar o widget Overlay para adicionar esse efeito. Esse cenário acontece sempre que uma pessoa desenvolvedora precisa implementar um novo recurso em uma rota existente.
Usar um Overlay pode parecer intuitivo, mas pode ser difícil de implementar no Flutter. A entrada do overlay precisa ser inserida por meio de um método de callback. Além disso, você precisa manter uma referência à entrada do overlay, já que a remoção é feita usando essa referência, e não o context do overlay. Também, se você precisar que a posição e a transformação da entrada do overlay dependam de outro widget que não está no overlay, isso pode confundir. Isso acontece porque o context do MediaQuery do overlay é diferente do context normal. Você deve ter notado isso ao usar padding ou margin em um widget antes de fazer uma chamada ao Overlay. Felizmente, o Flutter já cuida desses detalhes para você.
Se uma entrada do overlay precisar seguir um ‘alvo’ que não está na pilha do overlay, você pode usar CompositedTransformTarget, CompositedTransformFollower e LayerLink para “colar” os widgets uns aos outros. Para isso, você precisa:
Envolver o widget no overlay com um CompositedTransformFollower.
O follower precisa ser um descendente de CompositedTransformTarget.
O widget alvo deve ser envolvido com um CompositedTransformTarget.
Uma instância de LayerLink une o follower e o alvo.
No GIF a seguir, o container azul não está no overlay, mas o container verde está. O container azul é filho de CompositedTransformTarget, e o container verde é filho de CompositedTransformFollower. Os dois estão ligados pela mesma instância de LayerLink. Observe que o widget verde do overlay conhece os limites do widget azul de UI, mesmo que o widget azul não esteja no overlay:

Experimente você mesmo usando esta instância do DartPad. O código de exemplo é o seguinte:
Código de Hans Muller
import 'package:flutter/material.dart';
void main() {
runApp(MaterialApp(home: Slide()));
}
class Indicator extends StatelessWidget {
Indicator({ Key key, this.link, this.offset }) : super(key: key);
final LayerLink link;
final Offset offset;
@override
Widget build(BuildContext context) {
return CompositedTransformFollower(
offset: offset,
link: link,
child: Container(
color: Colors.green,
),
);
}
}
class Slide extends StatefulWidget {
Slide({ Key key }) : super(key: key);
@override
_SlideState createState() => _SlideState();
}
class _SlideState extends State<Slide> {
final double indicatorWidth = 24.0;
final double indicatorHeight = 300.0;
final double slideHeight = 200.0;
final double slideWidth = 400.0;
final LayerLink layerLink = LayerLink();
OverlayEntry overlayEntry;
Offset indicatorOffset;
Offset getIndicatorOffset(Offset dragOffset) {
final double x = (dragOffset.dx - (indicatorWidth / 2.0)).clamp(0.0, slideWidth - indicatorWidth);
final double y = (slideHeight - indicatorHeight) / 2.0;
return Offset(x, y);
}
void showIndicator(DragStartDetails details) {
indicatorOffset = getIndicatorOffset(details.localPosition);
overlayEntry = OverlayEntry(
builder: (BuildContext context) {
return Positioned(
top: 0.0,
left: 0.0,
child: SizedBox(
width: indicatorWidth,
height: indicatorHeight,
child: Indicator(
offset: indicatorOffset,
link: layerLink
),
),
);
},
);
Overlay.of(context).insert(overlayEntry);
}
void updateIndicator(DragUpdateDetails details) {
indicatorOffset = getIndicatorOffset(details.localPosition);
overlayEntry.markNeedsBuild();
}
void hideIndicator(DragEndDetails details) {
overlayEntry.remove();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Overlay Indicator')),
body: Center(
child: CompositedTransformTarget(
link: layerLink,
child: Container(
width: slideWidth,
height: slideHeight,
color: Colors.blue.withOpacity(0.2),
child: GestureDetector(
onPanStart: showIndicator,
onPanUpdate: updateIndicator,
onPanEnd: hideIndicator,
),
),
),
),
);
}
}
Este exemplo mostra como usar esses widgets juntos. Para ver o verdadeiro poder deles, aplique uma Transformation ao CompositedTransformTarget. Você vai notar que o widget verde do overlay também é afetado por essa transformação, graças à LayerLink compartilhada entre eles.
No GIF a seguir, o container azul não está no overlay, mas o container verde está. Desta vez, o CompositedTransformTarget foi rotacionado. Como você pode ver, mesmo que o CompositeTransformFollower esteja na pilha do overlay, ele ainda sabe onde está o alvo e quaisquer transformações que foram aplicadas a ele.

Experimente você mesmo usando esta instância do DartPad. O código de exemplo é o seguinte:
Código de Hans Muller
import 'dart:math' as math;
import 'package:flutter/material.dart';
void main() {
runApp(MaterialApp(home: Slide()));
}
class Indicator extends StatelessWidget {
Indicator({ Key key, this.link, this.offset }) : super(key: key);
final LayerLink link;
final Offset offset;
@override
Widget build(BuildContext context) {
return CompositedTransformFollower(
offset: offset,
link: link,
child: Container(
color: Colors.green,
),
);
}
}
class Slide extends StatefulWidget {
Slide({ Key key }) : super(key: key);
@override
_SlideState createState() => _SlideState();
}
class _SlideState extends State<Slide> {
final double indicatorWidth = 24.0;
final double indicatorHeight = 300.0;
final double slideHeight = 200.0;
final double slideWidth = 400.0;
final LayerLink layerLink = LayerLink();
OverlayEntry overlayEntry;
Offset indicatorOffset;
Offset getIndicatorOffset(Offset dragOffset) {
final double x = (dragOffset.dx - (indicatorWidth / 2.0)).clamp(0.0, slideWidth - indicatorWidth);
final double y = (slideHeight - indicatorHeight) / 2.0;
return Offset(x, y);
}
void showIndicator(DragStartDetails details) {
indicatorOffset = getIndicatorOffset(details.localPosition);
overlayEntry = OverlayEntry(
builder: (BuildContext context) {
return Positioned(
top: 0.0,
left: 0.0,
child: SizedBox(
width: indicatorWidth,
height: indicatorHeight,
child: Indicator(
offset: indicatorOffset,
link: layerLink
),
),
);
},
);
Overlay.of(context).insert(overlayEntry);
}
void updateIndicator(DragUpdateDetails details) {
indicatorOffset = getIndicatorOffset(details.localPosition);
overlayEntry.markNeedsBuild();
}
void hideIndicator(DragEndDetails details) {
overlayEntry.remove();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Overlay Indicator')),
body: Transform.rotate(
angle: -math.pi / 12.0,
child: Center(
child: CompositedTransformTarget(
link: layerLink,
child: Container(
width: slideWidth,
height: slideHeight,
color: Colors.blue.withOpacity(0.2),
child: GestureDetector(
onPanStart: showIndicator,
onPanUpdate: updateIndicator,
onPanEnd: hideIndicator,
),
),
),
),
),
);
}
}
Conclusão
Ao implementar uma UI que faz widgets flutuarem sobre outros widgets, usar o overlay e ligar os widgets entre si é uma abordagem simples e poderosa. Neste artigo, você aprendeu a usar um LayerLink para colar esses widgets. Agora, vá em frente e crie sua UI incrível!
Para saber mais sobre o Jose, visite as páginas dele no GitHub, LinkedIn, YouTube e Instagram.