Keys! Para que servem?

O parâmetro key pode ser encontrado praticamente em todos os construtores de widgets, mas o seu uso é menos comum.

O parâmetro key pode ser encontrado em praticamente todos os construtores de widgets, mas o uso dele é menos comum. As keys preservam o estado quando widgets são movidos na árvore de widgets. Na prática, isso significa que elas podem ser úteis para preservar a posição de rolagem do usuário ou manter o estado ao modificar uma coleção.

O artigo a seguir é adaptado do seguinte vídeo:

Watch on YouTube in a new tab: "When to Use Keys - Flutter Widgets 101 Ep. 4"

Se você prefere ouvir ou assistir em vez de ler, esse vídeo deve cobrir todo o mesmo conteúdo.

Os bastidores das Keys

Na maioria das vezes… você não precisa de keys! Geralmente, não há mal algum em adicioná-las, mas é desnecessário e só ocupa espaço à toa, assim como a palavra-chave new, ou declarar tipos tanto do lado direito quanto do lado esquerdo de uma nova variável (estou olhando para você, Map<Foo, Bar> aMap = Map<Foo, Bar>()). Mas, se você se pegar adicionando, removendo ou reordenando uma coleção de widgets do mesmo tipo que guardam algum estado, usar keys provavelmente estará no seu futuro!

Se você se pegar adicionando, removendo ou reordenando uma coleção de widgets do mesmo tipo que guardam algum estado, usar keys provavelmente estará no seu futuro.

Para ilustrar por que você precisa de keys ao modificar uma coleção de widgets, escrevi um app extremamente simples com dois widgets de cores aleatórias que trocam de lugar quando você toca em um botão:

No app na versão stateless, tenho dois Tiles stateless, cada um com uma cor gerada aleatoriamente, dentro de uma Row e de uma StatefulWidget chamada PositionedTiles para guardar a posição desses tiles. Quando toco no FloatingActionButton lá embaixo, ele troca corretamente a posição deles na lista:

dart
void main() => runApp(new MaterialApp(home: PositionedTiles()));
​
class PositionedTiles extends StatefulWidget {
 @override
 State<StatefulWidget> createState() => PositionedTilesState();
}
​
class PositionedTilesState extends State<PositionedTiles> {
 List<Widget> tiles = [
   StatelessColorfulTile(),
   StatelessColorfulTile(),
 ];
​
 @override
 Widget build(BuildContext context) {
   return Scaffold(
     body: Row(children: tiles),
     floatingActionButton: FloatingActionButton(
         child: Icon(Icons.sentiment_very_satisfied), onPressed: swapTiles),
   );
 }
​
 swapTiles() {
   setState(() {
     tiles.insert(1, tiles.removeAt(0));
   });
 }
}
​
class StatelessColorfulTile extends StatelessWidget {
 Color myColor = UniqueColorGenerator.getColor();
 @override
 Widget build(BuildContext context) {
   return Container(
       color: myColor, child: Padding(padding: EdgeInsets.all(70.0)));
 }
}

Mas, se tornarmos os ColorfulTiles stateful em vez de stateless e guardarmos a cor no estado, quando eu pressiono o botão parece que nada acontece.

dart
List<Widget> tiles = [
   StatefulColorfulTile(),
   StatefulColorfulTile(),
];
​
...
class StatefulColorfulTile extends StatefulWidget {
 @override
 ColorfulTileState createState() => ColorfulTileState();
}
​
class ColorfulTileState extends State<ColorfulTile> {
 Color myColor;
​
 @override
 void initState() {
   super.initState();
   myColor = UniqueColorGenerator.getColor();
 }
​
 @override
 Widget build(BuildContext context) {
   return Container(
       color: myColor,
       child: Padding(
         padding: EdgeInsets.all(70.0),
       ));
 }
}

Só um lembrete: o código mostrado acima está com bug, pois não mostra as cores trocando de lugar quando o usuário pressiona o botão “swap”. A correção é adicionar um parâmetro key aos widgets stateful, e então os widgets trocam de lugar como queremos:

