Wear OS Compose 代码实验室

1. 简介

Wear OS Compose 允许您将使用 Jetpack Compose 构建应用的知识迁移到可穿戴设备上。

Wear OS Compose 内置了对 Material Design 的支持，简化并加速了 UI 开发，并帮助您用更少的代码创建精美的应用。

在本代码实验室中，我们希望您具备一些 Compose 知识，但您当然不必是专家。

我们将使用 Horologist，这是一个基于 Jetpack Compose 构建的开源项目，可帮助开发者加速应用开发。

您将创建几个 Wear 特定的可组合项（简单和复杂），最终，您可以开始编写自己的 Wear OS 应用。让我们开始吧！

学习内容

您之前使用 Compose 的经验中的异同
简单的可组合项及其在 Wear OS 上的工作原理
Wear OS 特定的可组合项
Wear OS 的 LazyColumn (ScalingLazyColumn)
Wear OS 版本的 Scaffold

构建内容

您将构建一个简单的应用，该应用显示一个针对 Wear OS 优化的可组合项滚动列表。

因为您将使用 Scaffold，您还将在顶部获得一个弯曲的文本时间，一个晕影，最后是与设备侧面绑定的滚动指示器。

以下是完成代码实验室后应用的外观

先决条件

对 Android 开发的基本了解
对 Kotlin 的基本了解
对 Compose 的基本了解

2. 设置环境

在此步骤中，您将设置环境并下载启动项目。

所需工具

最新稳定版本的 Android Studio
Wear OS 设备或模拟器（新手？此处介绍如何设置。）

下载代码

如果您已安装 git，则只需运行以下命令即可从此仓库克隆代码。要检查是否安装了 git，请在终端或命令行中键入 git --version 并验证其是否正确执行。

git clone https://github.com/android/codelab-compose-for-wear-os.git
cd codelab-compose-for-wear-os

如果您没有安装 git，您可以点击以下按钮下载本代码实验室的所有代码

您可以随时在 Android Studio 中运行任一模块，方法是在工具栏中更改运行配置。

在 Android Studio 中打开项目

在“欢迎使用 Android Studio”窗口中，选择 打开现有项目
选择文件夹 [下载位置]
当 Android Studio 导入项目后，测试您是否可以在 Wear OS 模拟器或物理设备上运行 start 和 finished 模块。
start 模块应如下面的屏幕截图所示。您将在其中完成所有工作。

浏览开始代码

build.gradle 包含基本的应用配置。它包含创建可组合 Wear OS 应用所需的依赖项。我们将讨论 Jetpack Compose 和 Wear OS 版本之间的异同。
main > AndroidManifest.xml 包含创建 Wear OS 应用所需的元素。这与非 Compose 应用相同，并且类似于移动应用，因此我们不会对此进行回顾。
main > theme/ 文件夹包含 Compose 用于主题的 Color、Type 和 Theme 文件。
main > MainActivity.kt 包含使用 Compose 创建应用的样板代码。它还包含应用的顶级可组合项（如 Scaffold 和 ScalingLazyList）。
main > ReusableComponents.kt 包含我们创建的大多数 Wear 特定可组合项的功能。我们将在该文件中完成大量工作。

3. 审查依赖项

您进行的大多数 Wear 相关依赖项更改将在顶层架构层（如下所示，红色突出显示的部分）。

这意味着当以 Wear OS 为目标时，您之前使用过的许多 Jetpack Compose 依赖项不会改变。例如，UI、运行时、编译器和动画依赖项将保持不变。

但是，您需要使用正确的 Wear OS Material、Foundation 和 Navigation 库，这些库与您之前使用的库不同。

下面是一个比较，以帮助阐明差异

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
androidx.wear.compose:compose-ui-tooling	除了	androidx.compose.ui:ui-tooling-preview

1. 开发人员可以使用 Wear Compose Material 库继续使用其他与 Material 相关的库，如 Material Ripple 和 Material Icons Extended。

