Desenvolvimento de código iterativo

Como desenvolvedor para dispositivos móveis, você tem o hábito de desenvolver a interface do seu app etapa por etapa e não de uma só vez. O Android Studio adota essa abordagem com o Jetpack Compose, fornecendo ferramentas que não exigem um build completo para inspecionar, modificar valores e verificar o resultado final.

Edição em tempo real

A Edição em tempo real é um recurso que permite atualizar elementos combináveis em emuladores e dispositivos físicos em tempo real. Essa funcionalidade minimiza as mudanças de contexto entre a programação de código e a criação do app, permitindo que você se concentre na programação por mais tempo, sem interrupções.

A Edição em tempo real tem três modos:

  • Manual: as mudanças de código são aplicadas quando são enviadas manualmente usando Control + \ (Command + \ no macOS).
  • Manual ao salvar: as mudanças de código são aplicadas quando são salvas manualmente usando Ctrl + S (Command + S no macOS).
  • Automática: as mudanças são aplicadas no dispositivo ou emulador quando você atualiza uma função combinável.

O recurso de Edição em tempo real se concentra em mudanças no código relacionadas a IU e UX. Ele não oferece suporte a mudanças como atualizações de assinatura de método, adição de novos métodos ou mudanças na hierarquia de classes. Para saber mais, consulte a lista de Limitações do recurso Edição em tempo real.

Esse recurso não substitui a criação e execução do app ou o recurso Aplicar mudanças. Em vez disso, ele foi projetado para otimizar o fluxo de trabalho durante a criação, implantação e iteração para desenvolver a interface do Compose.

Confira as práticas recomendadas de fluxo de trabalho:

  1. Configure o aplicativo para que ele possa ser executado.
  2. Use a Edição em tempo real o máximo possível, até que seja necessário fazer uma mudança sem suporte desse recurso. Por exemplo: adicionar novos métodos enquanto o app estiver em execução.
  3. Depois de fazer uma mudança sem suporte, clique em Run Ícone
de execução para reiniciar o app e retomar a Edição em tempo real.

Como usar o recurso Edição em tempo real

Para começar, siga estas etapas para criar uma atividade vazia do Compose, ativar a Edição em tempo real no projeto e fazer mudanças com ela.

Configurar o novo projeto

  1. Antes de começar, confira se o Android Studio Giraffe ou uma versão mais recente está instalado e se o nível da API do dispositivo ou emulador físico é de pelo menos 30.

  2. Abra o Android Studio e selecione New Project no pop-up Welcome to Android Studio. Se já tiver um projeto aberto, você poderá criar um novo acessando File > New > New Project.

  3. Escolha o modelo Empty Compose Activity para Phone and Tablet e clique em Next.

    Seleção de modelos no Android Studio
    Figura 1. Modelos para escolher. Para usar a Edição em tempo real, escolha Empty Compose Activity.
  4. Preencha a caixa de diálogo New Project com as informações necessárias: nome, nome do pacote, local para salvar, SDK mínimo e idioma de configuração do build.

    Exemplo de configurações do projeto da Etapa 4 inseridas no Android Studio
    Figura 2. Exemplos de configurações do projeto.
  5. Clique em Finish.

Ativar o recurso Edição em tempo real

  1. Acesse as configurações para ativar a Edição em tempo real.

    • No Windows ou no Linux, acesse File > Settings > Editor > Live Edit.
    • No macOS, acesse Android Studio > Settings > Editor > Live Edit.
  2. Selecione a opção Live Edit e o modo que você quer executar nas configurações.

    No modo manual, as mudanças no código são enviadas sempre que você pressiona Control + \ (Command + \ no macOS). No modo manual ao salvar, as alterações de código são aplicadas sempre que você salva manualmente usando Ctrl + S (Command + S no macOS). No modo automático, as mudanças de código são aplicadas no dispositivo ou emulador à medida que você faz as mudanças.

    IU da caixa de seleção da Edição em tempo real nas configurações do Android Studio
    Figura 3. Configurações da Edição em tempo real.
  3. No editor, abra o arquivo MainActivity, que é o ponto de entrada do app.

  4. Clique em Run Botão da interface para implantar o app.

  5. Depois de ativar a Edição em tempo real, a marca de seleção verde Up-to-date (atualizado) vai aparecer no canto superior direito da janela de ferramentas Running Devices:

    interface da marca de seleção verde da Edição em tempo real

Fazer e revisar mudanças

Quando você faz mudanças com suporte no editor, o dispositivo de teste virtual ou físico é atualizado automaticamente.

Por exemplo, edite o método Greeting existente em MainActivity para o seguinte:

