Gesty jedną ręką w przypadku funkcji Tworzenie

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

Początkowo platforma była obsługiwana na zegarkach Pixel Watch (Pixel Watch 3 i nowszych), ale jest dostępna dla wszystkich producentów OEM. Dzięki temu interfejsowi API obsługa gestów w Twojej aplikacji będzie automatycznie dostosowywać się do ekosystemu w miarę rozszerzania obsługi sprzętowej.

Aby pomóc użytkownikom odkrywać dostępne gesty bez zaśmiecania interfejsu, platforma Wear OS udostępnia animowane wskaźniki gestów. Te wskazówki wizualne pokazują, 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

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

  • Główne działanie (podwójne uszczypnięcie): odpowiada głównemu działaniu na ekranie, np. odebraniu połączenia lub przełączeniu odtwarzania multimediów.
  • Odrzucanie działania (obrót nadgarstka): odpowiada nawigacji wstecznej, zamykaniu 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 będzie wykonywać żadnych działań, nie wpływając na standardowe interakcje dotykowe.

Podobnie jak w przypadku standardowych zachowań Compose, gesty wykonywane jedną ręką w elementach interfejsu włącza się za pomocą modyfikatorów. Konfigurujesz gesty aplikacji zgodnie z działaniem, które ma być wykonywane – podstawowym lub odrzucającym – oraz gestureId, aby dostosować je do preferencji użytkownika na poziomie systemu, takich jak częstotliwość wyświetlania wskazówek i wyciszanie częstotliwości. Konfigurację tę wyrażasz, tworząc obiekt OneHandedGestureConfiguration. Zalecamy użycie funkcji rememberOneHandedGestureConfiguration. WOneHandedGestureConfiguration tym miejscu możesz też określić priorytet gestu.

Funkcja rememberOneHandedGestureConfiguration śledzi historię interakcji użytkownika w różnych kompozycjach bez ujawniania stanu aplikacji. Gdy aplikacja utworzy konfigurację, powinna przekazać ją do funkcji Modifier.oneHandedGesture w interaktywnym komponencie.

Aby pomóc użytkownikom w odkryciu dostępnych gestów, biblioteka udostępnia metodę OneHandedGestureClickIndicator. Ta metoda działa jako element opakowujący, który zastępuje podstawową treść, aby wskazać użytkownikowi, że dostępne jest działanie gestu.

Komponenty interaktywne

Aby włączyć gesty w przypadku interaktywnego elementu sterującego, takiego jak przycisk, utwórz konfigurację określającą OneHandedGestureAction.Primary i zastosuj modyfikator oneHandedGesture. Przekaż ten sam MutableInteractionSource do elementu sterującego i modyfikatora, aby zdarzenia gestów emitowały wizualne informacje o naciśnięciu do elementu sterującego.

Aby włączyć wskaźnik gestów, utwórz instancję klasy OneHandedGestureClickIndicatorState i zapamiętaj ją. Następnie, aby wywołać wizualną informację zwrotną, wywołaj showIndicator w wywołaniu zwrotnym onGestureAvailable udostępnionym przez modyfikator oneHandedGesture, który sygnalizuje systemowi, że wystąpiło zdarzenie wskazujące. Po wywołaniu komponent na chwilę zastępuje swoją normalną zawartość 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())
    }
}

Kontenery z możliwością przewijania

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 przekazać wizualną informację zwrotną dotyczącą przewijania, możesz użyć OneHandedGestureScrollIndicator. Ten komponent działa jak standardowy wskaźnik przewijania, który pokazuje pozycję przewijania, ale może też wskazywać, że użytkownik może przewijać. Ten wskaźnik jest zwykle przekazywany do slotu scrollIndicator w ScreenScaffold i jest powiązany ze stanem kontenera z możliwością przewijania, np. TransformingLazyColumn. Obserwuje też parametr OneHandedGestureScrollIndicatorState, aby zarządzać przejściami wizualnymi.

Aby wywołać wizualne potwierdzenie, wywołaj showIndicator w tym stanie – zwykle w funkcji zwrotnej onGestureAvailable modyfikatora oneHandedGesture. Po aktywowaniu wskaźnik tymczasowo zastępuje swój standardowy stan wizualny sekwencją animacji gestów, aby powiadomić 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 z tym samym działaniem podstawowym, dodając gesturePriority do obiektu OneHandedGestureConfiguration:

  • OneHandedGesturePriority.Clickable (najwyższy): przypisz do interaktywnych elementów sterujących, np. tych typu Button lub Card, aby rejestrowały gesty, gdy są widoczne na ekranie.
  • OneHandedGesturePriority.Scrollable (średni): przypisz do kontenerów z możliwością przewijania lub stronicowania, aby ustępowały miejsca elementom podrzędnym, które można kliknąć, ale przewijały się, gdy nie jest widoczny żaden element sterujący, który można kliknąć.
  • OneHandedGesturePriority.Unspecified (najniższy): priorytet nieprzypisany. Jest to wartość domyślna gestu, który nie ma ustawionego parametru priority.