打开 build.gradle，在您的 start 模块中搜索“TODO: Review Dependencies”。（此步骤仅用于审查依赖项，您无需添加任何代码。）

start/build.gradle

   def composeBom = platform(libs.androidx.compose.bom)

    // General compose dependencies
    implementation composeBom
    implementation libs.androidx.activity.compose
    implementation libs.compose.ui.tooling.preview

    implementation(libs.androidx.material.icons.extended)

    // Compose for Wear OS Dependencies
    implementation libs.wear.compose.material

    // Foundation is additive, so you can use the mobile version in your Wear OS app.
    implementation libs.wear.compose.foundation

    // Compose preview annotations for Wear OS.
    implementation(libs.androidx.compose.ui.tooling)

    debugImplementation libs.compose.ui.tooling
    debugImplementation libs.androidx.ui.test.manifest
    debugImplementation composeBom

您应该认识许多常规的 Compose 依赖项，因此我们不会介绍这些依赖项。

让我们转到 Wear OS 依赖项。

正如前面概述的那样，仅包含 material 的 Wear OS 特定版本（androidx.wear.compose:compose-material）。也就是说，您不会在项目中看到或包含 androidx.compose.material:material。

需要说明的是，您可以将其他 Material 库与 Wear Material 一起使用。实际上，我们在本代码实验室中通过包含 androidx.compose.material:material-icons-extended 实现了这一点。

最后，我们包含了 Compose 的 Wear foundation 库（androidx.wear.compose:compose-foundation）。这是附加的，因此您可以将其与之前使用过的标准 foundation 一起使用。事实上，您可能已经注意到我们在常规的 Compose 依赖项中包含了它！

好的，现在我们了解了依赖项，让我们看看主应用。

4. 审查 MainActivity

我们将在

start

模块中完成所有工作，因此请确保您打开的每个文件都在该模块中。

让我们首先在 start 模块中打开 MainActivity。

这是一个非常简单的类，它扩展了 ComponentActivity 并使用 setContent { WearApp() } 创建 UI。

根据您之前对 Compose 的了解，这应该看起来很熟悉。我们只是在设置 UI。

向下滚动到 WearApp() 可组合函数。在我们讨论代码本身之前，您应该会看到代码中散布着许多 TODO。这些都代表了本代码实验室中的步骤。您现在可以忽略它们。

它应该如下所示

fun WearApp() 中的代码

WearAppTheme {
     /* *************************** Part 4: Wear OS Scaffold *************************** */
    // TODO (Start): Create a AppScaffold (Wear Version)

    // TODO: Swap to ScalingLazyColumnState
    val listState = rememberLazyListState()

    /* *************************** Part 4: Wear OS Scaffold *************************** */
    // TODO (Start): Create a ScreenScaffold (Wear Version)

    // Modifiers used by our Wear composables.
    val contentModifier = Modifier.fillMaxWidth().padding(bottom = 8.dp)
    val iconModifier = Modifier.size(24.dp).wrapContentSize(align = Alignment.Center)

    /* *************************** Part 3: ScalingLazyColumn *************************** */
    // TODO: Swap a ScalingLazyColumn (Wear's version of LazyColumn)
    LazyColumn(
        modifier = Modifier.fillMaxSize(),
        contentPadding = PaddingValues(
            top = 32.dp,
            start = 8.dp,
            end = 8.dp,
            bottom = 32.dp,
        ),
        verticalArrangement = Arrangement.Center,
        state = listState,
    ) {
        // TODO: Remove item; for beginning only.
        item { StartOnlyTextComposables() }

        /* ******************* Part 1: Simple composables ******************* */
        item { ButtonExample(contentModifier, iconModifier) }
        item { TextExample(contentModifier) }
        item { CardExample(contentModifier, iconModifier) }

        /* ********************* Part 2: Wear unique composables ********************* */
        item { ChipExample(contentModifier, iconModifier) }
        item { ToggleChipExample(contentModifier) }
        }

    // TODO (End): Create a ScreenScaffold (Wear Version)
    // TODO (End): Create a AppScaffold (Wear Version)
}

