實體按鈕

穿戴式裝置通常含有多個實體按鈕 (也稱為 Stem)。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() 方法。此方法傳回的按鈕數量包含電源按鈕，因此若傳回的值大於一，表示有多功能按鈕可供使用。如要準確計算可指派的多功能按鈕數量，請將按鈕總數扣除一，因為第一個按鈕一律是電源按鈕。

按下按鈕動作的的按鍵碼

每個按鈕都對應至 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 參考資料」。