Gestos com uma mão no Compose

A partir do Wear OS 7 (nível 37 da API), uma estrutura de gestos com uma mão, junto com uma API que faz parte do Compose para Wear OS, permite que os usuários interajam com o app sem tocar na tela.

Embora inicialmente tenha suporte em dispositivos Pixel Watch (Pixel Watch 3 e mais recentes), a estrutura está disponível para todos os OEMs. Ao adotar essa API, o suporte a gestos do app é dimensionado automaticamente em todo o ecossistema à medida que o suporte de hardware é expandido.

Para ajudar os usuários a descobrir os gestos disponíveis sem poluir a interface, a estrutura do Wear OS oferece indicadores de gestos animados. Essas dicas visuais destacam onde um gesto pode ser realizado, enquanto o sistema gerencia automaticamente a cadência de exibição e a frequência de silenciamento de acordo com as preferências do usuário.

Gestos e ações com suporte

A estrutura de gestos do Wear OS oferece suporte a dois tipos de gestos:

  • Ação principal (fazer gesto de pinça duas vezes): mapeia para a ação principal em uma tela, como atender uma chamada ou alternar a reprodução de mídia.
  • Ação de dispensa (girar o pulso) : mapeia para a navegação para trás, dispensando uma caixa de diálogo ou cancelando um comando.

Configurar gestos no Compose

Embora a API de gestos com uma mão possa melhorar a interface, é importante lembrar que alguns hardwares e OEMs não oferecem suporte a esses gestos. Se a API detectar que o app está sendo executado em um desses dispositivos sem suporte, a biblioteca vai desativar automaticamente sem afetar as interações de toque padrão.

Assim como nos comportamentos padrão do Compose, você ativa gestos com uma mão em elementos da interface usando modificadores. Você configura os gestos do app de acordo com a ação a ser realizada (principal ou dispensar) e um gestureId para coordenar com as preferências do usuário no nível do sistema, como cadência de exibição de dicas e silenciamento de frequência. Para expressar essa configuração, crie um OneHandedGestureConfiguration objeto. Recomendamos usar a rememberOneHandedGestureConfiguration função para criá-lo. O OneHandedGestureConfiguration também é o local em que você pode fornecer a prioridade do gesto.

A função rememberOneHandedGestureConfiguration rastreia o histórico de interação do usuário em recomposições sem expor o estado do aplicativo. Depois que o app criar a configuração, ele precisará transmiti-la para Modifier.oneHandedGesture no elemento combinável interativo.

Para ajudar os usuários a descobrir os gestos disponíveis, a biblioteca fornece o método OneHandedGestureClickIndicator. Esse método funciona como um wrapper que substitui o conteúdo subjacente para indicar ao usuário que uma ação de gesto está disponível.

Componentes interativos

Para ativar gestos em um controle interativo, como um botão, crie uma configuração especificando OneHandedGestureAction.Primary e aplique o modificador oneHandedGesture. Transmita o mesmo MutableInteractionSource para o controle e o modificador para que os eventos de gesto emitam feedback de pressão visual no controle.

Para ativar o indicador de gesto, crie e lembre-se de uma instância de OneHandedGestureClickIndicatorState. Em seguida, para acionar o feedback visual, chame showIndicator no callback onGestureAvailable fornecido pelo modificador oneHandedGesture, que sinaliza ao sistema que um evento de indicação ocorreu. Quando chamado, o componente substitui brevemente o conteúdo normal por uma animação de gesto.

var isPlaying by remember { mutableStateOf(false) }
val onClick = { isPlaying = !isPlaying }

val gestureConfig = rememberOneHandedGestureConfiguration(
    action = OneHandedGestureAction.Primary
)
val indicatorState = remember { OneHandedGestureClickIndicatorState() }
val coroutineScope = rememberCoroutineScope()
val interactionSource = remember { MutableInteractionSource() }

Button(
    onClick = onClick,
    interactionSource = interactionSource,
    modifier = Modifier
        .fillMaxWidth()
        .oneHandedGesture(
            gestureConfiguration = gestureConfig,
            interactionSource = interactionSource,
            onGestureLabel = if (isPlaying) "pause" else "play",
            onGestureAvailable = { coroutineScope.launch { indicatorState.showIndicator() } },
            onGesture = onClick
        )
) {
    OneHandedGestureClickIndicator(
        gestureConfiguration = gestureConfig,
        state = indicatorState
    ) {
        Text(if (isPlaying) "Pause" else "Play", modifier = Modifier.fillMaxWidth())
    }
}

Contêineres roláveis

Para telas ou listas roláveis, crie uma configuração especificando OneHandedGestureAction.Primary e aplique o modificador oneHandedGesture ao contêiner, chamando um auxiliar de rolagem, como scrollDown.

