Gesti con una mano con Scrivi

A partire da Wear OS 7 (livello API 37), un framework di gesti a una mano, insieme a un'API che fa parte di Compose per Wear OS, consente agli utenti di interagire con la tua app senza toccarla.

Sebbene inizialmente supportato sui dispositivi Pixel Watch (Pixel Watch 3 e modelli successivi), il framework è disponibile per tutti gli OEM. Adottando questa API, il supporto dei gesti della tua app viene scalato automaticamente nell'ecosistema man mano che il supporto hardware si espande.

Per aiutare gli utenti a scoprire i gesti disponibili senza ingombrare l'interfaccia utente, il framework di Wear OS fornisce indicatori di gesti animati. Questi suggerimenti visivi evidenziano dove è possibile eseguire un gesto, mentre il sistema gestisce automaticamente la cadenza di visualizzazione e la frequenza di disattivazione dell'audio in base alle preferenze dell'utente.

Gesti e azioni supportati

Il framework dei gesti di Wear OS supporta due tipi di gesti:

  • Azione principale (doppio pizzico): esegue l'azione principale su una schermata, ad esempio rispondere a una chiamata o attivare/disattivare la riproduzione dei contenuti multimediali.
  • Azione di chiusura (rotazione del polso): esegue la navigazione all'indietro, chiude una finestra di dialogo o annulla un prompt.

Configurare i gesti in Compose

Sebbene l'API dei gesti a una mano possa migliorare l'interfaccia utente, è importante tenere presente che alcuni hardware e OEM non supportano questi gesti. Se l'API rileva che la tua app è in esecuzione su uno di questi dispositivi non supportati, la libreria diventa automaticamente autonoma senza influire sulle interazioni touch standard.

Come per i comportamenti standard di Compose, puoi attivare i gesti a una mano sugli elementi dell'interfaccia utente utilizzando i modificatori. Configura i gesti della tua app in base all'azione da eseguire (principale o di chiusura) e a un gestureId per coordinarti con le preferenze dell'utente a livello di sistema, ad esempio la cadenza di visualizzazione dei suggerimenti e la frequenza di disattivazione dell'audio. Per esprimere questa configurazione, crea un OneHandedGestureConfiguration oggetto. Ti consigliamo di utilizzare la rememberOneHandedGestureConfiguration funzione per crearlo. In OneHandedGestureConfiguration puoi anche specificare la priorità dei gesti.

La funzione rememberOneHandedGestureConfiguration tiene traccia della cronologia delle interazioni utente tra le ricomposizioni senza esporre lo stato dell'applicazione. Una volta creata la configurazione, l'app deve passarla a Modifier.oneHandedGesture nel composable interattivo.

Per aiutare gli utenti a scoprire i gesti disponibili, la libreria fornisce il metodo OneHandedGestureClickIndicator. Questo metodo funge da wrapper che sostituisce i contenuti sottostanti per indicare all'utente che è disponibile un'azione di gesto.

Componenti interattivi

Per attivare i gesti su un controllo interattivo come un pulsante, crea una configurazione che specifichi OneHandedGestureAction.Primary e applica il modificatore oneHandedGesture. Passa lo stesso MutableInteractionSource sia al controllo sia al modificatore in modo che gli eventi di gesto emettano un feedback visivo di pressione sul controllo.

Per attivare l'indicatore di gesto, crea e memorizza un'istanza di OneHandedGestureClickIndicatorState. Poi, per attivare il feedback visivo, chiama showIndicator all'interno del callback onGestureAvailable fornito dal modificatore oneHandedGesture, che segnala al sistema che si è verificato un evento di indicazione. Una volta chiamato, il componente sostituisce brevemente i contenuti normali con un'animazione di 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())
    }
}

Container scorrevoli

Per le schermate o gli elenchi scorrevoli, crea una configurazione che specifichi OneHandedGestureAction.Primary e applica il modificatore oneHandedGesture al container, chiamando un helper di scorrimento come scrollDown.