dart
List<Widget> tiles = [
  StatefulColorfulTile(key: UniqueKey()), // Keys added here
  StatefulColorfulTile(key: UniqueKey()),
];
​
// ...
class StatefulColorfulTile extends StatefulWidget {
  StatefulColorfulTile({Key key}) : super(key: key);  // NEW CONSTRUCTOR
​
  @override
  ColorfulTileState createState() => ColorfulTileState();
}
​
class ColorfulTileState extends State<ColorfulTile> {
  Color myColor;
​
  @override
  void initState() {
    super.initState();
    myColor = UniqueColorGenerator.getColor();
  }
​
  @override
  Widget build(BuildContext context) {
    return Container(
      color: myColor,
      child: Padding(
        padding: EdgeInsets.all(70.0),
      ),
    );
  }
}

Mas isso só é necessário se você tiver widgets stateful na subárvore que está modificando. Se toda a subárvore de widgets da sua coleção for stateless, keys não são necessárias.

Pronto! Tecnicamente, isso é tudo o que você precisa saber para usar keys no Flutter. Mas, se quiser entender o porquê por trás de tudo…

O lado prático de por que as Keys às vezes são necessárias

Você ainda está aqui, hein? Então aproxime-se, para aprender a verdadeira natureza das árvores de Widget e Element e se tornar um Feiticeiro do Flutter! Muahahaha! Ha ha! Ha HA! Ahem, com licença.

Como você deve saber, por baixo dos panos, para cada widget o Flutter constrói um Element correspondente. Assim como ao construir uma árvore de Widget, o Flutter também constrói uma árvore de Element. O ElementTree é extremamente simples, guardando apenas informações sobre o tipo de cada widget e uma referência aos elementos filhos. Você pode pensar no ElementTree como um esqueleto do seu app Flutter. Ele mostra a estrutura do seu app, mas todas as informações adicionais podem ser consultadas por referência ao widget original.

O widget Row do exemplo acima guarda essencialmente um conjunto de slots ordenados para cada um dos seus filhos. Quando trocamos a ordem dos widgets Tile na Row, o Flutter percorre a ElementTree para verificar se a estrutura esquelética é a mesma.

Ele começa pelo RowElement e depois passa para os filhos dele. O ElementTree verifica se o novo widget é do mesmo tipo e tem a mesma key que o antigo e, se for, atualiza sua referência para o novo widget. Na versão stateless, os widgets não têm keys, então o Flutter apenas verifica o tipo. (Se isso parece muita informação de uma vez, assista à animação acima.)

A estrutura subjacente da árvore Element para widgets stateful é um pouco diferente. Há widgets e Elements como antes, mas também há um par de objetos de estado junto com eles, e as informações de cor são guardadas ali, e não nos próprios widgets.

No caso stateful Tile sem keys, quando trocamos a ordem dos dois widgets, o Flutter percorre a ElementTree, verifica o tipo do RowWidget e atualiza a referência. Depois, o TileElement verifica se o widget correspondente é do mesmo tipo (TileWidget) e é, então atualiza a referência. O mesmo acontece com o segundo filho. Como o Flutter usa a ElementTree e o estado correspondente para determinar o que realmente exibir no seu dispositivo, do nosso ponto de vista parece que seus widgets não trocaram de lugar corretamente!

Na versão corrigida, com o Tiles stateful, adicionei propriedades key aos widgets. Agora, se trocarmos os widgets, os Row correspondem como antes, mas a key do Tile Element não bate com a key do Tile Widget correspondente. Isso faz o Flutter desativar esses elementos e remover as referências aos Tile Elements na árvore de elementos, começando pelo primeiro que não bate.

Em seguida, o Flutter procura entre os filhos não correspondentes do Row um elemento com a key correta. Ele encontra uma correspondência e atualiza sua referência para o widget correspondente. Depois, o Flutter faz o mesmo com o segundo filho. Agora o Flutter exibe o que esperamos, com os widgets trocando de lugar e atualizando suas cores quando eu pressiono o botão.

Então, resumindo: chaves são úteis se você estiver modificando a ordem ou o número de widgets com estado em uma coleção. Para fins de ilustração, guardei a cor como estado neste exemplo. Muitas vezes, porém, o estado é bem mais sutil. Animações em execução, dados que o usuário digitou e a posição da rolagem envolvem estado.

Onde eu as coloco?

Resposta curta: se você precisar adicionar chaves ao seu app, adicione-as no topo da subárvore de widgets com o estado que você precisa preservar.

