在 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 範例存放區

相容性

Compose for Wear OS 可在支援 Wear OS 3.0 (API 級別 30) 的手錶,以及使用 Wear OS 2.0 (API 級別 25 以上) 的手錶上運作。使用 1.0 版本的 Compose for Wear OS 時,必須使用 1.2 版本的 androidx.compose 程式庫和 Kotlin 1.7.0。

途徑

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.Buttonandroidx.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 工具包依附元件,如以下程式碼片段所示:

Kotlin

dependencies {

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

    // General compose dependencies
    implementation(composeBom)
    implementation("androidx.activity:activity-compose:1.9.2")
    implementation("androidx.compose.ui:ui-tooling-preview:1.7.1")
    // 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")
}

不同點

請盡可能使用 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 的範例檔案:

// Example project in app/build.gradle file
dependencies {
    // Standard Compose dependencies...

    // Wear specific Compose Dependencies
    implementation "androidx.wear.compose:compose-material:$rootProject.wearVersion"
    implementation "androidx.wear.compose:compose-foundation:$rootProject.wearVersion"

    // For navigation within your app...
    implementation "androidx.wear.compose:compose-navigation:$rootProject.wearVersion"

    // Other dependencies...
}

意見回饋

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

加入 #compose-wear 頻道 來與開發人員社群交流,並告訴我們您的 無須專人管理