Restrições e ordem dos modificadores

No Compose, é possível encadear vários modificadores para mudar a aparência de um elemento combinável. Essas cadeias de modificadores podem afetar as restrições transmitidas aos elementos combináveis, que definem os limites de largura e altura.

Esta página descreve como os modificadores encadeados afetam as restrições e, por sua vez, a medição e o posicionamento dos elementos combináveis.

Modificadores na árvore de IU

Para entender como os modificadores se influenciam, é útil visualizar como eles aparecem na árvore de IU, que é gerada durante a fase de composição. Para mais informações, consulte a seção Composição.

Na árvore de IU, é possível visualizar os modificadores como nós de wrapper para os nós de layout:

Código para elementos combináveis e modificadores, além da representação visual deles como uma árvore de UI.
Figura 1. Modificadores que envolvem nós de layout na árvore de IU.

Adicionar mais de um modificador a um elemento combinável cria uma cadeia de modificadores. Ao encadear vários modificadores, cada nó de modificador envolve o restante da cadeia e o nó de layout dentro. Por exemplo, ao encadear um clip e um size modificador, o nó de modificador clip envolve o nó de modificador size, que envolve o nó de layout Image.

Na fase de layout, o algoritmo que percorre a árvore permanece o mesmo, mas cada nó de modificador também é visitado. Dessa forma, um modificador pode mudar os requisitos de tamanho e o posicionamento do modificador ou do nó de layout que ele envolve.

Como mostrado na Figura 2, a implementação dos elementos combináveis Image e Text consiste em uma cadeia de modificadores que envolvem um único nó de layout.

As implementações de Row e Column são nós de layout que descrevem como dispor os filhos.

A estrutura de árvore de antes, mas agora cada nó é apenas um layout simples, com muitos nós de encapsulamento de modificadores ao redor.
Figura 2. A mesma estrutura de árvore da Figura 1, mas com elementos combináveis na árvore de IU visualizados como cadeias de modificadores.

Para resumir:

  • Os modificadores envolvem um único modificador ou nó de layout.
  • Os nós de layout podem dispor vários nós filhos.

As seções a seguir descrevem como usar esse modelo mental para raciocinar sobre o encadeamento de modificadores e como ele influencia o tamanho dos elementos combináveis.

Restrições na fase de layout

A fase de layout segue um algoritmo de três etapas para encontrar a largura, a altura e a coordenada x, y de cada nó de layout:

  1. Medir filhos: um nó mede os filhos, se houver.
  2. Decidir o próprio tamanho: com base nessas medições, um nó decide o próprio tamanho.
  3. Posicionar filhos: cada nó filho é posicionado em relação à posição de um nó.

Constraints ajudam a encontrar os tamanhos certos para os nós durante as duas primeiras etapas do algoritmo. As restrições definem os limites mínimo e máximo para a largura e a altura de um nó. Quando o nó decide o tamanho, o tamanho medido precisa estar dentro desse intervalo.

Tipos de restrições

Uma restrição pode ser uma das seguintes:

  • Limitada: o nó tem uma largura e altura máximas e mínimas.
Restrições delimitadas de tamanhos diferentes em um contêiner.
Figura 3. Restrições limitadas.
  • Ilimitada: o nó não está restrito a nenhum tamanho. Os limites máximos de largura e altura são definidos como infinitos.
Restrições sem limites com largura e altura definidas como infinito. As restrições vão além do contêiner.
Figura 4. Restrições ilimitadas.
  • Exata: o nó precisa seguir um requisito de tamanho exato. Os limites mínimo e máximo são definidos com o mesmo valor.
Restrições exatas que obedecem a um requisito de tamanho exato dentro do contêiner.
Figura 5. Restrições exatas.
  • Combinação: o nó segue uma combinação dos tipos de restrição anteriores. Por exemplo, uma restrição pode limitar a largura, permitindo uma altura máxima ilimitada, ou definir uma largura exata, mas fornecer uma altura limitada.
Dois contêineres que mostram combinações de restrições limitadas e ilimitadas e larguras e alturas exatas.
Figura 6. Combinações de restrições limitadas e ilimitadas e larguras e alturas exatas.

A próxima seção descreve como essas restrições são transmitidas de um pai para um filho.

Como as restrições são transmitidas do pai para o filho