@Composable
fun Greeting(name: String) {
    Text(
        text = "Hello $name!",
        Modifier
            .padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}

As mudanças feitas aparecem instantaneamente no dispositivo de teste, como mostrado na Figura 4.

Mudanças feitas no método de saudação mostradas em um dispositivo
Figura 4. O dispositivo de teste que mostra a Edição em tempo real muda para o método Greeting.

Resolver problemas da Edição em tempo real

Se as edições não aparecerem no dispositivo de teste, é possível que o Android Studio não tenha atualizado as edições. Verifique se o indicador "Live Edit" mostra Out Of Date (desatualizado), como na Figura 5, que indica um erro de compilação. Para saber mais sobre o erro e receber sugestões para resolvê-lo, clique no indicador.

Ícone "out of date" da Edição em tempo real
Figura 5. Indicador de status da Edição em tempo real.

Limitações do recurso Edição em tempo real

Veja abaixo uma lista das limitações atuais.

  • [Aplicável apenas ao Android Studio Giraffe e versões mais recentes] A Edição em tempo real requer o Compose Runtime 1.3.0 ou mais recente. Se o projeto usar uma versão anterior do Compose, a Edição em tempo real será desativada.

  • [Aplicável apenas ao Android Studio Giraffe e versões mais recentes] A Edição em tempo real requer o AGP 8.1.0-alpha05 ou mais recente. Se o projeto usar uma versão mais antiga do AGP, a Edição em tempo real será desativada.

  • A Edição em tempo real requer um dispositivo físico ou emulador com o nível 30 da API ou mais recente.

  • A Edição em tempo real só oferece suporte à edição de um corpo de função, ou seja, não é possível mudar o nome ou a assinatura da função, adicionar ou remover uma função ou mudar campos que não sejam de função.

  • A Edição em tempo real redefine o estado do app na primeira vez que você muda uma função do Compose em um arquivo. Isso só acontece após a primeira mudança no código. O estado do app não é redefinido por mudanças de código subsequentes feitas nas funções do Compose nesse arquivo.

  • As classes modificadas na Edição em tempo real podem ter problemas de performance. Execute o app e use um build de lançamento limpo se estiver avaliando o desempenho.

  • É necessário executar uma execução completa para que o depurador funcione nas classes que você modificou com a Edição em tempo real.

  • Um app em execução pode falhar quando você usa a Edição em tempo real. Se isso acontecer, você pode reimplantar o app com o botão Run Botão da
interface.

  • A Edição em tempo real não realiza nenhuma manipulação de bytecode definida no arquivo de build do projeto. Por exemplo, a manipulação de bytecode que seria aplicada quando o projeto era criado usando as opções no menu Build ou clicando nos botões Build ou Run.

  • As funções que não são combináveis são atualizadas em tempo real no dispositivo ou emulador, e uma recomposição completa é acionada. A recomposição completa pode não invocar a função atualizada. Para funções não combináveis, é necessário acionar as funções recém-atualizadas ou executar o app novamente.

  • A Edição em tempo real não é retomada após a reinicialização do app. Execute o app novamente.

  • A Edição em tempo real só oferece suporte a processos depuráveis.

  • A Edição em tempo real não oferece suporte a projetos que usam valores personalizados para moduleName em kotlinOptions na configuração do build.

  • A Edição em tempo real não funciona com implantações múltiplas. Isso significa que não é possível implantar em um dispositivo e depois em outro. A Edição em tempo real só fica ativa no último conjunto de dispositivos em que o app foi implantado.

  • A Edição em tempo real funciona com implantações multidispositivo, ou seja, implantações em vários dispositivos que foram criados usando a opção Selecionar vários dispositivos na lista suspensa de dispositivo de destino. No entanto, ela não tem suporte oficial e pode haver problemas. Se você tiver problemas, informe aqui.

  • O recurso Apply Changes/Apply Code Changes não é compatível com a Edição em tempo real e exige que o app em execução seja reiniciado.

  • No momento, a Edição em tempo real não oferece suporte a projetos do Android Automotive.

Perguntas frequentes sobre o recurso de Edição em tempo real

  • Qual é o status atual da Edição em tempo real?

    A Edição em tempo real está disponível no Android Studio Giraffe. Para ativar o recurso, acesse File > Settings > Editor > Live Edit (Android Studio > Settings > Editor > Live Edit no macOS).

  • Quando usar a Edição em tempo real?

    Use a Edição em tempo real quando quiser conferir rapidamente o efeito das atualizações de elementos de UX (como atualizações de modificadores e animações) na experiência geral do app.

  • Quando devo evitar o uso da Edição em tempo real?

    O recurso de Edição em tempo real se concentra em mudanças no código relacionadas a IU e UX. Ele não oferece suporte a mudanças como atualizações de assinatura de método, adição de novos métodos ou mudanças na hierarquia de classes. Para mais informações, consulte Limitações da Edição em tempo real.

  • Quando usar a Visualização do Compose?

    Use a Visualização do Compose ao desenvolver elementos combináveis. A visualização mostra elementos do Compose e é atualizada automaticamente para mostrar o efeito das mudanças no código. A visualização também oferece suporte à exibição de elementos da interface em diferentes configurações e estados, como tema escuro, localidades e escala da fonte.

Edição em tempo real de literais (descontinuado)

O Android Studio pode atualizar, em tempo real, literais constantes usados em elementos combináveis nas visualizações, no emulador e no dispositivo físico. Veja alguns tipos compatíveis:

  • Int
  • String
  • Color
  • Dp
  • Boolean

Vídeo do usuário mudando literais no código-fonte, e a visualização sendo atualizada
dinamicamente

É possível conferir literais constantes que acionam atualizações em tempo real sem a etapa de compilação, ativando as decorações de literais pelo recurso "Edição em tempo real" do indicador da interface de literais:

Como ativar a edição em tempo real de literais

Aplicar mudanças

Apply Changes permite atualizar o código e os recursos sem ter que reimplantar o app em um emulador ou dispositivo físico (com algumas limitações).

Sempre que você adicionar, modificar ou excluir elementos combináveis, poderá atualizar o app sem precisar reimplantá-lo clicando no botão Apply Code Changes:

Usuário clicando no botão "Aplicar alterações"