Gerenciamento de teclado removível

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 da atividade, ou restringir a recriação da atividade para mudanças de configuração do teclado.

Em todos os casos, todos os dados relacionados ao teclado são armazenados em um Configuration objeto. 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 periféricos.

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

1. Permita que o sistema recrie a atividade em execução e cuide do gerenciamento do estado do app.
2. Gerencie a mudança de configuração por conta própria (a atividade não será recriada):
   • Declare todos os valores de configuração relacionados ao teclado.
   • Crie um gerenciador de mudanças de configuração.

Os apps de produtividade, que geralmente exigem controle refinado da interface para entrada de texto e outras entradas, podem se beneficiar da abordagem "faça você mesmo" para processar 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 criar mais espaço para ferramentas ou janelas de edição.

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

1. Interface reativa:leia o estado de configuração atual diretamente nos elementos combináveis 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 com reconhecimento do ciclo de vida para registrar um listener de mudança de configuração na atividade do host, que permite acionar eventos não relacionados à interface (como registro ou análise) sem recriar a atividade ou instanciar elementos de visualização fictícios.

Ingredientes

• android:configChanges: atributo do elemento <activity> do manifesto do app. Informa o sistema sobre as mudanças de configuração que o app gerencia.
• LocalConfiguration: provedor local combinável que expõe o dispositivo Configuration.
• DisposableEffect: API de efeito colateral do Compose que executa um bloco de código quando um elemento combinável entra na composição e limpa 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 keyboard|keyboardHidden valores à lista de mudanças de configuração já gerenciadas:

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

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

Para processar mudanças de configuração no Jetpack Compose, use uma das seguintes opções, dependendo se você está atualizando a interface 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 recomponha 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
  }
  AdaptiveAppCookbook.kt

• 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 ComponentActivity do host.

  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)
      }
  }
  AdaptiveAppCookbook.kt

Resultados

O app agora vai responder a um teclado externo conectado ou desconectado 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 conexão ou desconexão do teclado, consulte Salvar estados da interface.