Gesty jedną ręką w przypadku funkcji Tworzenie

Od Wear OS 7 (poziom API 37) framework gestów wykonywanych jedną ręką oraz interfejs API, który jest częścią Compose na Wear OS, umożliwiają użytkownikom interakcję z aplikacją bez dotykania ekranu.

Framework jest początkowo obsługiwany na urządzeniach Pixel Watch (Pixel Watch 3 i nowszych), ale jest dostępny dla wszystkich producentów OEM. Dzięki zastosowaniu tego interfejsu API obsługa gestów w aplikacji automatycznie skaluje się w całym ekosystemie w miarę rozszerzania obsługi sprzętu.

Aby pomóc użytkownikom w odkrywaniu dostępnych gestów bez zaśmiecania interfejsu, framework Wear OS udostępnia animowane wskaźniki gestów. Te wizualne wskazówki informują, gdzie można wykonać gest, a system automatycznie zarządza częstotliwością ich wyświetlania i wyciszania zgodnie z preferencjami użytkownika.

Obsługiwane gesty i działania

Framework gestów Wear OS obsługuje 2 typy gestów:

  • Działanie główne (podwójne ściśnięcie): odpowiada głównemu działaniu na ekranie, np. odebraniu połączenia lub przełączaniu odtwarzania multimediów.
  • Działanie odrzucenia (obrót nadgarstka): odpowiada nawigacji wstecz, odrzuceniu okna lub anulowaniu prompta.

Konfigurowanie gestów w Compose

Chociaż interfejs API gestów wykonywanych jedną ręką może ulepszyć interfejs użytkownika, pamiętaj, że niektóre urządzenia i producenci OEM nie obsługują tych gestów. Jeśli interfejs API wykryje, że aplikacja działa na jednym z tych nieobsługiwanych urządzeń, biblioteka automatycznie nie wykonuje żadnych działań, nie wpływając na standardowe interakcje dotykowe.

Podobnie jak w przypadku standardowych zachowań Compose, gesty wykonywane jedną ręką włączasz w elementach interfejsu za pomocą modyfikatorów. Konfigurujesz gesty aplikacji zgodnie z działaniem, które ma zostać wykonane – głównym lub odrzucenia – oraz gestureId, aby koordynować je z preferencjami użytkownika na poziomie systemu, takimi jak częstotliwość wyświetlania podpowiedzi i wyciszania. Tę konfigurację wyrażasz, tworząc obiekt OneHandedGestureConfiguration. Zalecamy użycie do tego funkcji rememberOneHandedGestureConfiguration. W OneHandedGestureConfiguration możesz też określić priorytet gestu.

Funkcja rememberOneHandedGestureConfiguration śledzi historię interakcji użytkownika w ramach ponownych kompozycji bez ujawniania stanu aplikacji. Gdy aplikacja utworzy konfigurację, powinna przekazać ją do Modifier.oneHandedGesture w interaktywnym komponencie.

Aby pomóc użytkownikom w odkrywaniu dostępnych gestów, biblioteka udostępnia metodę OneHandedGestureClickIndicator. Ta metoda działa jako otoka, która zastępuje swoją podstawową treść, aby poinformować użytkownika, że dostępne jest działanie gestu.

Komponenty interaktywne

Aby włączyć gesty w interaktywnym komponencie, takim jak przycisk, utwórz konfigurację określającą OneHandedGestureAction.Primary i zastosuj modyfikator oneHandedGesture. Przekaż ten sam MutableInteractionSource zarówno do komponentu, jak i do modyfikatora, aby zdarzenia gestów emitowały wizualne informacje o naciśnięciu na komponent.

Aby włączyć wskaźnik gestu, utwórz i zapamiętaj instancję OneHandedGestureClickIndicatorState. Następnie, aby wywołać wizualne informacje, wywołaj showIndicator w wywołaniu zwrotnym onGestureAvailable udostępnianym przez modyfikator oneHandedGesture, który sygnalizuje systemowi, że wystąpiło zdarzenie wskazujące. Po wywołaniu komponent na krótko zastępuje swoją normalną treść animacją gestu.

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

Przewijane kontenery

W przypadku ekranów lub list z możliwością przewijania utwórz konfigurację określającą OneHandedGestureAction.Primary i zastosuj modyfikator oneHandedGesture do kontenera, wywołując pomocnika przewijania, np. scrollDown.

