Transições de elementos compartilhados no Compose

As transições de elementos compartilhados são uma maneira perfeita de fazer a transição entre elementos combináveis que têm conteúdo consistente entre eles. Elas são usadas com frequência para navegação, permitindo que você conecte visualmente diferentes telas à medida que um usuário navega entre elas.

Por exemplo, no vídeo a seguir, a imagem e o título do lanche são compartilhados da página de informações do produto para a página de detalhes.

Figura 1. Demonstração do elemento compartilhado do Jetsnack

No Compose, há algumas APIs de alto nível que ajudam a criar elementos compartilhados:

• SharedTransitionLayout: o layout mais externo necessário para implementar transições de elementos compartilhados. Ela fornece um SharedTransitionScope. Os elementos combináveis precisam estar em um SharedTransitionScope para usar os modificadores de elementos compartilhados.
• Modifier.sharedElement(): o modificador que sinaliza para o SharedTransitionScope o elemento combinável que precisa ser combinado com outro elemento combinável.
• Modifier.sharedBounds(): o modificador que sinaliza para o SharedTransitionScope que os limites desse elemento combinável precisam ser usados como os limites do contêiner em que a transição precisa ocorrer. Diferente de sharedElement(), sharedBounds() foi projetado para conteúdos visualmente diferentes.

Um conceito importante ao criar elementos compartilhados no Compose é como eles funcionam com sobreposições e cortes. Consulte a seção Recortes e sobreposições para saber mais sobre esse assunto importante.

Experimental: o suporte a elementos compartilhados está disponível no Compose 1.7.0 e é experimental. As APIs podem mudar no futuro. Registre bugs no Issue Tracker.

Uso básico

A transição a seguir será criada nesta seção, passando do item "lista" menor para o item detalhado maior:

Figura 2. Exemplo básico de transição de elemento compartilhado entre dois elementos combináveis.

A melhor maneira de usar Modifier.sharedElement() é em conjunto com AnimatedContent, AnimatedVisibility ou NavHost, porque ele gerencia a transição entre elementos combináveis automaticamente.

O ponto de partida é um AnimatedContent básico que tem um MainContent e um DetailsContent combináveis antes de adicionar elementos compartilhados:

Figura 3. Iniciando AnimatedContent sem transições de elementos compartilhados.

1. Para animar os elementos compartilhados entre os dois layouts, circule o elemento combinável AnimatedContent com SharedTransitionLayout. Os escopos de SharedTransitionLayout e AnimatedContent são transmitidos para MainContent e DetailsContent:

   var showDetails by remember {
       mutableStateOf(false)
   }
   SharedTransitionLayout {
       AnimatedContent(
           showDetails,
           label = "basic_transition"
       ) { targetState ->
           if (!targetState) {
               MainContent(
                   onShowDetails = {
                       showDetails = true
                   },
                   animatedVisibilityScope = this@AnimatedContent,
                   sharedTransitionScope = this@SharedTransitionLayout
               )
           } else {
               DetailsContent(
                   onBack = {
                       showDetails = false
                   },
                   animatedVisibilityScope = this@AnimatedContent,
                   sharedTransitionScope = this@SharedTransitionLayout
               )
           }
       }
   }
   BasicSharedElementSnippets.kt

