Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Cử chỉ bằng một tay với Compose

Phiên bản Material của Compose cho Wear OS

Trên Wear OS 7 (cấp độ API 37) trở lên, khung cử chỉ một tay cùng với một API thuộc Compose cho Wear OS cho phép người dùng tương tác với ứng dụng của bạn mà không cần chạm.

Mặc dù ban đầu được hỗ trợ trên các thiết bị Pixel Watch (Pixel Watch 3 trở lên), nhưng khung này được cung cấp cho tất cả OEM. Bằng cách áp dụng API này, tính năng hỗ trợ cử chỉ của ứng dụng sẽ tự động mở rộng trên toàn hệ sinh thái khi tính năng hỗ trợ phần cứng mở rộng.

Để giúp người dùng khám phá các cử chỉ có sẵn mà không làm lộn xộn giao diện người dùng, khung Wear OS cung cấp các chỉ báo cử chỉ động. Những gợi ý trực quan này làm nổi bật vị trí có thể thực hiện cử chỉ, trong khi hệ thống tự động quản lý tần suất hiển thị và tần suất tắt tiếng theo lựa chọn ưu tiên của người dùng.

Các cử chỉ và thao tác được hỗ trợ

Khung cử chỉ của Wear OS hỗ trợ hai loại cử chỉ:

Thao tác chính (Chụm hai lần): Liên kết với thao tác chính trên màn hình, chẳng hạn như trả lời cuộc gọi hoặc bật/tắt chế độ phát nội dung nghe nhìn.
Thao tác đóng (Xoay cổ tay): Liên kết với thao tác điều hướng lùi, đóng hộp thoại hoặc huỷ lời nhắc.

Định cấu hình cử chỉ trong Compose

Mặc dù API cử chỉ một tay có thể cải thiện giao diện người dùng, nhưng bạn cần lưu ý rằng một số phần cứng và OEM không hỗ trợ các cử chỉ này. Nếu API phát hiện thấy ứng dụng của bạn đang chạy trên một trong những thiết bị không được hỗ trợ này, thì thư viện sẽ tự động không hoạt động mà không ảnh hưởng đến các hoạt động tương tác chạm tiêu chuẩn.

Giống như các hành vi chuẩn của Compose, bạn có thể bật cử chỉ một tay trên các thành phần giao diện người dùng bằng đối tượng sửa đổi. Bạn định cấu hình cử chỉ của ứng dụng theo hành động cần thực hiện (chính hoặc đóng) và gestureId để phối hợp với lựa chọn ưu tiên của người dùng ở cấp hệ thống, chẳng hạn như nhịp độ hiển thị gợi ý và tắt tiếng tần suất. Bạn thể hiện cấu hình này bằng cách tạo một đối tượng OneHandedGestureConfiguration; bạn nên sử dụng hàm rememberOneHandedGestureConfiguration để tạo đối tượng này. OneHandedGestureConfiguration cũng là nơi bạn có thể cung cấp mức độ ưu tiên của cử chỉ.

Hàm rememberOneHandedGestureConfiguration theo dõi nhật ký tương tác của người dùng trên các thành phần kết hợp mà không hiển thị trạng thái ứng dụng. Sau khi ứng dụng của bạn đã tạo cấu hình, ứng dụng đó sẽ truyền cấu hình đến Modifier.oneHandedGesture trên composable tương tác của bạn.

Để giúp người dùng khám phá các cử chỉ có sẵn, thư viện cung cấp phương thức OneHandedGestureClickIndicator. Phương thức này đóng vai trò là một trình bao bọc thay thế nội dung cơ bản để cho người dùng biết rằng có thể thực hiện một thao tác cử chỉ.

Thành phần tương tác

Để bật cử chỉ trên một thành phần điều khiển tương tác như nút, hãy tạo một cấu hình chỉ định OneHandedGestureAction.Primary và áp dụng đối tượng sửa đổi oneHandedGesture. Truyền cùng một MutableInteractionSource cho cả thành phần điều khiển và đối tượng sửa đổi để các sự kiện cử chỉ phát ra phản hồi trực quan khi nhấn vào thành phần điều khiển.

