APIs de interoperabilidade

Ao adotar o Compose no seu app, as IUs do Compose e as baseadas em visualização podem ser combinadas. Confira esta lista de APIs, recomendações e dicas para facilitar a transição para o Compose.

Compose em visualizações

É possível adicionar uma IU com base no Compose a um app já existente que usa um design com base em visualização.

Para criar uma tela totalmente baseada no Compose, faça sua atividade chamar o método setContent() e transmitir as funções combináveis que você quer usar.

class ExampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent { // In here, we can call composables!
            MaterialTheme {
                Greeting(name = "compose")
            }
        }
    }
}

@Composable
fun Greeting(name: String) {
    Text(text = "Hello $name!")
}
InteroperabilityAPIsSnippets.kt

Esse código é parecido com o que você encontraria em um app feito inteiramente com o Compose.

ViewCompositionStrategy para ComposeView

Por padrão, o Compose descarta a composição sempre que a visualização se desanexa de uma janela. Os tipos de View da IU do Compose, como ComposeView e AbstractComposeView, usam uma ViewCompositionStrategy que define esse comportamento.

Por padrão, o Compose usa a estratégia DisposeOnDetachedFromWindowOrReleasedFromPool. No entanto, esse valor padrão pode ser indesejável em algumas situações em que os tipos de View da IU do Compose são usados em:

  • Fragmentos. A composição precisa seguir o ciclo de vida de visualização do fragmento para que os tipos de View da IU do Compose salvem o estado.

  • Transições. Sempre que a View da IU do Compose é usada como parte de uma transição, ela é removida da janela assim que a transição é iniciada, e não quando ela termina. Isso faz com que o elemento combinável descarte o estado enquanto ainda está na tela.

  • Sua View personalizada gerenciada por ciclo de vida.

Em algumas dessas situações, o app também poderá apresentar vazamento lento de memória nas instâncias de composição, a menos que você chame manualmente AbstractComposeView.disposeComposition.

Para descartar as composições automaticamente quando elas não forem mais necessárias, defina uma estratégia diferente ou crie uma própria chamando o método setViewCompositionStrategy. Por exemplo, a estratégia DisposeOnLifecycleDestroyed descarta a composição quando o lifecycle é destruído. Essa estratégia é adequada para os tipos de View da IU do Compose que compartilham uma relação direta com um LifecycleOwner conhecido. Quando o LifecycleOwner não for conhecido, o DisposeOnViewTreeLifecycleDestroyed poderá ser usado.

Veja essa API em ação em ComposeView em fragmentos.

ComposeView em fragmentos

Se você quiser incorporar o conteúdo da IU do Compose em um fragmento ou um layout de visualização já existente, use ComposeView e chame o método setContent() dele. ComposeView é uma View para Android.

Você pode colocar a ComposeView no seu layout XML como qualquer outra View:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <TextView
        android:id="@+id/hello_world"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Hello Android!" />

    <androidx.compose.ui.platform.ComposeView
        android:id="@+id/compose_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

No código-fonte do Kotlin, infle o layout usando o recurso de layout definido no XML. Em seguida, acesse a ComposeView usando o ID do XML, defina uma estratégia de composição que funcione melhor para a View host e chame setContent() para usar o Compose.

class ExampleFragment : Fragment() {

    private var _binding: FragmentExampleBinding? = null

    // This property is only valid between onCreateView and onDestroyView.
    private val binding get() = _binding!!

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        _binding = FragmentExampleBinding.inflate(inflater, container, false)
        val view = binding.root
        binding.composeView.apply {
            // Dispose of the Composition when the view's LifecycleOwner
            // is destroyed
            setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
            setContent {
                // In Compose world
                MaterialTheme {
                    Text("Hello Compose!")
                }
            }
        }
        return view
    }

    override fun onDestroyView() {
        super.onDestroyView()
        _binding = null
    }
}
InteroperabilityAPIsSnippets.kt

Dois elementos de texto um pouco diferentes, um acima do outro

Figura 1. Isso mostra a saída do código que adiciona elementos do Compose a uma hierarquia de IU de visualização. A mensagem "Hello Android!" é exibida por um widget TextView. A mensagem "Hello Compose!" é exibida por um elemento de texto do Compose.

Também será possível incluir uma ComposeView diretamente em um fragmento se a tela cheia for criada com o Compose, o que permite evitar totalmente o uso de um arquivo de layout XML.