2. Adicione Modifier.sharedElement() à cadeia de modificadores combináveis nos dois elementos combináveis correspondentes. Crie um objeto SharedContentState e lembre-se dele com rememberSharedContentState(). O objeto SharedContentState está armazenando a chave exclusiva que determina os elementos compartilhados. Forneça uma chave exclusiva para identificar o conteúdo e use rememberSharedContentState() para que o item seja lembrado. O AnimatedContentScope é transmitido ao modificador, que é usado para coordenar a animação.

   @Composable
   private fun MainContent(
       onShowDetails: () -> Unit,
       modifier: Modifier = Modifier,
       sharedTransitionScope: SharedTransitionScope,
       animatedVisibilityScope: AnimatedVisibilityScope
   ) {
       Row(
           // ...
       ) {
           with(sharedTransitionScope) {
               Image(
                   painter = painterResource(id = R.drawable.cupcake),
                   contentDescription = "Cupcake",
                   modifier = Modifier
                       .sharedElement(
                           rememberSharedContentState(key = "image"),
                           animatedVisibilityScope = animatedVisibilityScope
                       )
                       .size(100.dp)
                       .clip(CircleShape),
                   contentScale = ContentScale.Crop
               )
               // ...
           }
       }
   }
   
   @Composable
   private fun DetailsContent(
       modifier: Modifier = Modifier,
       onBack: () -> Unit,
       sharedTransitionScope: SharedTransitionScope,
       animatedVisibilityScope: AnimatedVisibilityScope
   ) {
       Column(
           // ...
       ) {
           with(sharedTransitionScope) {
               Image(
                   painter = painterResource(id = R.drawable.cupcake),
                   contentDescription = "Cupcake",
                   modifier = Modifier
                       .sharedElement(
                           rememberSharedContentState(key = "image"),
                           animatedVisibilityScope = animatedVisibilityScope
                       )
                       .size(200.dp)
                       .clip(CircleShape),
                   contentScale = ContentScale.Crop
               )
               // ...
           }
       }
   }
   BasicSharedElementSnippets.kt

Para saber se uma correspondência de elemento compartilhado ocorreu, extraia rememberSharedContentState() em uma variável e consulte isMatchFound.

Importante: a ordem de onde esse modificador é colocado na cadeia é importante. Coloque tudo que você não quer compartilhar antes de sharedElement() na cadeia de modificadores.

O que resulta na seguinte animação automática:

Figura 4. Exemplo básico de transição de elemento compartilhado entre dois elementos combináveis.

A cor do plano de fundo e o tamanho de todo o contêiner ainda usam as configurações padrão de AnimatedContent.

Limites compartilhados versus elemento compartilhado

Modifier.sharedBounds() é semelhante a Modifier.sharedElement(). No entanto, os modificadores são diferentes nos seguintes aspectos:

• sharedBounds() é para conteúdo visualmente diferente, mas que precisa compartilhar a mesma área entre os estados, enquanto sharedElement() espera que o conteúdo seja o mesmo.
• Com sharedBounds(), o conteúdo que entra e sai da tela fica visível durante a transição entre os dois estados, enquanto com sharedElement() apenas o conteúdo de destino é renderizado nos limites de transformação. Modifier.sharedBounds() tem os parâmetros enter e exit para especificar como o conteúdo precisa fazer a transição, de maneira semelhante a como AnimatedContent funciona.
• O caso de uso mais comum de sharedBounds() é o padrão de transformação de contêiner, enquanto para sharedElement(), o caso de uso de exemplo é uma transição principal.
• Ao usar elementos combináveis Text, é preferível usar sharedBounds() para oferecer suporte a mudanças de fonte, como a transição entre itálico e negrito ou mudanças de cor.

No exemplo anterior, adicionar Modifier.sharedBounds() a Row e Column nos dois cenários diferentes nos permite compartilhar os limites dos dois e realizar a animação de transição, permitindo que eles cresçam entre si:

@Composable
private fun MainContent(
    onShowDetails: () -> Unit,
    modifier: Modifier = Modifier,
    sharedTransitionScope: SharedTransitionScope,
    animatedVisibilityScope: AnimatedVisibilityScope
) {
    with(sharedTransitionScope) {
        Row(
            modifier = Modifier
                .padding(8.dp)
                .sharedBounds(
                    rememberSharedContentState(key = "bounds"),
                    animatedVisibilityScope = animatedVisibilityScope,
                    enter = fadeIn(),
                    exit = fadeOut(),
                    resizeMode = SharedTransitionScope.ResizeMode.ScaleToBounds()
                )
                // ...
        ) {
            // ...
        }
    }
}

@Composable
private fun DetailsContent(
    modifier: Modifier = Modifier,
    onBack: () -> Unit,
    sharedTransitionScope: SharedTransitionScope,
    animatedVisibilityScope: AnimatedVisibilityScope
) {
    with(sharedTransitionScope) {
        Column(
            modifier = Modifier
                .padding(top = 200.dp, start = 16.dp, end = 16.dp)
                .sharedBounds(
                    rememberSharedContentState(key = "bounds"),
                    animatedVisibilityScope = animatedVisibilityScope,
                    enter = fadeIn(),
                    exit = fadeOut(),
                    resizeMode = SharedTransitionScope.ResizeMode.ScaleToBounds()
                )
                // ...

        ) {
            // ...
        }
    }
}
SharedBoundsSnippets.kt

