物理按钮

可穿戴设备通常包含多个物理按钮，也称为 _杆_。Wear OS 设备始终至少有一个按钮：电源按钮。除此之外，可能还存在零个或多个多功能按钮。

在您的应用中，您可以将多功能按钮分配给操作。例如，健身应用可以使用多功能按钮启动或暂停锻炼。

注意：Wear OS 3.0 为操作系统保留了两个按钮，而 Wear OS 2.0 只保留了一个按钮。这减少了您可以为其分配操作的按钮数量。

有关合适的用例和设计注意事项，请查看 Wear OS 设计原则.

本指南介绍如何检索有关设备上可用多功能按钮的信息，以及如何处理按钮按下事件。

按钮元数据

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

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

按钮数量

要找出设备上有多少个按钮可用，请使用 WearableButtons.getButtonCount() 方法。此方法包括电源按钮，因此如果方法返回的值大于 1，则表明有可用的多功能按钮。要获得可分配多功能按钮的准确数量，请从计数中减去 1，因为第一个按钮始终是电源按钮。

按钮按下事件的键码

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

按钮 KeyEvent
多功能按钮 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
}

Java

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)
    }
}

Java

@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 参考。