Gerenciamento de teclado removível

Ícone de avaliação de três estrelas

O suporte a teclados removíveis ajuda a maximizar a produtividade do usuário em dispositivos de tela grande. O Android aciona uma mudança de configuração sempre que um teclado é conectado ou desconectado de um dispositivo, o que pode causar uma perda do estado da interface. O app pode salvar e restaurar o estado, permitindo que o sistema processe a recriação de atividades, ou restringir a recriação de atividades para mudanças na configuração do teclado.

Em todos os casos, todos os dados relacionados ao teclado são armazenados em um objeto Configuration. Os campos keyboard e keyboardHidden do objeto de configuração contêm informações sobre o tipo de teclado e a disponibilidade dele.

Práticas recomendadas

Os apps otimizados para telas grandes oferecem suporte a todos os tipos de dispositivos de entrada, desde teclados de software e hardware até stylus, mouse, trackpad e outros dispositivos periféricos.

O suporte a teclados externos envolve mudanças de configuração, que podem ser gerenciadas de duas maneiras:

  1. Deixe o sistema recriar a atividade em execução e cuide do gerenciamento do estado do app.
  2. Gerenciar a mudança de configuração por conta própria (a atividade não será recriada):
    • Declarar todos os valores de configuração relacionados ao teclado
    • Criar um gerenciador de mudanças de configuração

Os apps de produtividade, que geralmente exigem um controle preciso da interface para entrada de texto e outras entradas, podem se beneficiar da abordagem de aprenda a fazer para lidar com mudanças de configuração.

Em casos especiais, talvez você queira mudar o layout do app quando um teclado de hardware for conectado ou desconectado, por exemplo, para liberar mais espaço para ferramentas ou janelas de edição.

No Jetpack Compose, é possível reagir a mudanças na configuração do teclado de duas maneiras:

  1. IU reativa:leia o estado de configuração atual diretamente nos elementos que podem ser compostos usando LocalConfiguration.current. A interface é recomposta automaticamente para se adaptar ao novo estado quando um teclado é conectado ou desconectado.
  2. Callback de efeito colateral:use um DisposableEffect que reconhece o ciclo de vida para registrar um listener de mudança de configuração na atividade do host, o que permite acionar eventos que não são da interface (como geração de registros ou análises) sem recriar a atividade ou instanciar elementos de visualização fictícios.

Ingredientes

  • android:configChanges: atributo do elemento <activity> do manifesto do app. Informa ao sistema sobre as mudanças de configuração que o app gerencia.
  • LocalConfiguration: provedor local de composição que expõe o Configuration do dispositivo atual.
  • DisposableEffect: API de efeito colateral do Compose que executa um bloco de código quando um elemento que pode ser composto entra na composição e faz a limpeza quando ele sai.

Etapas

Declare o atributo configChanges e adicione valores relacionados ao teclado para evitar a recriação da atividade. Em seguida, use LocalConfiguration.current para adaptar dinamicamente o layout combinável ou registre um listener de configuração usando DisposableEffect.

1. Declarar o atributo configChanges

Atualize o elemento <activity> no manifesto do app adicionando os valores keyboard|keyboardHidden à lista de mudanças de configuração já gerenciadas:

<activity
      …
      android:configChanges="...|keyboard|keyboardHidden">

2. Responder a mudanças na configuração do teclado

Para lidar com mudanças de configuração no Jetpack Compose, use uma das seguintes opções, dependendo se você está atualizando a IU ou executando um callback de efeito colateral:

  • Opção A: interface reativa (recomendada)

    Leia o tipo de teclado diretamente de LocalConfiguration.current. Quando um teclado de hardware é conectado ou desconectado, esse valor muda, e o Compose recompõe automaticamente a interface.

    val configuration = LocalConfiguration.current
    val isPhysicalKeyboardAttached = configuration.keyboard == Configuration.KEYBOARD_QWERTY
    
    if (isPhysicalKeyboardAttached) {
        // Render layout optimized for physical keyboard
    } else {
        // Render default layout
    }

  • Opção B: listener de efeito colateral

    Se você precisar executar um efeito colateral (como registro, atualização de um banco de dados local ou acionamento de análises) quando a configuração mudar, use um DisposableEffect para registrar um listener de mudança de configuração no host ComponentActivity.

    val context = LocalActivity.current
    DisposableEffect(context) {
        val activity = context as? ComponentActivity
        val listener = Consumer<Configuration> { newConfig ->
            val hasKeyboard = newConfig.keyboard == Configuration.KEYBOARD_QWERTY
            // Trigger non-UI actions, analytics, etc.
        }
        activity?.addOnConfigurationChangedListener(listener)
        onDispose {
            activity?.removeOnConfigurationChangedListener(listener)
        }
    }

Resultados

Agora, o app vai responder à conexão ou desconexão de um teclado externo sem recriar a atividade em execução.

Outros recursos

Para saber como salvar o estado da interface do app durante mudanças de configuração, como conectar ou desconectar o teclado, consulte Salvar estados da interface.