Figura 5. Limites compartilhados entre dois elementos combináveis.

Entender escopos

Para usar Modifier.sharedElement(), o elemento combinável precisa estar em um SharedTransitionScope. O elemento combinável SharedTransitionLayout fornece o SharedTransitionScope. Posicione o mesmo ponto de nível superior da hierarquia de IU que contém os elementos que você quer compartilhar.

Geralmente, os elementos combináveis também precisam ser colocados dentro de um AnimatedVisibilityScope. Isso geralmente é fornecido usando AnimatedContent para alternar entre elementos combináveis ou ao usar AnimatedVisibility diretamente, ou pela função combinável NavHost, a menos que você gerencie a visibilidade manualmente. Para usar vários escopos, salve os escopos necessários em um CompositionLocal, use recebedores de contexto no Kotlin ou transmita os escopos como parâmetros para suas funções.

Use CompositionLocals no cenário em que você tem vários escopos para acompanhar ou uma hierarquia profundamente aninhada. Um CompositionLocal permite escolher os escopos exatos que serão salvos e usados. Por outro lado, quando você usa receptores de contexto, outros layouts na sua hierarquia podem substituir acidentalmente os escopos fornecidos. Por exemplo, se você tiver várias AnimatedContent aninhadas, os escopos poderão ser substituídos.

val LocalNavAnimatedVisibilityScope = compositionLocalOf<AnimatedVisibilityScope?> { null }
val LocalSharedTransitionScope = compositionLocalOf<SharedTransitionScope?> { null }

@Composable
private fun SharedElementScope_CompositionLocal() {
    // An example of how to use composition locals to pass around the shared transition scope, far down your UI tree.
    // ...
    SharedTransitionLayout {
        CompositionLocalProvider(
            LocalSharedTransitionScope provides this
        ) {
            // This could also be your top-level NavHost as this provides an AnimatedContentScope
            AnimatedContent(state, label = "Top level AnimatedContent") { targetState ->
                CompositionLocalProvider(LocalNavAnimatedVisibilityScope provides this) {
                    // Now we can access the scopes in any nested composables as follows:
                    val sharedTransitionScope = LocalSharedTransitionScope.current
                        ?: throw IllegalStateException("No SharedElementScope found")
                    val animatedVisibilityScope = LocalNavAnimatedVisibilityScope.current
                        ?: throw IllegalStateException("No AnimatedVisibility found")
                }
                // ...
            }
        }
    }
}
BasicSharedElementSnippets.kt

Como alternativa, se a hierarquia não estiver profundamente aninhada, você poderá transmitir os escopos como parâmetros:

@Composable
fun MainContent(
    animatedVisibilityScope: AnimatedVisibilityScope,
    sharedTransitionScope: SharedTransitionScope
) {
}

@Composable
fun Details(
    animatedVisibilityScope: AnimatedVisibilityScope,
    sharedTransitionScope: SharedTransitionScope
) {
}
BasicSharedElementSnippets.kt

Elementos compartilhados com AnimatedVisibility

Os exemplos anteriores mostraram como usar elementos compartilhados com AnimatedContent, mas elementos compartilhados também funcionam com AnimatedVisibility.

Por exemplo, neste exemplo de grade lenta, cada elemento é unido em AnimatedVisibility. Quando o item é clicado, o conteúdo tem o efeito visual de ser extraído da interface em um componente semelhante a uma caixa de diálogo.

var selectedSnack by remember { mutableStateOf<Snack?>(null) }

