Wear OS 7(API 수준 37) 이상에서는 한 손 동작 프레임워크와 Wear OS용 Compose의 일부인 API를 통해 사용자가 터치 없이 앱과 상호작용할 수 있습니다.
이 프레임워크는 처음에는 Pixel Watch 기기(Pixel Watch 3 이상)에서 지원되지만 모든 OEM에서 사용할 수 있습니다. 이 API를 채택하면 하드웨어 지원이 확대됨에 따라 앱의 동작 지원이 생태계 전반에서 자동으로 확장됩니다.
UI를 복잡하게 만들지 않으면서 사용자가 사용 가능한 동작을 찾을 수 있도록 Wear OS 프레임워크는 애니메이션 동작 표시기를 제공합니다. 이러한 시각적 힌트는 동작을 실행할 수 있는 위치를 강조 표시하며, 시스템은 사용자 환경설정에 따라 표시 주기와 음소거 빈도를 자동으로 관리합니다.
지원되는 동작 및 작업
Wear OS 동작 프레임워크는 두 가지 동작 작업 유형을 지원합니다.
- 기본 작업: 전화 받기 또는 미디어 재생 전환과 같은 화면의 기본 작업에 매핑됩니다. Pixel Watch 기기에서 이 작업은 두 번 꼬집기 동작에 매핑됩니다.
- 닫기 작업: 뒤로 탐색, 대화상자 닫기 또는 프롬프트 취소에 매핑됩니다. Pixel Watch 기기에서 이 작업은 손목 돌리기 동작에 매핑됩니다.
Compose에서 동작 구성
한 손 동작 API는 UI를 개선할 수 있지만 일부 하드웨어와 OEM은 이러한 동작을 지원하지 않는다는 점에 유의해야 합니다. API가 앱이 이러한 지원되지 않는 기기 중 하나에서 실행 중임을 감지하면 라이브러리는 표준 터치 상호작용에 영향을 주지 않고 자동으로 작동하지 않습니다.
표준 Compose 동작과 마찬가지로 수정자를 사용하여 UI 요소에서 한 손 동작을 사용 설정합니다. 실행할 작업(기본 또는 닫기)과 gestureId에 따라 앱의 동작을 구성하여 힌트 표시 주기 및 빈도 음소거와 같은 시스템 수준 사용자 환경설정과 조정합니다. OneHandedGestureConfiguration 객체를 만들어 이 구성을 표현합니다. rememberOneHandedGestureConfiguration 함수를 사용하여 만드는 것이 좋습니다. OneHandedGestureConfiguration는 동작 우선순위를 제공할 수 있는 위치이기도 합니다.
rememberOneHandedGestureConfiguration 함수는 애플리케이션 상태를 노출하지 않고 리컴포지션 전반에서 사용자 상호작용 기록을 추적합니다. 앱에서 구성을 만들면 대화형 컴포저블의 Modifier.oneHandedGesture에 구성을 전달해야 합니다.
사용자가 사용 가능한 동작을 찾을 수 있도록 라이브러리는 OneHandedGestureClickIndicator 메서드를 제공합니다. 이 메서드는 기본 콘텐츠를 대체하여 사용자에게 동작 액션을 사용할 수 있음을 나타내는 래퍼 역할을 합니다.
상호작용 구성요소
버튼과 같은 대화형 컨트롤에서 동작을 사용 설정하려면 OneHandedGestureAction.Primary를 지정하는 구성을 만들고 oneHandedGesture 수정자를 적용합니다. 동작 이벤트가 컨트롤에 시각적 누르기 피드백을 내보내도록 컨트롤과 수정자 모두에 동일한 MutableInteractionSource를 전달합니다.
동작 표시기를 사용 설정하려면 OneHandedGestureClickIndicatorState 인스턴스를 만들고 기억합니다. 그런 다음 시각적 피드백을 트리거하려면 oneHandedGesture 수정자가 제공하는 onGestureAvailable 콜백 내에서 showIndicator를 호출합니다. 그러면 표시 이벤트가 발생했음을 시스템에 알립니다. 호출되면 구성요소는 일반 콘텐츠를 동작 애니메이션으로 잠시 대체합니다.
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()) } }
스크롤 가능한 컨테이너
스크롤 가능한 화면 또는 목록의 경우 OneHandedGestureAction.Primary를 지정하는 구성을 만들고 oneHandedGesture 수정자를 컨테이너에 적용하여 scrollDown와 같은 스크롤 도우미를 호출합니다.
스크롤 작업에 시각적 피드백을 제공하려면 OneHandedGestureScrollIndicator를 사용하면 됩니다. 이 구성요소는 스크롤 위치를 보여주는 표준 스크롤 표시기로 작동하지만, 사용자에게 스크롤 동작을 사용할 수 있음을 나타낼 수도 있습니다. 이 표시기는 일반적으로 ScreenScaffold의 scrollIndicator 슬롯에 전달되며 스크롤 가능한 컨테이너(예: TransformingLazyColumn)의 상태와 결합됩니다. 또한 OneHandedGestureScrollIndicatorState를 관찰하여 시각적 전환을 관리합니다.
시각적 피드백을 트리거하려면 이 상태에서 showIndicator를 호출합니다. 일반적으로 oneHandedGesture 수정자의 onGestureAvailable 콜백 내에서 호출합니다.
트리거되면 표시기가 표준 시각적 상태를 동작 애니메이션 시퀀스로 일시적으로 대체하여 사용자에게 알립니다.
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)) } } }
여러 동작 결합
OneHandedGestureConfiguration 객체에 gesturePriority를 추가하여 동일한 기본 작업으로 스크롤 동작과 클릭 동작을 모두 구성할 수 있습니다.
OneHandedGesturePriority.Clickable(가장 높음):Button또는Card유형과 같은 대화형 컨트롤에 할당하여 화면에 표시될 때 동작을 캡처합니다.OneHandedGesturePriority.Scrollable(중간): 스크롤 가능하거나 페이지로 나눌 수 있는 컨테이너에 할당하여 클릭 가능한 하위 요소에 양보하지만 클릭 가능한 컨트롤이 표시되지 않으면 스크롤합니다.OneHandedGesturePriority.Unspecified(가장 낮음): 할당되지 않은 우선순위입니다.priority가 설정되지 않은 동작의 기본값입니다.
내부 버튼에 priority = OneHandedGesturePriority.Clickable를, 상위 목록에 priority = OneHandedGesturePriority.Scrollable를 명시적으로 설정하면 시스템에서 이 동작 우선순위 동작을 표시할 수 있습니다.
사용자가 한 손 동작으로 기본 작업을 트리거하면 먼저 버튼이 표시될 때까지 목록을 아래로 스크롤한 다음 버튼의 클릭 작업을 캡처합니다.
ADB로 동작 테스트 및 디버그
Android 디버그 브리지(adb)와 IWearGestureService 시스템 서비스를 사용하여 실제 손목 움직임을 수행하지 않고도 실제 기기나 에뮬레이터에서 한 손 동작을 테스트할 수 있습니다.
동작 시뮬레이션 사용 설정
ADB를 사용하여 동작을 시뮬레이션하기 전에 기기 설정 및 제약 조건 재정의를 구성합니다.
Wear OS 기기에서 Wear OS 7(API 수준 37) 이상을 실행 중인지 확인합니다.
adb shell getprop ro.build.version.sdk손목에 착용하지 않거나 충전기에 올려놓은 실제 기기에서 테스트하는 경우 동작 프레임워크가 활성 상태로 유지되도록 오프바디 제약 조건을 재정의합니다.
adb shell cmd IWearGestureService override-constraints offbody-state
ADB를 사용하여 동작 이벤트 트리거
각 동작 작업에 매핑된 실제 동작은 기기 제조업체 또는 에뮬레이터 이미지에 따라 다를 수 있으므로 먼저 시스템에 지원되는 작업-동작 매핑을 쿼리합니다.
adb shell cmd IWearGestureService get-supported-actions -readable
이 명령어는 local(시계) 및 remote 구독자의 PrimaryAction 및 DismissAction에 매핑된 실제 동작을 보여주는 JSON 객체를 출력합니다. 예를 들어 Pixel Watch 또는 Wear OS 에뮬레이터에서 다음을 실행합니다.
{
"remote": {
"PrimaryAction": "DoublePinch",
"DismissAction": "WristTurn"
},
"local": {
"PrimaryAction": "DoublePinch",
"DismissAction": "WristTurn"
}
}
"local"에 나열된 동작 이름을 사용하여 워치용 앱의 동작을 시뮬레이션합니다.
PrimaryAction에 매핑된 동작(예:DoublePinch)을 시뮬레이션하려면 다음 ADB 셸 명령어를 실행합니다.adb shell cmd IWearGestureService gesture DoublePinchDismissAction에 매핑된 동작(예:WristTurn)을 시뮬레이션하려면 다음 ADB 셸 명령어를 실행합니다.adb shell cmd IWearGestureService gesture WristTurn
동작 힌트 추적 재설정
시스템은 사용자 상호작용 기록을 추적하고 전역 주기 설정(예: Always 또는 Daily)에 따라 플로팅 동작 힌트를 표시합니다. 앱의 동작 표시기를 디버깅할 때 이 추적 기록을 재설정하여 패키지에 힌트가 다시 표시되도록 합니다.
userdebug빌드 또는 에뮬레이터:adb shell cmd IWearGestureService hint clear <your_package_name>소매(
user) 빌드:루트 액세스 권한이 없는 상용 기기에서는 시스템 권한에 의해
hint clear가 차단됩니다. 앱의 로컬 데이터를 삭제하여 힌트 검색을 재설정합니다.adb shell pm clear <your_package_name>
기본 제약 조건 복원
테스트를 완료한 후 모든 디버그 제약 조건 재정의를 재설정하려면 다음 안내를 따르세요.
adb shell cmd IWearGestureService override-constraints reset
동작 삽입 문제 해결
앱이 시뮬레이션된 동작을 수신하지 않는 경우:
워치 화면이 켜져 있는지 확인합니다. 동작 프레임워크는 화면이 꺼져 있거나 대기 모드에 있는 동안 애플리케이션에 동작을 전달하지 않습니다. ADB를 사용하여 디스플레이를 절전 모드 해제하려면 다음을 실행합니다.
adb shell input keyevent KEYCODE_WAKEUP앱이 활성 동작 구독자로 등록되어 있고 현재 창 포커스를 보유하고 있는지 확인합니다.
adb shell cmd IWearGestureService get-active-gestures -readable앱의 동작 화면이 포그라운드에 있고 화면이 켜져 있으면 이 명령어는 구독한 작업의 활성 동작(예:
[DoublePinch]또는[DoublePinch, WristTurn])을 반환합니다. 빈 목록([])이 반환되면 창에 포커스가 있는지 또는 미착용 제약 조건이 활성화를 차단하는지 확인하세요.내부 동작 서비스 상태 및 활성 구독자 토큰을 검사합니다.
adb shell dumpsys IWearGestureService
추가 리소스
한 손 동작을 언제 어디서 사용해야 하는지에 관한 디자인 안내는 한 손 동작을 참고하세요.
추천 서비스
- 참고: JavaScript가 사용 중지되어 있으면 링크 텍스트가 표시됩니다.
- 한 손 동작 디자인 가이드