在 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 for Mobile 的许多开发原则都适用于 Compose for Wear OS。如需详细了解声明式界面框架的一般优势，请参阅为什么采用 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。

surface

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. 如果您位于 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. 根据 Gradle 属性文件中所述的方法，验证项目的 build.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 与适用于 Wear OS 的 Compose Material 可能会导致意外行为。例如，由于每个库都有自己的 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 频道，与开发者社区建立联系并分享您的体验。