Blog do Desenvolvedor Android: Adicione gestos de uma mão ao seu aplicativo Wear OS

Postado por Chiara Chiappini, Engenheira de Relações com Desenvolvedores, Android Developer Relations

Gestos de uma mão oferecem uma maneira conveniente e sem contato para os usuários interagirem com seus relógios, permitindo que eles realizem ações-chave usando apenas a mão em que o dispositivo está sendo usado.

Introduzidos pela primeira vez no Pixel Watch com Wear OS 6.1, os gestos de uma mão tornaram as interações rápidas fáceis, como iniciar e parar um temporizador, aceitar chamadas e controlar mídia.

Agora, com o Wear OS 7, estamos expandindo essa funcionalidade com um novo framework de Gestos que permite aos OEMs mapear gestos para ações primárias e descartes, e uma API para trazer controle por gestos à comunidade de desenvolvedores.

A partir da versão 1.7 beta do Compose for Wear OS, você pode integrar o controle por gestos em seus aplicativos Wear Compose de forma transparente. Para usar essa versão, atualize sua dependência Wear Compose para:

androidx.wear.compose:compose-material3:1.7.0-beta01

Direcionando a interação com uma mão

O framework de gestos de uma mão é projetado em torno de dois padrões principais de interação que permitem aos usuários tomar ação sem tocar na tela:

• Ação primária, que no Pixel Watch está mapeada para um gesto duplo de pinça: esta ação deve ser mapeada para a tarefa mais importante em um contexto dado. Por exemplo, os usuários podem realizar esse gesto para tirar uma foto em um aplicativo de câmera, iniciar/parar um temporizador ou aceitar uma chamada recebida.
• Ação de descarte, que no Pixel Watch está mapeada para um gesto de rotação do pulso: esta ação é mapeada para voltar ao sistema por padrão e fornece uma maneira intuitiva de fechar telas interrompidoras ou retornar à tela inicial do relógio. Ela pode ser substituída em casos específicos, como silenciar uma chamada recebida.

Esses gestos estão atualmente disponíveis no Pixel Watch 3 e versões posteriores, e o framework de gestos Wear OS está disponível para todos os fabricantes de dispositivos Wear OS adotarem.

Confira nossa nova orientação de design para integrar gestos de uma mão em seu aplicativo Wear.

Integrando gestos com Compose no Wear OS

Para fornecer suporte contínuo a gestos no Wear OS 7, estamos introduzindo um novo Modifier.oneHandedGesture que você pode aplicar a qualquer composável interativo existente para torná-lo consciente de gestos.

A implementação de gestos com Compose no Wear OS requer estes passos:

1. Defina a configuração do gesto. Comece usando rememberOneHandedGestureConfiguration para definir a natureza da interação. Esta configuração determina o comportamento básico fornecendo um GestureAction (por exemplo, rastreando um pinçar primário ou um deslizar de pulso).
2. Inicialize o estado do indicador. Dependendo do componente da IU, inicialize um objeto de estado específico, como OneHandedGestureClickIndicatorState para botões ou OneHandedGestureScrollIndicatorState para listas roláveis. Este estado é usado para coordenar a retroalimentação visual entre o modificador de detecção de gestos e os indicadores visuais da IU, gerenciando visibilidade, cronograma e animações de forma transparente.
3. Aplique Modifier.oneHandedGesture ao seu componente interativo. Você passará sua configuração e estado, e fornecerá callbacks padrão: onGestureAvailable para ativar o sinal visual quando o sistema preparar o gesto, e onGesture para executar a sua ação quando o gesto ocorrer.

O exemplo a seguir mostra como esses três passos se traduzem em código ao configurar um IconButton:

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

OutlinedIconButton(
    onClick = onPlayPauseButtonClicked,
    modifier = Modifier.touchTargetAwareSize(IconButtonDefaults.LargeButtonSize)
        .oneHandedGesture(
            gestureConfiguration = gestureConfig,
            interactionSource = interactionSource,
            onGestureLabel = "play or pause",
            onGestureAvailable = { 
                coroutineScope.launch { indicatorState.showIndicator() } 
            },
            onGesture = onPlayPauseButtonClicked,
        ),
) {
    // conteúdo do botão vai aqui
    // Consulte a seção "Guided discovery with gesture indicators" deste post para recomendações sobre adicionar um indicador de gesto.
}

