在 Wear OS 上使用 Jetpack Compose

适用于 Wear OS 的 Compose 与适用于移动设备的 Compose 类似。但是，有一些关键的区别。本指南将引导您了解这些相似之处和差异。

适用于 Wear OS 的 Compose 是 Android Jetpack 的一部分，与您使用的其他 Wear Jetpack 库一样，它可以帮助您更快地编写更好的代码。这是我们推荐的构建 Wear OS 应用 用户界面的方法。

如果您不熟悉使用 Jetpack Compose 工具包，请查看 Compose 学习路径。移动 Compose 的许多开发原则都适用于适用于 Wear OS 的 Compose。有关声明式 UI 框架的总体优势，请参阅 为什么选择 Compose。要详细了解适用于 Wear OS 的 Compose，请参阅 适用于 Wear OS 的 Compose 学习路径 和 GitHub 上的 Wear OS 示例存储库。

兼容性

Compose for Wear OS 适用于支持 Wear OS 3.0（API 级别 30）的手表，以及使用 Wear OS 2.0（API 级别 25 及以上）的手表。使用 Compose for Wear OS 1.0 版本 需要使用 androidx.compose 库的 1.2 版本和 Kotlin 1.7.0。

界面

Compose for Wear OS 使得在 Wear OS 上构建应用变得更加容易。有关更多信息，请参阅 应用。使用我们的内置组件创建符合 Wear OS 指南的用户体验。有关组件的更多信息，请参阅我们的 设计指南。

设置

使用 Jetpack Compose 与 Wear OS 类似于使用 Jetpack Compose 针对任何其他 Android 项目。主要区别在于 Jetpack Compose for Wear 添加了 Wear 特定的库，使创建针对手表定制的用户界面变得更加容易。在某些情况下，这些组件与非 Wear 对应组件具有相同的名称，例如 androidx.wear.compose.material.Button 和 androidx.compose.material.Button。

在 Android Studio 中创建一个新的应用

若要创建一个包含 Jetpack Compose 的新项目，请按照以下步骤操作

  1. 如果您位于欢迎使用 Android Studio 窗口，请单击启动新的 Android Studio 项目。如果您已经打开了 Android Studio 项目，请从菜单栏中选择文件 > 新建 > 导入示例。
  2. 搜索Compose for Wear，然后选择Compose for Wear OS Starter。
  3. 在配置您的项目 窗口中，执行以下操作
    1. 设置应用名称。
    2. 选择示例的项目位置。
  4. 单击完成。
  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.0")
    // 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 和移动设备之间的依赖项差异

Wear OS 依赖项

(androidx.wear.*)

 比较 移动设备依赖项

(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，并使用 问题跟踪器 提供建议和反馈。

加入 Kotlin Slack 上的 #compose-wear 频道，与开发者社区联系并告知我们您的体验。