我们首先设置主题，WearAppTheme { }。这与您之前编写的方式完全相同，也就是说，您设置了一个带有颜色、排版和形状的 MaterialTheme。

但是，在 Wear OS 的情况下，我们通常建议使用默认的 Material Wear 形状，这些形状针对圆形设备进行了优化，因此如果您深入研究我们的 theme/Theme.kt，您会发现我们没有覆盖形状。

如果您愿意，可以打开 theme/Theme.kt 以进一步探索它，但同样，它与手机上的主题相同。

接下来，我们为即将构建的 Wear 可组合项创建一些修饰符，这样我们就无需每次都指定它们。它主要用于居中内容并添加一些填充。

然后，我们创建一个LazyColumn，它用于为大量项目生成垂直滚动列表（就像您之前做的那样）。

代码

item { StartOnlyTextComposables() }

/* ******************* Part 1: Simple composables ******************* */
item { ButtonExample(contentModifier, iconModifier) }
item { TextExample(contentModifier) }
item { CardExample(contentModifier, iconModifier) }

/* ********************* Part 2: Wear unique composables ********************* */
item { ChipExample(contentModifier, iconModifier) }
item { ToggleChipExample(contentModifier) }

对于项目本身，只有StartOnlyTextComposables()生成任何 UI。（我们将在整个代码实验室中填充其余部分。）

这些函数实际上位于ReusableComponents.kt文件中，我们将在下一节中访问它。

让我们开始使用 Compose for Wear OS！

5. 添加简单的可组合项

我们将从三个可组合项（Button、Text 和 Card）开始，您可能已经熟悉它们。

首先，我们将删除 hello world 可组合项。

搜索“TODO: Remove item”并**删除**注释及其下方的行。

步骤 1

// TODO: Remove item; for beginning only.
item { StartOnlyTextComposables() }

接下来，让我们添加第一个可组合项。

创建 Button 可组合项

在start模块中的ReusableComponents.kt中打开，搜索“TODO: Create a Button Composable”，并将当前的可组合方法替换为此代码。

步骤 2

// TODO: Create a Button Composable (with a Row to center)
@Composable
fun ButtonExample(
    modifier: Modifier = Modifier,
    iconModifier: Modifier = Modifier
) {
    Row(
        modifier = modifier,
        horizontalArrangement = Arrangement.Center
    ) {
        // Button
        Button(
            modifier = Modifier.size(ButtonDefaults.LargeButtonSize),
            onClick = { /* ... */ },
        ) {
            Icon(
                imageVector = Icons.Rounded.Phone,
                contentDescription = "triggers phone action",
                modifier = iconModifier
            )
        }
    }
}

ButtonExample()可组合函数（此代码存在的位置）现在将生成一个居中的按钮。

让我们逐步了解代码。

Row仅在此处用于在圆形屏幕上居中Button可组合项。您可以看到我们通过应用在MainActivity中创建的修饰符并将其传递到此函数中来实现这一点。稍后，当我们在圆形屏幕上滚动时，我们要确保我们的内容不会被截断（这就是它居中的原因）。

接下来，我们创建Button本身。代码与您之前使用的 Button 代码相同，但是，在我们的例子中，我们使用ButtonDefault.LargeButtonSize。这些是针对 Wear OS 设备优化的预设尺寸，因此请确保使用它们！

之后，我们将点击事件设置为一个空 lambda。在我们的例子中，这些可组合项仅用于演示，因此我们不需要它。但是，在真实的应用程序中，我们将与例如 ViewModel 通信以执行业务逻辑。

然后我们在按钮内设置一个图标。此代码与您之前看到的 Icon 代码相同。我们还从androidx.compose.material:material-icons-extended库中获取我们的图标。

最后，我们设置了之前为图标设置的修饰符。

如果您运行应用程序，您应该会看到类似以下内容

这可能是您之前已经编写过的代码（这很好）。不同之处在于，您现在可以获得针对 Wear OS 优化的按钮。

