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. Eles são frequentemente usados para navegação, permitindo que você conecte visualmente diferentes telas à medida que o 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. Ele fornece um SharedTransitionScope. Os elementos combináveis precisam estar em um SharedTransitionScope para usar os modificadores de elemento compartilhado.
• Modifier.sharedElement(): o modificador que sinaliza para o SharedTransitionScope o elemento combinável que precisa ser combinado a 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-beta01 e é experimental. As APIs podem mudar no futuro. Registre bugs no issuetracker.

Uso básico

A transição a seguir será criada nesta seção, passando do item de "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 isso gerencia a transição entre os 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. Iniciar 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 nos dois elementos correspondentes. Crie um objeto SharedContentState e lembre-o 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 para o 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 ocorreu uma correspondência de elemento compartilhado, 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() serve para conteúdo visualmente diferente, mas que precisa compartilhar a mesma área entre 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 permitirá compartilhar os limites dos dois e executar 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, 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 receptores de contexto em Kotlin ou transmita os escopos como parâmetros para suas funções.

Use CompositionLocals quando você tiver vários escopos para acompanhar ou uma hierarquia aninhada em vários níveis. 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ários AnimatedContent aninhados, 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, caso sua hierarquia não esteja profundamente aninhada, transmita 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 depois dos modificadores do elemento compartilhado usam as restrições de antes para medir e calcular o tamanho de destino do filho. Os modificadores do elemento compartilhado criam uma série de restrições animadas para transformar gradualmente o filho do tamanho inicial para o 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 mostra o filho usando as restrições de destino e, em vez disso, usa um fator de escalonamento para realizar a animação, em vez de mudar o tamanho do layout.

Importante: seja consistente com a ordem dos modificadores nos itens correspondentes. Coloque os modificadores de tamanho após os modificadores do elemento compartilhado, exceto quando você usa requiredSize(). Se você usar requiredSize() após os modificadores de elemento compartilhado, não haverá novo layout dos filhos durante a transformação, mesmo se você usar ScaleToBounds(). Por outro lado, se requiredSize() estiver antes dos modificadores do elemento compartilhado, o 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, como nas seções "Em alta" e "Recomendado". É 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 porque elas 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 não é possível usar AnimatedVisibility ou AnimatedContent, você pode gerenciar a visibilidade do elemento compartilhado por conta própria. 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 muda quando há 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 se ajusta ao final ContentScale definido.
  • 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.