Para fornecer feedback visual para ações de rolagem, você pode usar o OneHandedGestureScrollIndicator. Esse componente funciona como um indicador de rolagem padrão que mostra a posição de rolagem, mas também pode indicar que um gesto de rolagem está disponível para o usuário. Esse indicador é normalmente transmitido ao slot scrollIndicator de um ScreenScaffold e é associado ao estado de um contêiner rolável, como um TransformingLazyColumn. Ele também observa um OneHandedGestureScrollIndicatorState para gerenciar as transições visuais.

Para acionar o feedback visual, chame showIndicator nesse estado, normalmente dentro do callback onGestureAvailable do modificador oneHandedGesture. Quando acionado, o indicador substitui temporariamente o estado visual padrão por uma sequência de animação de gesto para alertar o usuário.

val scrollState = rememberTransformingLazyColumnState()
val gestureConfig = rememberOneHandedGestureConfiguration(
    action = OneHandedGestureAction.Primary,
    priority = OneHandedGesturePriority.Scrollable
)
val indicatorState = remember(gestureConfig) { OneHandedGestureScrollIndicatorState() }
val coroutineScope = rememberCoroutineScope()

ScreenScaffold(
    scrollState = scrollState,
    scrollIndicator = {
        OneHandedGestureScrollIndicator(
            gestureConfiguration = gestureConfig,
            indicatorState = indicatorState,
            scrollState = scrollState,
            modifier = Modifier.align(Alignment.CenterEnd)
        )
    }
) { contentPadding ->
    TransformingLazyColumn(
        state = scrollState,
        contentPadding = contentPadding,
        modifier = Modifier
            .fillMaxSize()
            .oneHandedGesture(
                gestureConfiguration = gestureConfig,
                onGestureLabel = "scroll",
                onGestureAvailable = {
                    coroutineScope.launch { indicatorState.showIndicator() }
                },
                onGesture = { OneHandedGestureDefaults.scrollDown(scrollState) }
            )
    ) {
        items(10) { index ->
            Text("Item $index", modifier = Modifier.padding(8.dp))
        }
    }
}

Combinar vários gestos

É possível configurar um gesto de rolagem e um gesto de clique com a mesma ação principal adicionando gesturePriority ao objeto OneHandedGestureConfiguration:

  • OneHandedGesturePriority.Clickable (mais alta): atribua a controles interativos, como aqueles com o tipo Button ou Card, para que eles capturem gestos quando visíveis na tela.
  • OneHandedGesturePriority.Scrollable (média): atribua a contêineres roláveis ou pagináveis para que eles cedam a filhos clicáveis, mas rolem quando nenhum controle clicável estiver visível.
  • OneHandedGesturePriority.Unspecified (mais baixa): uma prioridade não atribuída. Esse é o valor padrão para um gesto que não tem uma priority definida.

Ao definir explicitamente priority = OneHandedGesturePriority.Clickable em um botão interno e priority = OneHandedGesturePriority.Scrollable na lista pai, o sistema pode mostrar esse comportamento de prioridade de gesto. Quando o usuário aciona a ação principal pelo gesto com uma mão, ele primeiro rola a lista para baixo até que o botão fique visível. Em seguida, ele captura a ação de clique do botão.

Testar e depurar gestos com o adb

É possível testar gestos com uma mão em um dispositivo físico ou emulador sem realizar movimentos físicos do pulso usando o Android Debug Bridge (adb) e o serviço do sistema IWearGestureService.

Ativar a simulação de gestos

  1. Verifique se o dispositivo Wear OS está executando o Wear OS 7 (nível 37 da API) e versões mais recentes.
  2. Se você estiver testando em um dispositivo físico que não está no pulso ou em um carregador, substitua o estado do sensor fora do corpo para que o dispositivo permaneça ativo:
adb shell cmd sensorservice set-off-body-state 0

Acionar eventos de gesto usando o adb

Para simular o gesto de pinça dupla (que é a ação Primary em relógios Pixel), execute o seguinte comando do shell adb:

adb shell cmd IWearGestureService gesture 1

Para simular o gesto de girar o pulso (que é a ação Dismiss em relógios Pixel), execute o seguinte comando do shell adb:

adb shell cmd IWearGestureService gesture 2

Redefinir o rastreamento de dicas de gestos

O sistema rastreia o histórico de interação do usuário e mostra dicas de gestos flutuantes com base na configuração de cadência global (como Sempre ou Diariamente). Ao depurar os indicadores de gesto do app, redefina esse histórico de rastreamento para que as dicas apareçam novamente no pacote:

adb shell cmd IWearGestureService hint clear <your_package_name>

Para redefinir o estado do sensor fora do corpo quando terminar o teste:

adb shell cmd sensorservice reset-off-body-state

Outros recursos

Para orientações de design sobre quando e onde usar gestos com uma mão, consulte Gestos com uma mão.