Để bật chỉ báo cử chỉ, hãy tạo và ghi nhớ một thực thể của OneHandedGestureClickIndicatorState. Sau đó, để kích hoạt phản hồi bằng hình ảnh, hãy gọi showIndicator trong lệnh gọi lại onGestureAvailable do đối tượng sửa đổi oneHandedGesture cung cấp. Thao tác này sẽ báo hiệu cho hệ thống biết rằng một sự kiện chỉ báo đã xảy ra. Sau khi được gọi, thành phần này sẽ nhanh chóng thay thế nội dung thông thường bằng ảnh động cử chỉ.

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())
    }
}OneHandedGestures.kt

Vùng chứa có thể cuộn

Đối với màn hình hoặc danh sách có thể cuộn, hãy tạo một cấu hình chỉ định OneHandedGestureAction.Primary và áp dụng đối tượng sửa đổi oneHandedGesture cho vùng chứa, gọi một trình trợ giúp cuộn như scrollDown.

Để cung cấp phản hồi bằng hình ảnh cho các thao tác cuộn, bạn có thể sử dụng OneHandedGestureScrollIndicator. Thành phần này hoạt động như một chỉ báo cuộn chuẩn cho biết vị trí cuộn, nhưng cũng có thể cho biết rằng người dùng có thể thực hiện cử chỉ cuộn. Chỉ báo này thường được truyền đến vùng scrollIndicator của ScreenScaffold và được kết hợp với trạng thái của một vùng chứa có thể cuộn, chẳng hạn như TransformingLazyColumn. Mã này cũng quan sát một OneHandedGestureScrollIndicatorState để quản lý các hiệu ứng chuyển đổi hình ảnh.

Để kích hoạt phản hồi bằng hình ảnh, hãy gọi showIndicator ở trạng thái này, thường là bên trong lệnh gọi lại onGestureAvailable của đối tượng sửa đổi oneHandedGesture. Sau khi được kích hoạt, chỉ báo sẽ tạm thời thay thế trạng thái hình ảnh chuẩn bằng một chuỗi ảnh động cử chỉ để cảnh báo người dùng.

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))
        }
    }
}OneHandedGestures.kt

Kết hợp nhiều cử chỉ

Bạn có thể định cấu hình cả cử chỉ cuộn và cử chỉ nhấp bằng cùng một hành động chính bằng cách thêm gesturePriority vào đối tượng OneHandedGestureConfiguration:

OneHandedGesturePriority.Clickable (cao nhất): Chỉ định cho các thành phần điều khiển tương tác (chẳng hạn như các thành phần có loại Button hoặc Card) để các thành phần này ghi lại cử chỉ khi xuất hiện trên màn hình.
OneHandedGesturePriority.Scrollable (trung bình): Chỉ định cho các vùng chứa có thể cuộn hoặc có thể phân trang để các vùng chứa này nhường chỗ cho các thành phần con có thể nhấp, nhưng cuộn khi không có thành phần điều khiển nào có thể nhấp.
OneHandedGesturePriority.Unspecified (thấp nhất): Mức độ ưu tiên chưa được chỉ định. Đây là giá trị mặc định cho một cử chỉ không có priority.

Bằng cách đặt rõ ràng priority = OneHandedGesturePriority.Clickable trên một nút bên trong và priority = OneHandedGesturePriority.Scrollable trên danh sách mẹ, hệ thống có thể cho thấy hành vi ưu tiên cử chỉ này. Khi người dùng kích hoạt hành động chính bằng cử chỉ một tay, trước tiên, cử chỉ này sẽ cuộn danh sách xuống cho đến khi nút hiển thị, sau đó ghi lại hành động nhấp vào nút.

Kiểm thử và gỡ lỗi cử chỉ bằng ADB

Bạn có thể kiểm thử cử chỉ một tay trên thiết bị thực hoặc trình mô phỏng mà không cần thực hiện các chuyển động cổ tay thực tế bằng cách sử dụng Cầu gỡ lỗi Android (adb) và dịch vụ hệ thống IWearGestureService.

Bật tính năng mô phỏng cử chỉ