Um erro comum que já vi é as pessoas acharem que só precisam colocar uma chave no primeiro widget com estado, mas há dragões por aí. Não acredita em mim? Para mostrar que tipo de problema podemos causar, envolvi meus widgets colorfulTile com widgets de padding, mas deixei as chaves nos tiles.

dart
void main() => runApp(new MaterialApp(home: PositionedTiles()));
​
class PositionedTiles extends StatefulWidget {
  @override
  State<StatefulWidget> createState() => PositionedTilesState();
}
​
class PositionedTilesState extends State<PositionedTiles> {
  // Stateful tiles now wrapped in padding (a stateless widget) to increase height
  // of widget tree and show why keys are needed at the Padding level.
  List<Widget> tiles = [
    Padding(
      padding: const EdgeInsets.all(8.0),
      child: StatefulColorfulTile(key: UniqueKey()),
    ),
    Padding(
      padding: const EdgeInsets.all(8.0),
      child: StatefulColorfulTile(key: UniqueKey()),
    ),
  ];
​
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Row(children: tiles),
      floatingActionButton: FloatingActionButton(
        child: Icon(Icons.sentiment_very_satisfied),
        onPressed: swapTiles,
      ),
    );
  }
​
  swapTiles() {
    setState(() {
      tiles.insert(1, tiles.removeAt(0));
    });
  }
}
​
class StatefulColorfulTile extends StatefulWidget {
  StatefulColorfulTile({Key key}) : super(key: key);
​
  @override
  ColorfulTileState createState() => ColorfulTileState();
}
​
class ColorfulTileState extends State<ColorfulTile> {
  Color myColor;
​
  @override
  void initState() {
    super.initState();
    myColor = UniqueColorGenerator.getColor();
  }
​
  @override
  Widget build(BuildContext context) {
    return Container(
      color: myColor,
      child: Padding(
        padding: EdgeInsets.all(70.0),
      ),
    );
  }
}

Agora, quando clico no botão, os Tiles mudam para cores aleatórias completamente diferentes!

Veja como ficam a WidgetTree e a ElementTree com os widgets de padding adicionados:

Quando trocamos as posições dos filhos, o algoritmo de correspondência entre elementos e widgets do Flutter analisa um nível da árvore por vez. O diagrama deixa em cinza os filhos dos filhos, para que possamos nos concentrar em um nível por vez. Nesse primeiro nível de filhos, com os elementos Padding, tudo se encaixa corretamente.

As chaves que estamos usando neste exemplo são LocalKeys. Isso significa que, ao associar widgets a elementos, o Flutter só procura correspondências de chave dentro de um determinado nível da árvore.

Como ele não consegue encontrar um elemento Tile nesse nível com esse valor de chave, cria um novo e inicializa um novo estado, neste caso, deixando o widget laranja!

Se adicionarmos chaves no nível dos widgets de padding:

dart
void main() => runApp(new MaterialApp(home: PositionedTiles()));
​
class PositionedTiles extends StatefulWidget {
  @override
  State<StatefulWidget> createState() => PositionedTilesState();
}
​
class PositionedTilesState extends State<PositionedTiles> {
  List<Widget> tiles = [
    Padding(
      // Place the keys at the *top* of the tree of the items in the collection.
      key: UniqueKey(),
      padding: const EdgeInsets.all(8.0),
      child: StatefulColorfulTile(),
    ),
    Padding(
      key: UniqueKey(),
      padding: const EdgeInsets.all(8.0),
      child: StatefulColorfulTile(),
    ),
  ];
​
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Row(children: tiles),
      floatingActionButton: FloatingActionButton(
        child: Icon(Icons.sentiment_very_satisfied),
        onPressed: swapTiles,
      ),
    );
  }
​
  swapTiles() {
    setState(() {
      tiles.insert(1, tiles.removeAt(0));
    });
  }
}
​
class StatefulColorfulTile extends StatefulWidget {
  StatefulColorfulTile({Key key}) : super(key: key);
​
  @override
  ColorfulTileState createState() => ColorfulTileState();
}
​
class ColorfulTileState extends State<ColorfulTile> {
  Color myColor;
​
  @override
  void initState() {
    super.initState();
    myColor = UniqueColorGenerator.getColor();
  }
​
  @override
  Widget build(BuildContext context) {
    return Container(
      color: myColor,
      child: Padding(
        padding: EdgeInsets.all(70.0),
      ),
    );
  }
}