Per fornire un feedback visivo per le azioni di scorrimento, puoi utilizzare il OneHandedGestureScrollIndicator. Questo componente funziona come un indicatore di scorrimento standard che mostra la posizione di scorrimento, ma può anche indicare che è disponibile un gesto di scorrimento per l'utente. Questo indicatore viene in genere passato allo slot scrollIndicator di un ScreenScaffold ed è accoppiato allo stato di un container scorrevole, ad esempio un TransformingLazyColumn. Osserva anche un OneHandedGestureScrollIndicatorState per gestire le transizioni visive.

Per attivare il feedback visivo, chiama showIndicator in questo stato, in genere all'interno del callback onGestureAvailable del modificatore oneHandedGesture. Una volta attivato, l'indicatore sostituisce temporaneamente il suo stato visivo standard con una sequenza di animazione di gesto per avvisare l'utente.

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))
        }
    }
}

Combinare più gesti

Puoi configurare sia un gesto di scorrimento sia un gesto di clic con la stessa azione principale aggiungendo gesturePriority all'oggetto OneHandedGestureConfiguration:

  • OneHandedGesturePriority.Clickable (massima): assegna ai controlli interattivi, ad esempio quelli di tipo Button o Card, in modo che acquisiscano i gesti quando sono visibili sullo schermo.
  • OneHandedGesturePriority.Scrollable (media): assegna ai container scorrevoli o impaginabili in modo che cedano ai figli cliccabili, ma scorrono quando non è visibile alcun controllo cliccabile.
  • OneHandedGesturePriority.Unspecified (minima): una priorità non assegnata. Questo è il valore predefinito per un gesto che non ha un priority impostato.

Impostando esplicitamente priority = OneHandedGesturePriority.Clickable su un pulsante interno e priority = OneHandedGesturePriority.Scrollable sull'elenco principale, il sistema può mostrare questo comportamento di priorità dei gesti. Quando l'utente attiva l'azione principale con il gesto a una mano, l'elenco scorre prima verso il basso finché il pulsante non è visibile. Poi, acquisisce l'azione di clic del pulsante.

Testare ed eseguire il debug dei gesti con ADB

Puoi testare i gesti a una mano su un dispositivo fisico o un emulatore senza eseguire movimenti fisici del polso utilizzando Android Debug Bridge (adb) e il servizio di sistema IWearGestureService.

Attivare la simulazione dei gesti

  1. Verifica che sul dispositivo Wear OS sia in esecuzione Wear OS 7 (livello API 37) e versioni successive.
  2. Se esegui il test su un dispositivo fisico che non è al polso o su un caricabatterie, sostituisci lo stato del sensore off-body in modo che il dispositivo rimanga attivo:
adb shell cmd sensorservice set-off-body-state 0

Attivare gli eventi di gesto utilizzando ADB

Per simulare il gesto Doppio pizzico (che è l'azione Primary su Pixel Watch), esegui il seguente comando della shell ADB:

adb shell cmd IWearGestureService gesture 1

Per simulare il gesto Rotazione del polso (che è l'azione Dismiss su Pixel Watch), esegui il seguente comando della shell ADB:

adb shell cmd IWearGestureService gesture 2

Reimpostare il monitoraggio dei suggerimenti sui gesti

Il sistema tiene traccia della cronologia delle interazioni utente e mostra i suggerimenti sui gesti mobili in base all'impostazione della cadenza globale (ad esempio Sempre o Ogni giorno). Quando esegui il debug degli indicatori di gesto della tua app, reimposta questa cronologia di monitoraggio in modo che i suggerimenti vengano visualizzati di nuovo per il tuo pacchetto:

adb shell cmd IWearGestureService hint clear <your_package_name>

Per reimpostare lo stato del sensore off-body al termine del test:

adb shell cmd sensorservice reset-off-body-state

Risorse aggiuntive

Per indicazioni sulla progettazione su quando e dove utilizzare i gesti a una mano, consulta Gesti a una mano.