class ExampleFragmentNoXml : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        return ComposeView(requireContext()).apply {
            // Dispose of the Composition when the view's LifecycleOwner
            // is destroyed
            setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
            setContent {
                MaterialTheme {
                    // In Compose world
                    Text("Hello Compose!")
                }
            }
        }
    }
}
InteroperabilityAPIsSnippets.kt

Várias ComposeViews no mesmo layout

Se houver vários elementos ComposeView no mesmo layout, cada um precisará ter um ID exclusivo para que o savedInstanceState funcione.

class ExampleFragmentMultipleComposeView : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View = LinearLayout(requireContext()).apply {
        addView(
            ComposeView(requireContext()).apply {
                setViewCompositionStrategy(
                    ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed
                )
                id = R.id.compose_view_x
                // ...
            }
        )
        addView(TextView(requireContext()))
        addView(
            ComposeView(requireContext()).apply {
                setViewCompositionStrategy(
                    ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed
                )
                id = R.id.compose_view_y
                // ...
            }
        )
    }
}
InteroperabilityAPIsSnippets.kt

Os IDs ComposeView são definidos no arquivo res/values/ids.xml:

<resources>
    <item name="compose_view_x" type="id" />
    <item name="compose_view_y" type="id" />
</resources>

Visualizações no Compose

É possível incluir uma hierarquia de visualização do Android em uma IU do Compose. Essa abordagem vai ser útil principalmente se você quiser usar elementos da IU que ainda não estão disponíveis no Compose, como AdView. Essa abordagem também permite reutilizar visualizações personalizadas que você pode ter criado.

Para incluir um elemento ou uma hierarquia de visualização, use a AndroidView que pode ser composta. AndroidView recebe uma lambda que retorna uma View. AndroidView também fornece um callback update que é chamado quando a visualização é inflada. A AndroidView faz a recomposição sempre que um State lido dentro do callback muda. A AndroidView, assim como vários outros elementos combináveis integrados, aceita um parâmetro Modifier que pode ser usado, por exemplo, para definir a posição dela no elemento combinável pai.

@Composable
fun CustomView() {
    var selectedItem by remember { mutableStateOf(0) }

    // Adds view to Compose
    AndroidView(
        modifier = Modifier.fillMaxSize(), // Occupy the max size in the Compose UI tree
        factory = { context ->
            // Creates view
            MyView(context).apply {
                // Sets up listeners for View -> Compose communication
                setOnClickListener {
                    selectedItem = 1
                }
            }
        },
        update = { view ->
            // View's been inflated or state read in this block has been updated
            // Add logic here if necessary

            // As selectedItem is read here, AndroidView will recompose
            // whenever the state changes
            // Example of Compose -> View communication
            view.selectedItem = selectedItem
        }
    )
}

@Composable
fun ContentExample() {
    Column(Modifier.fillMaxSize()) {
        Text("Look at this CustomView!")
        CustomView()
    }
}

InteroperabilityAPIsSnippets.kt

Para incorporar um layout XML, use a API AndroidViewBinding, que é fornecida pela biblioteca androidx.compose.ui:ui-viewbinding. Para isso, seu projeto precisa ativar a vinculação de visualizações.

@Composable
fun AndroidViewBindingExample() {
    AndroidViewBinding(ExampleLayoutBinding::inflate) {
        exampleView.setBackgroundColor(Color.GRAY)
    }
}
InteroperabilityAPIsSnippets.kt

Fragmentos no Compose

Use o elemento combinável AndroidViewBinding para adicionar um Fragment no Compose. O AndroidViewBinding inclui processamentos específicos de fragmentos, como remover o fragmento quando o elemento combinável sai da composição.

Para isso, infle o XML contendo uma FragmentContainerView como detentora do Fragment.

Por exemplo, se você tiver o my_fragment_layout.xml definido, poderá usar um código como este ao substituir o atributo android:name do XML pelo nome da classe de Fragment:

<androidx.fragment.app.FragmentContainerView
  xmlns:android="http://schemas.android.com/apk/res/android"
  android:id="@+id/fragment_container_view"
  android:layout_height="match_parent"
  android:layout_width="match_parent"
  android:name="com.example.MyFragment" />

Infle esse fragmento no Compose desta maneira:

@Composable
fun FragmentInComposeExample() {
    AndroidViewBinding(MyFragmentLayoutBinding::inflate) {
        val myFragment = fragmentContainerView.getFragment<MyFragment>()
        // ...
    }
}

InteroperabilityAPIsSnippets.kt

Se você precisa usar vários fragmentos no mesmo layout, defina um ID exclusivo para cada FragmentContainerView.

Como chamar o framework do Android no Compose

O Compose opera dentro das classes do framework do Android. Por exemplo, ele é hospedado em classes de visualização do Android, como Activity ou Fragment, e pode precisar usar classes do framework do Android, como Context, recursos do sistema, Service ou BroadcastReceiver.

Para saber mais sobre recursos do sistema, consulte a documentação Recursos no Compose.

Classes Composition Locals

As classes CompositionLocal permitem transmitir dados implicitamente usando funções combináveis. Em geral, elas recebem um valor em determinado nó da árvore da IU. Esse valor pode ser usado pelos descendentes combináveis sem declarar o CompositionLocal como um parâmetro na função combinável.

O CompositionLocal é usado na propagação de valores para tipos de framework do Android no Compose (como Context, Configuration ou View) em que o código do Compose é hospedado com o LocalContext, LocalConfiguration ou LocalView correspondente. As classes CompositionLocal têm o prefixo Local para melhor detecção do dispositivo com o preenchimento automático no ambiente de desenvolvimento integrado.

Acesse o valor atual de um CompositionLocal usando a propriedade current. Por exemplo, o código abaixo mostra uma mensagem de aviso usando LocalContext.current no método Toast.makeToast.

@Composable
fun ToastGreetingButton(greeting: String) {
    val context = LocalContext.current
    Button(onClick = {
        Toast.makeText(context, greeting, Toast.LENGTH_SHORT).show()
    }) {
        Text("Greet")
    }
}
InteroperabilityAPIsSnippets.kt

Para ver um exemplo mais completo, confira a seção Estudo de caso: BroadcastReceivers no fim deste documento.

Outras interações

Caso não haja um utilitário definido para a interação necessária, a prática recomendada é seguir as diretrizes gerais do Compose (o fluxo de dados desce, os eventos sobem), discutidas com mais detalhes em Como trabalhar com o Compose. Por exemplo, essa função combinável inicia uma atividade diferente:

class OtherInteractionsActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // get data from savedInstanceState
        setContent {
            MaterialTheme {
                ExampleComposable(data, onButtonClick = {
                    startActivity(Intent(this, MyActivity::class.java))
                })
            }
        }
    }
}

@Composable
fun ExampleComposable(data: DataExample, onButtonClick: () -> Unit) {
    Button(onClick = onButtonClick) {
        Text(data.title)
    }
}
InteroperabilityAPIsSnippets.kt

Estudo de caso: BroadcastReceivers

Para ver um exemplo mais realista dos recursos que você quer migrar ou implementar no Compose e para demonstrar o CompositionLocal e os efeitos colaterais, digamos que um BroadcastReceiver precise ser registrado usando uma função combinável.

A solução utiliza LocalContext para usar o contexto atual e os efeitos colaterais de rememberUpdatedState e DisposableEffect.

@Composable
fun SystemBroadcastReceiver(
    systemAction: String,
    onSystemEvent: (intent: Intent?) -> Unit
) {
    // Grab the current context in this part of the UI tree
    val context = LocalContext.current

    // Safely use the latest onSystemEvent lambda passed to the function
    val currentOnSystemEvent by rememberUpdatedState(onSystemEvent)

    // If either context or systemAction changes, unregister and register again
    DisposableEffect(context, systemAction) {
        val intentFilter = IntentFilter(systemAction)
        val broadcast = object : BroadcastReceiver() {
            override fun onReceive(context: Context?, intent: Intent?) {
                currentOnSystemEvent(intent)
            }
        }

        context.registerReceiver(broadcast, intentFilter)

        // When the effect leaves the Composition, remove the callback
        onDispose {
            context.unregisterReceiver(broadcast)
        }
    }
}

@Composable
fun HomeScreen() {

    SystemBroadcastReceiver(Intent.ACTION_BATTERY_CHANGED) { batteryStatus ->
        val isCharging = /* Get from batteryStatus ... */ true
        /* Do something if the device is charging */
    }

    /* Rest of the HomeScreen */
}
InteroperabilityAPIsSnippets.kt