实体按钮

穿戴式设备上通常会有多个实体按钮，也称为表把按钮。所有 Wear OS 设备都至少有一个按钮，即电源按钮。 除此之外，还可能会有多个多功能按钮（也可能没有）。 某些设备还提供实体侧面旋钮。

在您的应用中，您可以为操作分配多功能按钮，以便在应用处于前台时使用。例如，健身应用可以使用多功能按钮开始或暂停锻炼：

图 1. 显示多功能按钮的 Wear OS 健身应用。

如需了解合适的用例和设计注意事项，请参阅 Wear OS 设计原则。

本文档介绍了如何检索设备上可用的多功能按钮的相关信息，以及如何处理按钮按下动作。

按钮元数据

如需获取有关设备上按钮的更多信息，请使用 Wear Input AndroidX 库中定义的 API。在应用模块的 build.gradle 文件中添加以下依赖项：

dependencies {
implementation "androidx.wear:wear-input:1.2.0"
}

按钮数量

如需确定设备上可用的按钮数量，请使用 WearableButtons.getButtonCount() 方法。此方法的搜索范围包括电源按钮，因此，如果此方法返回的值大于 1，则表示有多功能按钮可供使用。将此返回的值减去 1 即为可分配的多功能按钮的准确总数，因为第一个按钮始终是电源按钮。

按钮按下动作的键码

每个按钮都将映射到 KeyEvent 类中的一个 int 常量，如下表所示：

按钮	KeyEvent
多功能按钮 1	KEYCODE_STEM_1
多功能按钮 2	KEYCODE_STEM_2
多功能按钮 3	KEYCODE_STEM_3

以下示例代码显示如何获取可用的按钮计数：

val count = WearableButtons.getButtonCount(context)

if (count > 1) {
    Log.d(TAG, "More than one button available")
}

val buttonInfo = WearableButtons.getButtonInfo(
    activity,
    KeyEvent.KEYCODE_STEM_1
)

if (buttonInfo == null) {
    // KEYCODE_STEM_1 is unavailable
    Log.d(TAG, "KEYCODE_STEM_1 not available")
} else {
    // KEYCODE_STEM_1 is present on the device
    Log.d(TAG, "KEYCODE_STEM_1 is present on the device")
}
HardwareButtonsActivity.kt

处理按钮按下动作

您的应用可以处理多个可能的按钮键码，如下所示：

• KEYCODE_STEM_1。
• KEYCODE_STEM_2。

您的应用可以接收这些键码，并将其转换为特定的应用内操作。

如需处理按钮按下动作，请实现 onKeyDown() 方法。

例如，以下实现可响应某个按钮按下动作，以控制应用中的操作：

override fun onKeyDown(keyCode: Int, event: KeyEvent?): Boolean {
    return if (event?.repeatCount == 0) {
        when (keyCode) {
            KeyEvent.KEYCODE_STEM_1 -> {
                Log.d(TAG, "KEYCODE_STEM_1 pressed")
                true
            }
            KeyEvent.KEYCODE_STEM_2 -> {
                Log.d(TAG, "KEYCODE_STEM_2 pressed")
                true
            }
            else -> {
                super.onKeyDown(keyCode, event)
            }
        }
    } else {
        super.onKeyDown(keyCode, event)
    }
}
HardwareButtonsActivity.kt

确定按钮位置

AndroidX 库提供了两种描述按钮位置的方法：

• WearableButtons.getButtonLabel()：返回一个本地化后的字符串，描述设备上按钮的常规位置。
• WearableButtons.getButtonIcon()：返回一个图标，表示按钮在设备上的常规位置。

如果这些 API 不符合您的应用需求，您还可以使用 WearableButtons.getButtonInfo() API 获取按钮在屏幕上的位置，并以更加个性化的方式对其进行处理。如需详细了解这些 API，请参阅 Wear API 参考文档。