SharedTransitionLayout(modifier = Modifier.fillMaxSize()) {
    LazyColumn(
        // ...
    ) {
        items(listSnacks) { snack ->
            AnimatedVisibility(
                visible = snack != selectedSnack,
                enter = fadeIn() + scaleIn(),
                exit = fadeOut() + scaleOut(),
                modifier = Modifier.animateItem()
            ) {
                Box(
                    modifier = Modifier
                        .sharedBounds(
                            sharedContentState = rememberSharedContentState(key = "${snack.name}-bounds"),
                            // Using the scope provided by AnimatedVisibility
                            animatedVisibilityScope = this,
                            clipInOverlayDuringTransition = OverlayClip(shapeForSharedElement)
                        )
                        .background(Color.White, shapeForSharedElement)
                        .clip(shapeForSharedElement)
                ) {
                    SnackContents(
                        snack = snack,
                        modifier = Modifier.sharedElement(
                            state = rememberSharedContentState(key = snack.name),
                            animatedVisibilityScope = this@AnimatedVisibility
                        ),
                        onClick = {
                            selectedSnack = snack
                        }
                    )
                }
            }
        }
    }
    // Contains matching AnimatedContent with sharedBounds modifiers.
    SnackEditDetails(
        snack = selectedSnack,
        onConfirmClick = {
            selectedSnack = null
        }
    )
}
AnimatedVisibilitySharedElementSnippets.kt

Figura 6. Elementos compartilhados com AnimatedVisibility.

Ordenação de modificadores

Com Modifier.sharedElement() e Modifier.sharedBounds(), a ordem da cadeia de modificadores é importante, assim como no restante do Compose. O posicionamento incorreto de modificadores que afetam o tamanho pode causar saltos visuais inesperados durante a correspondência do elemento compartilhado.

Por exemplo, se você colocar um modificador de padding em uma posição diferente em dois elementos compartilhados, vai haver uma diferença visual na animação.

var selectFirst by remember { mutableStateOf(true) }
val key = remember { Any() }
SharedTransitionLayout(
    Modifier
        .fillMaxSize()
        .padding(10.dp)
        .clickable {
            selectFirst = !selectFirst
        }
) {
    AnimatedContent(targetState = selectFirst, label = "AnimatedContent") { targetState ->
        if (targetState) {
            Box(
                Modifier
                    .padding(12.dp)
                    .sharedBounds(
                        rememberSharedContentState(key = key),
                        animatedVisibilityScope = this@AnimatedContent
                    )
                    .border(2.dp, Color.Red)
            ) {
                Text(
                    "Hello",
                    fontSize = 20.sp
                )
            }
        } else {
            Box(
                Modifier
                    .offset(180.dp, 180.dp)
                    .sharedBounds(
                        rememberSharedContentState(
                            key = key,
                        ),
                        animatedVisibilityScope = this@AnimatedContent
                    )
                    .border(2.dp, Color.Red)
                    // This padding is placed after sharedBounds, but it doesn't match the
                    // other shared elements modifier order, resulting in visual jumps
                    .padding(12.dp)

            ) {
                Text(
                    "Hello",
                    fontSize = 36.sp
                )
            }
        }
    }
}
BasicSharedElementSnippets.kt

Limites correspondentes	Limites sem correspondência: a animação do elemento compartilhado aparece um pouco fora do normal porque precisa ser redimensionada para os limites incorretos.

Os modificadores usados antes dos modificadores do elemento compartilhado fornecem restrições aos modificadores, que são usados para derivar os limites iniciais e de destino e, depois, a animação dos limites.

Os modificadores usados após os modificadores de elemento compartilhado usam as restrições anteriores para medir e calcular o tamanho de destino da filha. Os modificadores de elemento compartilhado criam uma série de restrições animadas para transformar gradualmente o elemento filho do tamanho inicial no tamanho de destino.

A exceção é se você usar resizeMode = ScaleToBounds() para a animação ou Modifier.skipToLookaheadSize() em um elemento combinável. Nesse caso, o Compose exibe a criança usando as restrições de destino e, em vez disso, usa um fator de escala para realizar a animação em vez de mudar o tamanho do layout em si.

Importante: seja consistente com a ordem dos modificadores nos itens correspondentes. Coloque os modificadores de tamanho depois dos modificadores de elemento compartilhado, exceto quando você usa requiredSize(). Se você usar requiredSize() após modificadores de elementos compartilhados, não haverá relayout de filhos durante a transformação, mesmo que você use ScaleToBounds(). Por outro lado, se requiredSize() estiver antes dos modificadores de elementos compartilhados, o elemento pai de requiredSize() nunca poderá observar os elementos compartilhados animatedSize.