非常简单，让我们看看另一个。

创建 Text 可组合项

在ReusableComponents.kt中，搜索“TODO: Create a Text Composable”，并将当前的可组合方法替换为此代码。

步骤 3

// TODO: Create a Text Composable
@Composable
fun TextExample(modifier: Modifier = Modifier) {
    Text(
        modifier = modifier,
        textAlign = TextAlign.Center,
        color = MaterialTheme.colors.primary,
        text = stringResource(R.string.device_shape)
    )
}

我们创建Text可组合项，设置其修饰符，对齐文本，设置颜色，最后从字符串资源设置文本本身。

Text 可组合项对于 Compose 开发人员来说应该看起来非常熟悉，并且代码实际上与您之前使用的代码相同。

让我们看看它是什么样子的

TextExample()可组合函数（我们放置代码的位置）现在在我们的主要材质颜色中生成一个 Text 可组合项。字符串是从我们的res/values/strings.xml文件提取的。

到目前为止，一切都很好。让我们看看我们最后一个类似的可组合项Card。

创建 Card 可组合项

在ReusableComponents.kt中，搜索“TODO: Create a Card”，并将当前的可组合方法替换为此代码。

步骤 4

// TODO: Create a Card (specifically, an AppCard) Composable
@Composable
fun CardExample(
    modifier: Modifier = Modifier,
    iconModifier: Modifier = Modifier
) {
    AppCard(
        modifier = modifier,
        appImage = {
            Icon(
                imageVector = Icons.Rounded.Message,
                contentDescription = "triggers open message action",
                modifier = iconModifier
            )
        },
        appName = { Text("Messages") },
        time = { Text("12m") },
        title = { Text("Kim Green") },
        onClick = { /* ... */ }
    ) {
        Text("On my way!")
    }
}

Wear 有点不同，因为我们有两个主要的卡片，AppCard和TitleCard。

在我们的例子中，我们希望在我们的卡片中有一个Icon，因此我们将使用AppCard。（TitleCard的插槽较少，有关更多信息，请参阅卡片指南。）

我们创建AppCard可组合项，设置其修饰符，添加一个Icon，添加几个Text可组合项参数（每个参数用于卡片上的不同空间），最后在最后设置主要内容文本。

让我们看看它是什么样子的

此时，您可能已经认识到，对于这些可组合项，Compose 代码实际上与您之前使用的代码相同，这很好，对吧？您可以重用您已经获得的所有知识！

好的，让我们看看一些新的可组合项。

6. 添加 Wear 独有的可组合项

在本节中，我们将探讨Chip和ToggleChip可组合项。

创建 Chip 可组合项

芯片实际上是在材质指南中指定的，但标准材质库中没有实际的可组合函数。

它们旨在提供快速的一键式操作，这对于屏幕空间有限的 Wear 设备尤其有意义。

以下是一些Chip可组合函数的变体，让您了解可以创建什么

让我们编写一些代码。

在ReusableComponents.kt中，搜索“TODO: Create a Chip”，并将当前的可组合方法替换为此代码。

步骤 5

