실제 버튼
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
일반적으로 웨어러블 기기에는 스템이라고도 하는 실제 버튼이 여러 개 있습니다. Wear OS 기기에는 항상 버튼이 최소한 한 개(전원 버튼) 있습니다. 그 외에도 다기능 버튼이 0개 이상 있을 수 있습니다.
앱에서 다기능 버튼을 작업에 할당할 수 있습니다. 예를 들어 피트니스 앱에서는 다기능 버튼을 사용하여 운동을 시작하거나 일시중지할 수 있습니다.
참고: Wear OS 3.0에는 OS용 버튼이 두 개 있지만 Wear OS 2.0에는 버튼이 하나만 있습니다. 따라서 작업을 할당할 수 있는 버튼 수가 줄어듭니다.
이 가이드에서는 기기에서 사용 가능한 다기능 버튼에 관한 정보를 검색하는 방법과 버튼 누르기를 처리하는 방법을 설명합니다.
기기에서 버튼에 관한 추가 정보를 가져오려면 Wear 입력 AndroidX 라이브러리에 정의된 API를 사용하세요. 앱 모듈의 build.gradle
파일에 다음 종속 항목을 추가합니다.
dependencies {
implementation "androidx.wear:wear-input:1.0.0"
}
기기에서 사용 가능한 버튼 수를 확인하려면
WearableButtons.getButtonCount()
메서드를 사용하세요. 이 메서드에는 전원 버튼이 포함되어 있으므로 메서드에서 1보다 큰 값을 반환하면 사용할 수 있는 다기능 버튼이 있는 것입니다. 할당 가능한 다기능 버튼의 정확한 개수를 가져오려면 개수에서 1을 빼세요. 첫 번째 버튼은 항상 전원 버튼이기 때문입니다.
각 버튼은 다음 표에 나와 있는 것처럼 KeyEvent
클래스의 int
상수에 매핑됩니다.
버튼
|
키 이벤트
|
다기능 버튼 1
|
KEYCODE_STEM_1
|
다기능 버튼 2
|
KEYCODE_STEM_2
|
다기능 버튼 3
|
KEYCODE_STEM_3
|
다음 코드 예는 사용 가능한 버튼 개수를 확인하는 방법을 보여줍니다.
Kotlin
val count = WearableButtons.getButtonCount(context)
if (count > 1) {
// There are multifunction buttons available
}
val buttonInfo = WearableButtons.getButtonInfo(activity, KeyEvent.KEYCODE_STEM_1)
if (buttonInfo == null) {
// KEYCODE_STEM_1 is unavailable
} else {
// KEYCODE_STEM_1 is present on the device
}
자바
int count = WearableButtons.getButtonCount(context);
if (count > 1) {
// There are multifunction buttons available
}
WearableButtons.ButtonInfo buttonInfo =
WearableButtons.getButtonInfo(activity, KeyEvent.KEYCODE_STEM_1);
if (buttonInfo == null) {
// KEYCODE_STEM_1 is unavailable
} else {
// KEYCODE_STEM_1 is present on the device
}
앱에서 처리할 수 있는 버튼 키 코드에는 여러 가지가 있습니다.
-
KEYCODE_STEM_1
-
KEYCODE_STEM_2
-
KEYCODE_STEM_3
앱은 이러한 키 코드를 받아 특정 인앱 작업으로 변환할 수 있습니다.
버튼 누르기를 처리하려면 onKeyDown()
메서드를 구현합니다.
예를 들어 다음 구현은 버튼 누르기에 응답하여 앱의 작업을 제어합니다.
Kotlin
// Activity
override fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {
return if (event.repeatCount == 0) {
when (keyCode) {
KeyEvent.KEYCODE_STEM_1 -> {
// Do stuff
true
}
KeyEvent.KEYCODE_STEM_2 -> {
// Do stuff
true
}
KeyEvent.KEYCODE_STEM_3 -> {
// Do stuff
true
}
else -> {
super.onKeyDown(keyCode, event)
}
}
} else {
super.onKeyDown(keyCode, event)
}
}
자바
@Override
// Activity
public boolean onKeyDown(int keyCode, KeyEvent event){
if (event.getRepeatCount() == 0) {
if (keyCode == KeyEvent.KEYCODE_STEM_1) {
// Do stuff
return true;
} else if (keyCode == KeyEvent.KEYCODE_STEM_2) {
// Do stuff
return true;
} else if (keyCode == KeyEvent.KEYCODE_STEM_3) {
// Do stuff
return true;
}
}
return super.onKeyDown(keyCode, event);
}
버튼 위치 확인
AndroidX 라이브러리는 버튼의 위치를 설명하는 두 가지 메서드를 제공합니다.
참고: 버튼과 그 기능을 설명할 때 텍스트 설명자를 사용하지 않는 것이 좋습니다. 대신 시각적 표시기를 사용하세요. 그러나 버튼에 관한 설명을 제공하는 것이 더 나은 경우도 있을 수 있습니다.
위의 메서드는 간단한 설명을 위한 것으로, 이러한 API가 앱의 요구사항에 맞지 않는 경우 WearableButtons.getButtonInfo()
API를 사용하여 화면상의 버튼 위치를 가져와 좀 더 맞춤설정된 방식으로 이를 처리할 수도 있습니다. API에 관한 자세한 내용은 Wear API 참조를 확인하세요.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-26(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-26(UTC)"],[],[],null,["# Physical buttons\n\nA wearable device typically contains multiple physical buttons, also known as _stems_. Wear OS\ndevices always have, at minimum, one button: the power button. Beyond that, zero or more\nmultifunction buttons might be present.\n\n\nIn your app, you can assign multifunction buttons to actions. For example, a fitness app\nmight start or pause a workout using multifunction buttons:\n\n**Note:** Wear OS 3.0 reserves two buttons for the OS, while\nWear OS 2.0 reserves only one. This reduces the number of buttons you can assign\nactions to. \n\nFor suitable use cases and design considerations, review the\n[Wear OS design principles](/training/wearables/design).\n\n\nThis guide describes how to retrieve information about available multifunction buttons on\na device and how to process button presses.\n\nButton metadata\n---------------\n\n\nTo get extra information about the buttons on a device, use the API defined in the\n[Wear Input](/reference/androidx/wear/input/package-summary) AndroidX library. Add the\nfollowing dependency in your app module's `build.gradle` file: \n\n```groovy\ndependencies {\nimplementation \"androidx.wear:wear-input:1.0.0\"\n}\n```\n\n### Number of buttons\n\n\nTo find out how many buttons are available on the device, use the\n[`WearableButtons.getButtonCount()`](/reference/android/support/wearable/input/WearableButtons#getButtonCount(android.content.Context)) method. This method includes the power button,\nso if the method returns a value greater than one, then there are multifunction buttons available\nfor use. To get an accurate count of assignable multifunction buttons, subtract\none from the count, since the first button is always the power button.\n\n### Keycodes for button presses\n\n\nEach button is mapped to an `int` constant from the [KeyEvent](https://developer.android.com/reference/android/view/KeyEvent.html)\nclass, as shown in the following table:\n\n| Button | KeyEvent |\n|------------------------|------------------|\n| Multifunction button 1 | `KEYCODE_STEM_1` |\n| Multifunction button 2 | `KEYCODE_STEM_2` |\n| Multifunction button 3 | `KEYCODE_STEM_3` |\n\n\nThe following example code shows how to get the available button\ncount: \n\n### Kotlin\n\n```kotlin\nval count = WearableButtons.getButtonCount(context)\n\nif (count \u003e 1) {\n // There are multifunction buttons available\n}\n\nval buttonInfo = WearableButtons.getButtonInfo(activity, KeyEvent.KEYCODE_STEM_1)\n\nif (buttonInfo == null) {\n // KEYCODE_STEM_1 is unavailable\n} else {\n // KEYCODE_STEM_1 is present on the device\n}\n```\n\n### Java\n\n```java\nint count = WearableButtons.getButtonCount(context);\n\nif (count \u003e 1) {\n // There are multifunction buttons available\n}\n\nWearableButtons.ButtonInfo buttonInfo =\n WearableButtons.getButtonInfo(activity, KeyEvent.KEYCODE_STEM_1);\n\nif (buttonInfo == null) {\n // KEYCODE_STEM_1 is unavailable\n} else {\n // KEYCODE_STEM_1 is present on the device\n}\n```\n\nHandle button presses\n---------------------\n\n\nThere are a number of possible button keycodes that your app can handle:\n\n- `KEYCODE_STEM_1`\n- `KEYCODE_STEM_2 `\n- `KEYCODE_STEM_3`\n\n\nYour app can receive these key codes and convert them to specific in-app actions.\n\n\nTo handle a button press, implement the\n[`onKeyDown()`](/reference/android/app/Activity#onKeyDown(int,%20android.view.KeyEvent)) method.\n\n\nFor example, this implementation responds to button presses to control\nactions in an app: \n\n### Kotlin\n\n```kotlin\n// Activity\noverride fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {\n return if (event.repeatCount == 0) {\n when (keyCode) {\n KeyEvent.KEYCODE_STEM_1 -\u003e {\n // Do stuff\n true\n }\n KeyEvent.KEYCODE_STEM_2 -\u003e {\n // Do stuff\n true\n }\n KeyEvent.KEYCODE_STEM_3 -\u003e {\n // Do stuff\n true\n }\n else -\u003e {\n super.onKeyDown(keyCode, event)\n }\n }\n } else {\n super.onKeyDown(keyCode, event)\n }\n}\n```\n\n### Java\n\n```java\n@Override\n// Activity\npublic boolean onKeyDown(int keyCode, KeyEvent event){\n if (event.getRepeatCount() == 0) {\n if (keyCode == KeyEvent.KEYCODE_STEM_1) {\n // Do stuff\n return true;\n } else if (keyCode == KeyEvent.KEYCODE_STEM_2) {\n // Do stuff\n return true;\n } else if (keyCode == KeyEvent.KEYCODE_STEM_3) {\n // Do stuff\n return true;\n }\n }\n return super.onKeyDown(keyCode, event);\n}\n```\n\nDetermine the button positions\n------------------------------\n\n\nThe AndroidX Library provides two methods that describe the location of a button:\n\n- [`WearableButtons.getButtonLabel()`](/reference/android/support/wearable/input/WearableButtons#getButtonLabel(android.content.Context, int)) returns a localized string describing the general placement of the button on the device.\n- [`WearableButtons.getButtonIcon()`](/reference/android/support/wearable/input/WearableButtons#getButtonIcon(android.content.Context, int)) returns an icon representing the general placement of the button on the device.\n\n**Note:** We recommend that you avoid using textual descriptors\nwhen describing buttons and their functions. Use visual indicators instead. However, there may\nbe some cases where describing a button makes more sense.\n\n\nThe previous methods were designed for simple descriptions. If these APIs don't suit your app's\nneeds, you can also use the `WearableButtons.getButtonInfo()` API to get the\nlocation of the button on the screen and handle it in a more customized way. For more\ninformation on the APIs, see the\n[Wear API reference](/reference/android/support/wearable/input/package-summary)."]]