Trước khi mô phỏng cử chỉ bằng ADB, hãy định cấu hình chế độ cài đặt thiết bị và ghi đè quy tắc ràng buộc:

Xác minh rằng thiết bị Wear OS của bạn đang chạy Wear OS 7 (cấp độ API 37) trở lên:
```
adb shell getprop ro.build.version.sdk
```
Nếu bạn đang kiểm thử trên một thiết bị thực không đeo trên cổ tay hoặc đang đặt trên bộ sạc, hãy ghi đè quy tắc ràng buộc không đeo trên người để khung cử chỉ vẫn hoạt động:
```
adb shell cmd IWearGestureService override-constraints offbody-state
```

Kích hoạt sự kiện cử chỉ bằng ADB

Để mô phỏng cử chỉ chụm ngón tay hai lần (là thao tác Primary trên Pixel Watch), hãy chạy lệnh shell adb sau:

adb shell cmd IWearGestureService gesture DoublePinch

Để mô phỏng cử chỉ Xoay cổ tay (là thao tác Dismiss trên đồng hồ Pixel), hãy chạy lệnh shell ADB sau:

adb shell cmd IWearGestureService gesture WristTurn

Đặt lại tính năng theo dõi gợi ý cử chỉ

Hệ thống theo dõi nhật ký tương tác của người dùng và hiển thị gợi ý cử chỉ nổi dựa trên chế độ cài đặt nhịp độ chung (chẳng hạn như Luôn luôn hoặc Hằng ngày). Khi gỡ lỗi chỉ báo cử chỉ của ứng dụng, hãy đặt lại nhật ký theo dõi này để gợi ý xuất hiện lại cho gói của bạn:

Trên các bản dựng hoặc trình mô phỏng userdebug:

adb shell cmd IWearGestureService hint clear <your_package_name>

Trên bản dựng bán lẻ (user):

Trên các thiết bị thương mại không có quyền truy cập gốc, hint clear sẽ bị chặn theo quyền của hệ thống. Xoá dữ liệu địa phương của ứng dụng để đặt lại tính năng khám phá gợi ý:
```
adb shell pm clear <your_package_name>
```

Khôi phục các quy tắc ràng buộc mặc định

Cách đặt lại tất cả các chế độ ghi đè quy tắc ràng buộc gỡ lỗi khi bạn kiểm thử xong:

adb shell cmd IWearGestureService override-constraints reset

Khắc phục sự cố chèn cử chỉ

Nếu ứng dụng của bạn không nhận được cử chỉ mô phỏng:

Kiểm tra để đảm bảo màn hình đồng hồ đang bật và hoạt động. Khung cử chỉ không gửi cử chỉ đến các ứng dụng khi màn hình tắt hoặc ở chế độ môi trường xung quanh. Để bật màn hình bằng ADB, hãy chạy lệnh:
```
adb shell input keyevent KEYCODE_WAKEUP
```
Kiểm tra xem ứng dụng của bạn có được đăng ký làm người đăng ký cử chỉ đang hoạt động và hiện đang giữ tiêu điểm cửa sổ hay không:
```
adb shell cmd IWearGestureService get-active-gestures -readable
```
Khi màn hình cử chỉ của ứng dụng ở nền trước và màn hình đang bật, lệnh này sẽ trả về [DoublePinch] hoặc [DoublePinch, WristTurn]. Nếu hệ thống trả về một danh sách trống ([]), hãy kiểm tra xem cửa sổ của bạn có tiêu điểm hay không hoặc liệu các quy tắc ràng buộc khi không đeo thiết bị có đang chặn việc kích hoạt hay không.
Kiểm tra trạng thái dịch vụ cử chỉ nội bộ và mã thông báo của người đăng ký đang hoạt động:
```
adb shell dumpsys IWearGestureService
```

Tài nguyên khác

Để biết hướng dẫn thiết kế về thời điểm và vị trí sử dụng cử chỉ một tay, hãy xem phần Cử chỉ một tay.

Đề xuất cho bạn

Lưu ý: văn bản có đường liên kết sẽ hiện khi JavaScript tắt
Hướng dẫn thiết kế cử chỉ bằng một tay

Cử chỉ bằng một tay với Compose Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.