// TODO: Create a Chip Composable
@Composable
fun ChipExample(
    modifier: Modifier = Modifier,
    iconModifier: Modifier = Modifier
) {
    Chip(
        modifier = modifier,
        onClick = { /* ... */ },
        label = {
            Text(
                text = "5 minute Meditation",
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        },
        icon = {
            Icon(
                imageVector = Icons.Rounded.SelfImprovement,
                contentDescription = "triggers meditation action",
                modifier = iconModifier
            )
        },
    )
}

Chip可组合项使用了许多与您习惯的其他可组合项相同的参数（修饰符和onClick），因此我们无需复习这些。

它还接收一个标签（我们为此创建一个Text可组合项）和一个图标。

Icon代码应该与您在其他可组合项中看到的代码完全相同，但对于此代码，我们从androidx.compose.material:material-icons-extended库中提取Self Improvement图标。

让我们看看它是什么样子的（请记住向下滚动）

好的，让我们看看Toggle的一个变体，即ToggleChip可组合项。

创建 ToggleChip 可组合项

ToggleChip就像一个Chip，但允许用户与单选按钮、切换按钮或复选框进行交互。

在ReusableComponents.kt中，搜索“TODO: Create a ToggleChip”，并将当前的可组合方法替换为此代码。

步骤 6

// TODO: Create a ToggleChip Composable
@Composable
fun ToggleChipExample(modifier: Modifier = Modifier) {
    var checked by remember { mutableStateOf(true) }
    ToggleChip(
        modifier = modifier,
        checked = checked,
        toggleControl = {
            Switch(
                checked = checked,
                modifier = Modifier.semantics {
                    this.contentDescription = if (checked) "On" else "Off"
                }
            )
        },
        onCheckedChange = {
            checked = it
        },
        label = {
            Text(
                text = "Sound",
                maxLines = 1,
                overflow = TextOverflow.Ellipsis
            )
        }
    )
}

现在ToggleChipExample()可组合函数（此代码存在的位置）使用切换开关（而不是复选框或单选按钮）生成一个ToggleChip。

首先，我们创建一个MutableState。我们之前在其他函数中没有这样做，因为我们主要进行 UI 演示，以便您可以看到 Wear 提供的功能。

在正常的应用程序中，您可能希望传入选中状态和处理点击的 lambda，以便可组合项可以是无状态的（此处了解更多信息）。

在我们的例子中，我们只是为了简化操作，展示ToggleChip在具有工作切换功能的情况下的外观（即使我们对状态不做任何操作）。

接下来，我们设置修饰符、选中状态和切换控件以提供所需的开关。

然后我们为更改状态创建一个 lambda，最后使用Text可组合项（以及一些基本参数）设置标签。

让我们看看它是什么样子的

好的，现在您已经看到了许多 Wear OS 特定的可组合项，并且如前所述，大多数代码与您之前编写的代码几乎相同。

让我们看看一些更高级的内容。

7. 迁移到 ScalingLazyColumn

您可能在移动应用程序中使用过LazyColumn来生成垂直滚动列表。

由于圆形设备在顶部和底部较小，因此显示项目的空间较少。因此，Wear OS 有自己的LazyColumn版本以更好地支持这些圆形设备。

ScalingLazyColumn 继承自 LazyColumn，支持在屏幕顶部和底部进行缩放和透明度调整，使内容更易于用户阅读。

这是一个演示

请注意，当项目靠近中心时，它会放大到其完整尺寸，然后随着它移开，它会缩小（同时变得更透明）。

这是一个来自应用程序的更具体的示例

我们发现这确实有助于提高可读性。

现在您已经看到了 ScalingLazyColumn 的实际应用，让我们开始将我们的 LazyColumn 转换。

我们将使用 Horologist ScalingLazyColumn 来确保列表中的项目具有正确的填充，并且在不同的设备屏幕尺寸上不会被裁剪。

转换为 Horologist ScalingLazyColumnState

在 MainActivity.kt 中，搜索“TODO: Swap to ScalingLazyColumnState”，并用以下代码替换该注释和下面的行，请注意我们如何指定哪些是第一个和最后一个组件，以便使用最佳填充值来避免任何内容裁剪。

步骤 7

// TODO: Swap to ScalingLazyColumnState
val listState = rememberResponsiveColumnState(
    contentPadding = ScalingLazyColumnDefaults.padding(
        first = ItemType.SingleButton,
        last = ItemType.Chip,
    ),
)

名称几乎相同。就像 LazyListState 处理 LazyColumn 的状态一样，ScalingLazyColumnState 处理 ScalingLazyColumn 的状态。

转换为 Horologist ScalingLazyColumn

接下来，我们替换为 ScalingLazyColumn。

在 MainActivity.kt 中，搜索“TODO: Swap a ScalingLazyColumn”。首先，将 LazyColumn 替换为 Horologist ScalingLazyColumn。

然后完全删除 contentPadding, verticalArrangement, modifier 和 autocentering - Horologist ScalingLazyColumn 已经提供了默认设置，这些设置可以保证更好的默认视觉效果，因为大部分视口将被列表项填充。在大多数情况下，默认参数就足够了，如果您在顶部有标题，我们建议将其放入 ResponsiveListHeader 作为第一个项目。

步骤 8

// TODO: Swap a ScalingLazyColumn (Wear's version of LazyColumn)
ScalingLazyColumn(
    columnState = listState

就是这样！让我们看看效果如何

您可以看到，当您滚动时，内容会进行缩放，并且屏幕顶部和底部的透明度会进行调整，迁移工作量非常少！

当您上下移动冥想可组合项时，您会真正注意到这一点。

现在进入最后一个主题，Wear OS 的 Scaffold。

8. 添加 Scaffold

Scaffold 提供了一个布局结构，可以帮助您按照常见模式排列屏幕，就像移动设备一样，但它不支持应用栏、浮动操作按钮、抽屉或其他移动特定元素，而是支持三个 Wear 特定的布局以及顶级组件：时间、滚动/位置指示器和页面指示器。

它们看起来是这样的

	`TimeText`
	`PositionIndicator`
	`PageIndicator`

我们将详细介绍前三个组件，但首先，让我们将脚手架放在适当的位置。

我们将使用 Horologist AppScaffold 和 ScreenScaffold，它们默认在屏幕上添加 TimeText

并确保在屏幕之间导航时它可以正确动画。

此外，ScreenScaffold 为可滚动内容添加了 PositionIndicator。

添加 Scaffold

现在让我们添加 AppScaffold 和 ScreenScaffold 的样板代码。

找到“TODO (Start): Create a AppScaffold (Wear Version)”，并在其下方添加以下代码。

步骤 9

WearAppTheme {
// TODO (Start): Create a Horologist AppScaffold (Wear Version)
AppScaffold {

找到 "TODO (Start): Create a ScreenScaffold (Wear Version)"，并在其下方添加以下代码。

// TODO (Start): Create a Horologist ScreenScaffold (Wear Version)
ScreenScaffold( 
    scrollState = listState,
){

接下来，确保将结束括号添加到正确的位置。

找到 "TODO (End): Create a ScreenScaffold (Wear Version)"，并在那里添加结束括号

步骤 10

// TODO (End): Create a ScreenScaffold (Wear Version)
}

找到 "TODO (End): Create a AppScaffold (Wear Version)"，并在那里添加结束括号

步骤 10

// TODO (End): Create a AppScaffold (Wear Version)
}

让我们先运行它。您应该会看到类似以下内容

请注意，它添加了

一个 TimeText，它在后台使用弯曲文本，并为开发者提供了一种简单的方法来显示时间，而无需放置可组合项或使用任何与时间相关的类。此外，Material 指南建议您在应用程序中任何屏幕的顶部显示时间，并且在滚动时它会逐渐淡出。
一个 PositionIndicator（也称为滚动指示器），它是屏幕右侧的一个指示器，用于根据您传入的状态对象类型显示当前指示器位置。在我们的例子中，将是 ScalingLazyColumnState。

好的，让我们看看现在是什么样子

尝试上下滚动。您应该只在滚动时看到滚动指示器显示。

干得好，您已经完成了大多数 Wear OS 可组合项的 UI 演示！

9. 恭喜

恭喜！您学习了在 Wear OS 上使用 Compose 的基础知识！

现在您可以重新应用您所有的 Compose 知识来创建漂亮的 Wear OS 应用！

接下来是什么？

查看其他 Wear OS 代码实验室

创建您的第一个 Wear OS 磁贴

进一步阅读

反馈

我们很乐意听取您使用 Compose for Wear OS 的体验以及您能够构建的内容！加入 Kotlin Slack #compose-wear 频道中的讨论，并继续在问题跟踪器上提供反馈。

编码愉快！