Chaves exclusivas

Ao trabalhar com elementos compartilhados complexos, é recomendável criar uma chave que não seja uma string, já que as strings podem apresentar correspondências a erros. Cada chave precisa ser exclusiva para que as correspondências ocorram. Por exemplo, no Jetsnack, temos os seguintes elementos compartilhados:

Figura 7. Imagem mostrando o Jetsnack com anotações para cada parte da interface.

Você pode criar um tipo enumerado para representar o tipo de elemento compartilhado. Neste exemplo, todo o cartão de lanches também pode aparecer em vários lugares diferentes na tela inicial, por exemplo, nas seções "Mais populares" e "Recomendados". É possível criar uma chave que tenha o snackId, o origin ("Popular"/"Recomendado") e o type do elemento compartilhado que será compartilhado:

data class SnackSharedElementKey(
    val snackId: Long,
    val origin: String,
    val type: SnackSharedElementType
)

enum class SnackSharedElementType {
    Bounds,
    Image,
    Title,
    Tagline,
    Background
}

@Composable
fun SharedElementUniqueKey() {
    // ...
            Box(
                modifier = Modifier
                    .sharedElement(
                        rememberSharedContentState(
                            key = SnackSharedElementKey(
                                snackId = 1,
                                origin = "latest",
                                type = SnackSharedElementType.Image
                            )
                        ),
                        animatedVisibilityScope = this@AnimatedVisibility
                    )
            )
            // ...
}
BasicSharedElementSnippets.kt

As classes de dados são recomendadas para chaves, já que implementam hashCode() e isEquals().

Importante :tenha cuidado ao trabalhar com listas de conteúdo. É necessário anexar o número do item à chave ou usar um identificador exclusivo diferente.

Gerenciar a visibilidade dos elementos compartilhados manualmente

Nos casos em que você não usa AnimatedVisibility ou AnimatedContent, é possível gerenciar a visibilidade do elemento compartilhado. Use Modifier.sharedElementWithCallerManagedVisibility() e forneça sua própria condicional que determina quando um item precisa ficar visível ou não:

var selectFirst by remember { mutableStateOf(true) }
val key = remember { Any() }
SharedTransitionLayout(
    Modifier
        .fillMaxSize()
        .padding(10.dp)
        .clickable {
            selectFirst = !selectFirst
        }
) {
    Box(
        Modifier
            .sharedElementWithCallerManagedVisibility(
                rememberSharedContentState(key = key),
                !selectFirst
            )
            .background(Color.Red)
            .size(100.dp)
    ) {
        Text(if (!selectFirst) "false" else "true", color = Color.White)
    }
    Box(
        Modifier
            .offset(180.dp, 180.dp)
            .sharedElementWithCallerManagedVisibility(
                rememberSharedContentState(
                    key = key,
                ),
                selectFirst
            )
            .alpha(0.5f)
            .background(Color.Blue)
            .size(180.dp)
    ) {
        Text(if (selectFirst) "false" else "true", color = Color.White)
    }
}
BasicSharedElementSnippets.kt

Importante: o elemento compartilhado permanece na árvore da interface mesmo quando visible == false. O elemento compartilhado inicia uma transição sempre que o tamanho ou a posição mudam, porque ele tem uma correspondência ativa. Portanto, é recomendável remover o elemento compartilhado com visible == false da árvore quando a transição for concluída, observando SharedTransitionScope.isTransitionActive.

Limitações atuais

Essas APIs têm algumas limitações. Mais especificamente:

• Não há suporte à interoperabilidade entre as visualizações e o Compose. Isso inclui qualquer elemento combinável que envolva AndroidView, como um Dialog.
• Não há suporte a animação automática para o seguinte:
  • Elementos combináveis de imagem compartilhada:
    • ContentScale não é animado por padrão. Ele é fixado no final definido ContentScale.
  • Recorte de forma: não há suporte integrado para animação automática entre formas, por exemplo, animar de um quadrado para um círculo durante a transição do item.
  • Para os casos sem suporte, use Modifier.sharedBounds() em vez de sharedElement() e adicione Modifier.animateEnterExit() aos itens.