在 Wear OS 上使用 Jetpack Compose

Compose for Wear OS 和 Compose for Mobile 十分類似，但也有一些關鍵差異。本指南說明兩者之間的相似與不同之處。

Compose for Wear OS 屬於 Android Jetpack，正如您使用的其他 Wear Jetpack 程式庫，這個項目的用意是協助加快編寫程式碼的過程。建議您以此方法為 Wear OS 應用程式建構使用者介面。

如果您對 Jetpack Compose 工具包的使用方式不太熟悉，請參閱 Compose 課程。行動裝置專用的 Compose 有許多開發原則都適用於 Compose for Wear OS。如要進一步瞭解宣告式 UI 架構的一般優點，請參閱「為什麼要選擇使用 Compose」。如果想進一步瞭解 Compose for Wear OS，請參閱 Compose for Wear OS 課程以及 GitHub 的 Wear OS 範例存放區。

在 Wear OS 上使用 Jetpack Compose 的 Material Design

Wear OS 上的 Jetpack Compose 提供 Material 2.5 的實作項目，可協助您設計更引人入勝的應用程式體驗。Wear OS 上的 Material Design 元件是以 Wear Material 主題設定為基礎建構而成。這種主題設定是系統化的方式，可用來自訂 Material Design，更準確地反映產品品牌。

相容性

Compose for Wear OS 可在支援 Wear OS 3.0 (API 級別 30) 的手錶，以及使用 Wear OS 2.0 (API 級別 25 以上) 的手錶上運作。使用 1.4 版的 Compose for Wear OS 時，必須使用 1.7 版的 androidx.compose 程式庫和 Kotlin 1.9.0。您可以使用 BOM 對應和 Compose 對應 Kotlin 的相容性清單，檢查 Compose 相容性。

途徑

Compose for Wear OS 可讓您在 Wear OS 建構應用程式時更加得心應手。詳情請參閱「應用程式」一節。請使用內建元件，建立符合 Wear OS 規範的使用者體驗。如要進一步瞭解這些元件，請參閱設計指南。

設定

搭配 Wear OS 使用 Jetpack Compose 的方法和其他 Android 專案使用 Jetpack Compose 的方式非常類似。主要的差別在於 Jetpack Compose for Wear 增加了 Wear 專用的程式庫，可讓您更輕鬆地建立手錶專屬的使用者介面。有些元件會和非 Wear 版本的元件使用相同的名稱，例如 androidx.wear.compose.material.Button 和 androidx.compose.material.Button。

在 Android Studio 建立新的應用程式

如要建立包含 Jetpack Compose 的新專案，請按照下列步驟操作：

  1. 如果您位於「Welcome to Android Studio」視窗，請按一下「Start a new Android Studio project」。如果您已開啟 Android Studio 專案，請依序點選選單列中的「File」>「New」>「Import Sample」。
  2. 搜尋「Compose for Wear」，然後選取「Compose for Wear OS Starter」。
  3. 在「Configure your project」視窗中執行以下操作：
    1. 設定「Application name」。
    2. 選擇範例的「Project location」。
  4. 按一下「Finish」。
  5. 確認專案的 build.gradle 檔案設定無誤，如「Gradle 屬性檔案」中所述。

您現在可以用 Compose for Wear OS 開發應用程式了。

Jetpack Compose 工具包依附元件

如要將 Jetpack Compose 與 Wear OS 搭配使用，您需要在應用程式的 build.gradle 檔案中加入 Jetpack Compose 工具包依附元件。與 Wear OS 相關的大部分依附元件變更都位於頂層架構層，在下圖中以紅框標示。

<img 'foundation',="" 'material',="" 'runtime'.="" 'ui',="" 2="" 4="" a="" alt="" and="" are="" bottom,="" box""="" by="" contain="" from="" rectangles="" rectangles.="" red="" src="/static/wear/images/components/ComposeDependencies.png" surrounded="" the="" to="" top="" />

這表示許多搭配 Jetpack Compose 使用的依附元件仍適用於 Wear OS 版本。舉例來說，您可以使用相同的使用者介面、執行階段、編譯器和動畫依附元件。

不過，Wear OS 有專屬的 material、foundation 和 navigation 程式庫版本，因此請確認您使用的是正確的程式庫。

請盡可能使用 WearComposeMaterial 版本的 API。就技術上來說，您也可以使用 Compose Material 的行動裝置版本，但是這個程式庫並未針對 Wear OS 的獨特需求進行最佳化。此外，混用 Compose Material 和 Compose Material for Wear OS 也可能導致非預期行為。舉例來說，每個程式庫都有自己的 MaterialTheme 類別，如果您同時使用兩種版本，顏色、字體排版和形狀可能會不一致。

下表列出 Wear OS 和 Mobile 依附元件的不同點：

Wear OS 依附元件

(androidx.wear.*)

 比較 Mobile 依附元件

(androidx.*)
androidx.wear.compose:compose-material 而非 androidx.compose.material:material
androidx.wear.compose:compose-navigation 而非 androidx.navigation:navigation-compose
androidx.wear.compose:compose-foundation 搭配使用 androidx.compose.foundation:foundation

以下程式碼片段顯示包含這些依附元件的 build.gradle 檔案範例：

Kotlin

dependencies {

    val composeBom = platform("androidx.compose:compose-bom:2024.10.01")

    // General compose dependencies
    implementation(composeBom)
    implementation("androidx.activity:activity-compose:1.9.3")
    implementation("androidx.compose.ui:ui-tooling-preview:1.7.5")
    // Other compose dependencies

    // Compose for Wear OS Dependencies
    implementation("androidx.wear.compose:compose-material:1.4.0")

    // Foundation is additive, so you can use the mobile version in your Wear OS app.
    implementation("androidx.wear.compose:compose-foundation:1.4.0")

    // Wear OS preview annotations
    implementation("androidx.wear.compose:compose-ui-tooling:1.4.0")

    // If you are using Compose Navigation, use the Wear OS version (NOT THE MOBILE VERSION).
    // Uncomment the line below and update the version number.
    // implementation("androidx.wear.compose:compose-navigation:1.4.0")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.3")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.4.0")
    androidTestImplementation("androidx.compose.ui:ui-test-junit4:1.0.3")
    debugImplementation("androidx.compose.ui:ui-tooling:1.0.3")
}

意見回饋

試用 Compose for Wear OS 後，歡迎您透過 Issue Tracker 提供建議和意見。

另外也邀請您加入 Kotlin Slack 的 #compose-wear 頻道，和開發人員社群交流並談談您的使用體驗。