Durante a primeira etapa do algoritmo descrito em Restrições na fase de layout, as restrições são transmitidas do pai para o filho na árvore de IU.

Quando um nó pai mede os filhos, ele fornece essas restrições a cada filho para informar o tamanho permitido. Em seguida, ao decidir o próprio tamanho, ele também adere às restrições transmitidas pelos pais.

Em um nível alto, o algoritmo funciona da seguinte maneira:

  1. Para decidir o tamanho que realmente quer ocupar, o nó raiz na árvore de IU mede os filhos e encaminha as mesmas restrições para o primeiro filho.
  2. Se o filho for um modificador que não afeta a medição, ele encaminha as restrições para o próximo modificador. As restrições são transmitidas pela cadeia de modificadores como estão, a menos que um modificador que afete a medição seja alcançado. As restrições são redimensionadas de acordo.
  3. Quando um nó é alcançado e não tem filhos (chamado de "nó folha"), ele decide o tamanho com base nas restrições transmitidas e retorna esse tamanho resolvido para o pai.
  4. O pai adapta as restrições com base nas medições do filho e chama o próximo filho com essas restrições ajustadas.
  5. Depois que todos os filhos de um pai são medidos, o nó pai decide o próprio tamanho e comunica isso ao pai.
  6. Dessa forma, toda a árvore é percorrida em profundidade. Por fim, todos os nós decidem os tamanhos, e a etapa de medição é concluída.

Para um exemplo detalhado, assista ao Constraints and modifier order vídeo (link em inglês).

Modificadores que afetam as restrições

Na seção anterior, você aprendeu que alguns modificadores podem afetar o tamanho da restrição. As seções a seguir descrevem modificadores específicos que afetam as restrições.

O modificador size

O size modificador declara o tamanho preferencial do conteúdo.

Por exemplo, a árvore de IU a seguir precisa ser renderizada em um contêiner de 300dp por 200dp. As restrições são limitadas, permitindo larguras entre 100dp e 300dp e alturas entre 100dp e 200dp:

Uma parte de uma árvore de interface com o modificador de tamanho envolvendo um nó de layout e a representação das restrições limitadas definidas pelo modificador de tamanho em um contêiner.
Figura 7. Restrições limitadas na árvore de IU e representação em um contêiner.

O modificador size adapta as restrições recebidas para corresponder ao valor transmitido a ele. Neste exemplo, o valor é 150dp:

Igual à Figura 7, exceto que o modificador de tamanho adapta as restrições recebidas para corresponder ao valor transmitido a ele.
Figura 8. O modificador size ajustando as restrições para 150dp.

Se a largura e a altura forem menores que o limite de restrição menor ou maiores que o limite de restrição maior, o modificador vai corresponder às restrições transmitidas o mais próximo possível, sem deixar de aderir às restrições transmitidas:

Duas árvores de interface e as representações correspondentes em contêineres. No primeiro, o modificador de tamanho aceita as restrições recebidas. No segundo, ele se adapta às restrições muito grandes o mais próximo possível, resultando em restrições que preenchem o contêiner.
Figura 9. O modificador size aderindo à restrição transmitida o mais próximo possível.

O encadeamento de vários modificadores size não funciona. O primeiro modificador size define as restrições mínima e máxima para um valor fixo. Mesmo que o segundo modificador de tamanho solicite um tamanho menor ou maior, ele ainda precisa aderir aos limites exatos transmitidos. Portanto, ele não vai substituir esses valores:

Uma cadeia de dois modificadores de tamanho na árvore da interface e sua representação em um contêiner, que é o resultado do primeiro valor transmitido e não do segundo.
Figura 10. Uma cadeia de dois modificadores size, em que o segundo valor transmitido (50dp) não substitui o primeiro valor (100dp).

O modificador requiredSize

Use o modificador requiredSize em vez de size se precisar que o seu nó substitua as restrições recebidas. O modificador requiredSize substitui as restrições recebidas e transmite o tamanho especificado como limites exatos.

Quando o tamanho é transmitido de volta para a árvore, o nó filho é centralizado no espaço disponível:

O modificador size e requiredSize encadeados em uma árvore de UI e a representação correspondente em um contêiner. As restrições do modificador requiredSize substituem as restrições do modificador de tamanho.
Figura 11. O modificador requiredSize substituindo as restrições recebidas do modificador size.

Os modificadores width e height