Jeśli w przypadku wewnętrznego przycisku ustawisz wartość priority = OneHandedGesturePriority.Clickable, a w przypadku jego nadrzędnej listy – priority = OneHandedGesturePriority.Scrollable, system może wyświetlać to zachowanie związane z priorytetem gestu. Gdy użytkownik wywoła działanie podstawowe za pomocą gestu wykonywanego jedną ręką, najpierw przewinie listę w dół, aż przycisk będzie widoczny, a potem zarejestruje kliknięcie przycisku.

Testowanie i debugowanie gestów za pomocą ADB

Gesty wykonywane jedną ręką możesz testować na urządzeniu fizycznym lub emulatorze bez wykonywania fizycznych ruchów nadgarstkiem za pomocą Android Debug Bridge (adb) i usługi systemowej IWearGestureService.

Włącz symulację gestów

Zanim zaczniesz symulować gesty za pomocą ADB, skonfiguruj ustawienia urządzenia i zastąpienia ograniczeń:

  1. Sprawdź, czy na urządzeniu z Wear OS działa Wear OS 7 (poziom API 37) lub nowszy:

    adb shell getprop ro.build.version.sdk

  2. Jeśli testujesz na urządzeniu fizycznym, które nie jest na Twoim nadgarstku lub jest umieszczone na ładowarce, zastąp ograniczenie dotyczące braku kontaktu z ciałem, aby platforma gestów pozostała aktywna:

    adb shell cmd IWearGestureService override-constraints offbody-state

Aktywowanie zdarzeń gestów za pomocą ADB

Aby zasymulować gest podwójnego uszczypnięcia (czyli działanie Primary na zegarkach Pixel), uruchom to polecenie powłoki ADB:

adb shell cmd IWearGestureService gesture DoublePinch

Aby zasymulować gest obrotu nadgarstka (czyli działanie Dismiss na zegarkach Pixel Watch), uruchom to polecenie powłoki ADB:

adb shell cmd IWearGestureService gesture WristTurn

Resetowanie śledzenia wskazówek dotyczących gestów

System śledzi historię interakcji użytkownika i wyświetla pływające wskazówki dotyczące gestów na podstawie globalnego ustawienia częstotliwości (np. Zawsze lub Codziennie). Podczas debugowania wskaźników gestów w aplikacji zresetuj historię śledzenia, aby ponownie wyświetlać wskazówki dotyczące pakietu:

  • W przypadku kompilacji userdebug lub emulatorów:

    adb shell cmd IWearGestureService hint clear <your_package_name>

  • W przypadku kompilacji na potrzeby sprzedaży detalicznej (user):

    Na urządzeniach komercyjnych bez dostępu do roota funkcja hint clear jest blokowana przez uprawnienia systemowe. Wyczyść dane lokalne aplikacji, aby zresetować wykrywanie podpowiedzi:

    adb shell pm clear <your_package_name>

Przywracanie domyślnych ograniczeń

Aby po zakończeniu testowania zresetować wszystkie zastąpienia ograniczeń debugowania:

adb shell cmd IWearGestureService override-constraints reset

Rozwiązywanie problemów z wstrzykiwaniem gestów

Jeśli aplikacja nie otrzymuje symulowanych gestów:

  1. Sprawdź, czy ekran zegarka jest aktywny i włączony. Platforma gestów nie wysyła gestów do aplikacji, gdy ekran jest wyłączony lub w trybie otoczenia. Aby wybudzić wyświetlacz za pomocą ADB, uruchom to polecenie:

    adb shell input keyevent KEYCODE_WAKEUP

  2. Sprawdź, czy aplikacja jest zarejestrowana jako aktywny subskrybent gestów i czy ma obecnie fokus okna:

    adb shell cmd IWearGestureService get-active-gestures -readable

    Gdy ekran gestów aplikacji jest na pierwszym planie i jest aktywny, to polecenie zwraca wartość [DoublePinch] lub [DoublePinch, WristTurn]. Jeśli zwrócona zostanie pusta lista ([]), sprawdź, czy okno jest aktywne lub czy ograniczenia dotyczące odległości od ciała nie blokują aktywacji.

  3. Sprawdź stan wewnętrznej usługi gestów i aktywne tokeny subskrybentów:

    adb shell dumpsys IWearGestureService

Dodatkowe materiały

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