Aby zapewnić wizualne informacje o działaniach przewijania, możesz użyć OneHandedGestureScrollIndicator. Ten komponent działa jako standardowy wskaźnik przewijania, który pokazuje pozycję przewijania, ale może też wskazywać, że użytkownik ma do dyspozycji gest przewijania. Ten wskaźnik jest zwykle przekazywany do slotu scrollIndicator elementu ScreenScaffold i jest powiązany ze stanem przewijanego kontenera, np. TransformingLazyColumn. Obserwuje też OneHandedGestureScrollIndicatorState, aby zarządzać swoimi wizualnymi przejściami.

Aby wywołać wizualne informacje, wywołaj showIndicator w tym stanie – zwykle w wywołaniu zwrotnym onGestureAvailable modyfikatora oneHandedGesture. Po wywołaniu wskaźnik tymczasowo zastępuje swój standardowy stan wizualny sekwencją animacji gestu, aby ostrzec użytkownika.

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

Łączenie wielu gestów

Możesz skonfigurować zarówno gest przewijania, jak i gest kliknięcia za pomocą tego samego działania głównego, dodając gesturePriority do obiektu OneHandedGestureConfiguration:

  • OneHandedGesturePriority.Clickable (najwyższy): przypisz do interaktywnych komponentów – np. tych typu Button lub Card – aby przechwytywały gesty, gdy są widoczne na ekranie.
  • OneHandedGesturePriority.Scrollable (średni): przypisz do przewijanych lub stronicowanych kontenerów, aby ustępowały klikalnym elementom podrzędnym, ale przewijały się, gdy nie jest widoczny żaden klikalny komponent.
  • OneHandedGesturePriority.Unspecified (najniższy): nieprzypisany priorytet. Jest to wartość domyślna gestu, który nie ma ustawionego priority.

Dzięki wyraźnemu ustawieniu priority = OneHandedGesturePriority.Clickable na wewnętrznym przycisku i priority = OneHandedGesturePriority.Scrollable na liście nadrzędnej system może wyświetlać to zachowanie priorytetu gestu. Gdy użytkownik wywoła działanie główne za pomocą gestu wykonywanego jedną ręką, system najpierw przewinie listę w dół, aż przycisk będzie widoczny. Następnie przechwyci działanie kliknięcia przycisku.

Testowanie i debugowanie gestów za pomocą ADB

Możesz testować gesty wykonywane jedną ręką na urządzeniu fizycznym lub emulatorze bez wykonywania fizycznych ruchów nadgarstka, używając Android Debug Bridge (adb) i usługi systemowej IWearGestureService.

Włączanie symulacji gestów

  1. Sprawdź, czy na urządzeniu z Wear OS działa Wear OS 7 (poziom API 37) lub nowszy.
  2. Jeśli testujesz na urządzeniu fizycznym, które nie jest na nadgarstku ani na ładowarce, zastąp stan czujnika poza ciałem, aby urządzenie pozostało aktywne:
adb shell cmd sensorservice set-off-body-state 0

Wywoływanie zdarzeń gestów za pomocą ADB

Aby zasymulować gest podwójnego ściśnięcia (który jest działaniem Primary na zegarkach Pixel), uruchom to polecenie powłoki ADB:

adb shell cmd IWearGestureService gesture 1

Aby zasymulować gest obrotu nadgarstka (który jest działaniem Dismiss na zegarkach Pixel), uruchom to polecenie powłoki ADB:

adb shell cmd IWearGestureService gesture 2

Resetowanie śledzenia podpowiedzi dotyczących gestów

System śledzi historię interakcji użytkownika i wyświetla pływające podpowiedzi dotyczące gestów na podstawie globalnego ustawienia częstotliwości (np. Zawsze lub Codziennie). Podczas debugowania wskaźników gestów aplikacji zresetuj tę historię śledzenia, aby podpowiedzi ponownie pojawiały się w przypadku Twojej paczki:

adb shell cmd IWearGestureService hint clear <your_package_name>

Aby po zakończeniu testowania zresetować stan czujnika poza ciałem:

adb shell cmd sensorservice reset-off-body-state

Dodatkowe materiały

Wskazówki dotyczące projektowania, kiedy i gdzie używać gestów wykonywanych jedną ręką, znajdziesz w artykule Gesty wykonywane jedną ręką.