O modificador size adapta a largura e a altura das restrições. Com o modificador width, é possível definir uma largura fixa, mas deixar a altura indefinida. Da mesma forma, com o modificador height, é possível definir uma altura fixa, mas deixar a largura indefinida:

Duas árvores de interface, uma com o modificador de largura e a representação do contêiner, e a outra com o modificador de altura e a representação.
Figura 12. O modificador width e o modificador height definindo uma largura e altura fixas, respectivamente.

O modificador sizeIn

O modificador sizeIn permite definir restrições mínimas e máximas exatas para largura e altura. Use o modificador sizeIn se precisar de um controle refinado sobre as restrições.

Uma árvore de interface com o modificador sizeIn com larguras e alturas mínimas e máximas definidas, e sua representação em um contêiner.
Figura 13. O modificador sizeIn com minWidth, maxWidth, minHeight e maxHeight definidos.

Exemplos

Esta seção mostra e explica a saída de vários snippets de código com modificadores encadeados.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .fillMaxSize()
        .size(50.dp)
)
ConstraintsModifiersSnippets.kt

Este snippet produz a seguinte saída:

Um quadrado azul que preenche o contêiner principal.
Figura 14. O Image preenche o tamanho máximo como resultado da cadeia de modificadores.
  • O modificador fillMaxSize muda as restrições para definir a largura e a altura mínimas para o valor máximo: 300dp de largura e 200dp de altura.
  • Embora o modificador size queira usar um tamanho de 50dp, ele ainda precisa aderir às restrições mínimas recebidas. Portanto, o modificador size também vai gerar os limites de restrição exatos de 300 por 200, ignorando o valor fornecido no modificador size.
  • A Image segue esses limites e informa um tamanho de 300 por 200, que é transmitido por toda a árvore.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .fillMaxSize()
        .wrapContentSize()
        .size(50.dp)
)
ConstraintsModifiersSnippets.kt

Este snippet produz a seguinte saída:

Um pequeno quadrado azul centralizado no contêiner pai.
Figura 15. O Image é centralizado e dimensionado para 50dp.
  • O modificador fillMaxSize adapta as restrições para definir a largura e a altura mínimas para o valor máximo: 300dp de largura e 200dp de altura.
  • O modificador wrapContentSize redefine as restrições mínimas. Portanto, embora fillMaxSize tenha resultado em restrições fixas, wrapContentSize redefine as restrições limitadas. O nó a seguir agora pode ocupar todo o espaço novamente ou ser menor que todo o espaço.
  • O modificador size define as restrições para limites mínimos e máximos de 50.
  • A Image é resolvida para um tamanho de 50 por 50, e o modificador size encaminha isso.
  • O modificador wrapContentSize tem uma propriedade especial. Ele pega o filho e o coloca no centro dos limites mínimos disponíveis que foram transmitidos a ele. O tamanho que ele comunica aos pais é igual aos limites mínimos que foram transmitidos a ele.

Ao combinar apenas três modificadores, é possível definir um tamanho para o elemento combinável e centralizá-lo no pai.

Image(
    painterResource(R.drawable.hero),
    contentDescription = null,
    Modifier
        .clip(CircleShape)
        .padding(10.dp)
        .size(100.dp)
)
ConstraintsModifiersSnippets.kt

Este snippet produz a seguinte saída:

Uma forma circular que foi cortada incorretamente devido à ordem dos modificadores.
Figura 16. Uma forma cortada incorretamente devido à ordem do modificador order.
  • O modificador clip não muda as restrições.
  • O modificador padding diminui as restrições máximas.
  • O modificador size define todas as restrições como 100dp.
  • A Image adere a essas restrições e informa um tamanho de 100dp por 100dp.
  • O modificador padding adiciona 10dp em todos os lados ao tamanho informado pela Image. Portanto, o layout com padding informa uma largura e altura de 120dp.
  • Agora, na fase de desenho, o modificador clip atua em uma tela de 120dp por 120dp. Ele cria uma máscara de círculo desse tamanho.
  • O modificador padding insere o conteúdo em 10dp em todos os lados, o que diminui o tamanho da tela para a Image para 100dp por 100dp.
  • A Image é desenhada nessa tela menor. A imagem é cortada com base no círculo original de 120dp. Portanto, a saída é um resultado não redondo.
Anterior
Conceitos básicos de layout
Avançar
Modificadores personalizados