O GestureAction.Primary também pode ser usado para rolar quando o conteúdo é o objetivo final da jornada do usuário ou há um botão com ação de gesto fora da tela que o usuário pode rolar até. Alguns exemplos incluem:

• Rolar por uma notificação para visualizar o conteúdo e/ou iniciar uma resposta (disponível em TransformingLazyColumn e ScalingLazyColumn).
• Paginar através de métricas de treino ou outros conteúdos que não exigem que o usuário toque para continuar a jornada do usuário (disponível em  HorizontalPager e VerticalPager).

val scrollGestureConfig = rememberOneHandedGestureConfiguration(action = GestureAction.Primary)
val scrollIndicatorState = remember { OneHandedGestureScrollIndicatorState() }
val coroutineScope = rememberCoroutineScope()

TransformingLazyColumn(
    state = scrollState,
    contentPadding = contentPadding,
    modifier = Modifier
        .fillMaxSize()
        .oneHandedGesture(
            gestureConfiguration = scrollGestureConfig,
            onGestureLabel = "scroll",
            onGestureAvailable = { 
                coroutineScope.launch { scrollIndicatorState.showIndicator() } 
            },
            onGesture = { OneHandedGestureDefaults.scrollDown(scrollState) }
        )
) {
    // conteúdo da lista vai aqui
    // Consulte a seção "Guided discovery with gesture indicators" deste post para recomendações sobre adicionar um indicador de gesto.
}

Descoberta guiada com indicadores de gestos

Para ajudar os usuários a aprender quais gestos estão disponíveis, os indicadores de gesto funcionam como dicas para descobrir quais gestos estão disponíveis em uma tela.

Essas dicas fornecem sinais animados que informam aos usuários onde eles podem realizar um gesto. O quadro gerencia a cadência e a aparência dessas dicas, garantindo que sejam úteis sem ser intrusivas. Configurações do sistema permitem que os usuários alterem a frequência para algo menos frequente, se desejado.

Para integrar com dicas, a API fornece os seguintes componentes de indicador de gesto:

O exemplo a seguir mostra como usar o OneHandedGestureClickIndicator para um Button. Veja outro exemplo de uso do OneHandedGestureScrollIndicator em nossa orientação.

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

OutlinedIconButton(
    onClick = onPlayPauseButtonClicked,
    modifier = Modifier.touchTargetAwareSize(IconButtonDefaults.LargeButtonSize)
        .oneHandedGesture(
            gestureConfiguration = gestureConfig,
            interactionSource = interactionSource,
            onGestureLabel = "play or pause",
            onGestureAvailable = { 
                coroutineScope.launch { indicatorState.showIndicator() } 
            },
            onGesture = onPlayPauseButtonClicked,
        ),
) {
    OneHandedGestureClickIndicator(
        gestureConfiguration = gestureConfig,
        indicatorState = indicatorState,
    ) {
        val icon = if (playerUiModel.playbackState.isPlaying) Icons.Filled.Pause else Icons.Filled.PlayArrow
        Icon(icon, contentDescription = "Play or Pause")
    }
}

Já estamos vendo uma adoção precoce dessas APIs por parceiros como o Spotify, que está usando gestos com uma mão para tornar o controle de música mais fluido em movimento. Ao adotar o Modifier.oneHandedGesture em seu aplicativo Wear OS, o Spotify permite aos usuários tocar ou pausar sua música com a ação principal do gesto, que nos dispositivos Pixel Watch é o gesto de pinça dupla. Essa ação dispara o mesmo comportamento que o botão físico play/pause e o usuário não precisa tocar na tela.

Aplicativo Spotify com integração de gestos

Adicione gestos com uma mão ao seu aplicativo

Você pode começar a experimentar com gestos com uma mão hoje na versão beta 1.7 do Compose para Wear OS.

Asegure-se de que o seu aplicativo está rodando no Wear OS 7, que fornece o suporte da plataforma subjacente para detecção de gestos. Confira nossa nova orientação sobre gestos com uma mão para ver como você pode começar a construir experiências mais convenientes para seus usuários.