O Flutter percebe o problema e atualiza as conexões corretamente, assim como fez no exemplo anterior. A ordem foi restaurada no universo.

Que tipo de Key devo usar?

Os responsáveis pelas APIs do Flutter nos deram uma variedade de classes Key para escolher. O tipo de chave que você deve usar depende da característica distintiva dos itens que precisam de chaves. Dê uma olhada nas informações que você armazena nesses widgets. Aqui vou falar sobre quatro tipos diferentes de chaves: ValueKey, ObjectKey, UniqueKey e GlobalKey.

Considere o seguinte app de lista de tarefas¹, em que você pode reordenar os itens da sua lista de tarefas por prioridade e depois removê-los quando terminar.

Nesse cenário, você pode esperar que o texto de um item da lista de tarefas seja constante e único. Se for o caso, ele provavelmente é um bom candidato para uma ValueKey, em que o texto é o “valor”.

dart
return TodoItem(
  key: ValueKey(todo.task),
  todo: todo,
  onDismissed: (direction) => _removeTodo(context, todo),
);

Em um cenário diferente, talvez você tenha um app de agenda de contatos que lista informações sobre cada usuário. Nesse caso, cada widget filho armazena uma combinação de dados mais complexa. Qualquer um dos campos individuais, como o primeiro nome ou a data de aniversário, pode ser igual ao de outro registro, mas a combinação é única. Nesse cenário, uma ObjectKey provavelmente é a mais adequada.

Se você tiver vários widgets na sua coleção com o mesmo valor, ou se quiser garantir que cada widget seja realmente distinto de todos os outros, pode usar UniqueKey. Usei UniqueKey no exemplo do app de troca de cores, porque não tínhamos outros dados constantes armazenados nos nossos tiles, e não sabemos qual será a cor quando construímos o widget. Cuidado com UniqueKey, porém! Se você construir uma nova UniqueKey dentro de um método build, o widget que usa essa chave vai receber uma chave diferente, única, toda vez que o método build for executado de novo. Isso vai eliminar qualquer benefício de usar chaves!

Da mesma forma, algo que você definitivamente não deve fazer é usar um número aleatório como chave. Toda vez que um widget é construído, um novo número aleatório será gerado e você perderá a consistência entre os quadros. Aí é melhor nem ter usado chaves!

**PageStorageKey**s são chaves especializadas que armazenam a posição de rolagem do usuário para que o app possa preservá-la para depois.

GlobalKeys têm dois usos: eles permitem que widgets mudem de pai em qualquer lugar do seu app sem perder o estado, ou podem ser usados para acessar informações sobre outro widget em uma parte completamente diferente da árvore de widgets. Um exemplo do primeiro cenário seria se você quisesse mostrar o mesmo widget em duas telas diferentes, mantendo todo o mesmo estado; nesse caso, você iria querer usar um GlobalKey. No segundo cenário, talvez você queira validar uma senha, mas não queira compartilhar essa informação de estado com outros widgets da árvore. GlobalKeys também pode ser útil para testes, usando uma chave para acessar um widget específico e consultar informações sobre o seu estado.

Muitas vezes (mas nem sempre!), GlobalKeys se parecem um pouco com variáveis globais. Geralmente existe uma forma melhor de buscar esse estado, usando InheritedWidgets, ou algo como Redux ou o padrão BLoC.

Resumo rápido

Em resumo, use chaves quando quiser preservar o estado entre árvores de widgets. Isso acontece com mais frequência quando você está modificando uma coleção de widgets do mesmo tipo, como em uma lista. Coloque a chave no topo da árvore de widgets que você quer preservar e escolha o tipo de chave com base nos dados que você armazena no widget.

Parabéns, você já está bem a caminho de se tornar um Mago do Flutter! Ah, eu disse mago? Quis dizer codificador, no sentido de alguém que escreve o código-fonte de apps… o que também é quase tão bom. …Quase. ⚡

[1] Código do app de tarefas inspirado em https://github.com/brianegan/flutter_architecture_samples/tree/master/example/vanilla

Mais do Flutter