如何正确选用Wear OS Compose手表专用组件？

很多人开始用Jetpack Compose开发Wear OS应用时，会直接把手机项目里的组件拿过来用，结果列表在圆形表盘边缘被截断，按钮小到很难点中，时间信息也被遮住。Wear OS Compose的专用组件并不是简单缩小尺寸，而是从测量、绘制到触摸反馈都针对手表环境重新设计。理解这些组件的工作方式，才能做出真正适合手腕上的界面。

一、为什么手机Compose组件在手表上会失效

普通Compose的LazyColumn假设屏幕是矩形，并且有足够的纵向空间让内容滚动。手表屏幕直径通常在40毫米到46毫米之间，实际可用区域更小，而且很多设备采用圆形屏幕。矩形列表的顶部和底部会被圆形边缘切掉，用户看不到首尾条目。即使通过padding预留空间，视觉上也会显得拥挤。

另一个差异来自交互方式。手机用户习惯点击按钮和滑动长列表，手表用户则更多依赖旋转表冠和短距离滑动。Wear OS Compose的ScalingLazyColumn内部会监听表冠滚动事件，并将滚动转换成带缩放效果的位移。普通LazyColumn并不具备针对圆形边缘的缩放淡出逻辑。

此外，Wear OS常显模式要求界面在低功耗下保持基本可读。专用组件在绘制时会减少不必要的重绘，TimeText还能独立更新，避免整棵树因时间变化而重组。这些设计在手机组件里并不是优先考虑项。

二、ScalingLazyColumn：让列表贴合圆形边缘

ScalingLazyColumn是Wear OS Compose中最核心的布局组件，位于androidx.wear.compose.foundation.lazy包中。它和手机上的LazyColumn类似，但会根据每个item与屏幕上下边缘的距离，动态调整item的缩放比例和透明度。靠近边缘的item会逐渐缩小并变淡，滚到中心时恢复完整尺寸。

使用ScalingLazyColumn需要先创建状态对象，然后通过items或item来添加内容。下面的代码展示了如何创建一个带有自动居中效果的列表。

val listState = rememberScalingLazyListState()
ScalingLazyColumn(
    modifier = Modifier.fillMaxSize(),
    state = listState,
    autoCentering = AutoCenteringParams(itemIndex = 1)
) {
    items(10) { index ->
        Text(
            text = "条目 $index",
            modifier = Modifier.fillMaxWidth()
                .padding(vertical = 8.dp)
        )
    }
}

autoCentering参数用来指定滚动停止后哪一项尽量居中。对于手表上的列表，让当前选中项居中能减少边缘裁切带来的误读。如果你不需要自动居中，可以省略该参数。ScalingLazyColumn默认还会为每个item添加缩放动画，这个效果由ScalingLazyColumn内部处理，不需要额外设置。

与ScalingLazyColumn配合最紧密的是TimeText。它通常放在列表的第一项，用来显示当前时间或应用名称。TimeText的更新不会触发整个列表重组，这对常显模式下的电量消耗很重要。

ScalingLazyColumn(
    state = listState,
    modifier = Modifier.fillMaxSize()
) {
    item {
        TimeText(
            modifier = Modifier.fillMaxWidth()
                .padding(horizontal = 16.dp, vertical = 8.dp)
        )
    }
    items(20) { index ->
        Text("选项 $index")
    }
}

TimeText内部使用了低功耗的时间源，在屏幕常显时会以较低的频率刷新。你可以通过TextStyle参数调整字体大小和颜色，但要注意字体不宜过小，否则在运动中难以阅读。

三、Stepper、Chip与Pager：针对手表优化的交互组件

手表屏幕小，传统的加减按钮往往因为目标区域太小而难以点击。Stepper用一个紧凑的加减控件替代两个独立按钮，并且支持旋转表冠调节数值。它的onValueChange回调会给出最新值，你可以直接更新状态。

var count by remember { mutableStateOf(0) }
Stepper(
    value = count,
    onValueChange = { count = it },
    valueRange = 0..60,
    steps = 1,
    modifier = Modifier.fillMaxWidth()
) {
    Text(text = "$count 分钟")
}

valueRange限定了数值范围，steps表示每次增减的步长。手表上的Stepper在点击加号或减号时会触发触觉反馈，用户即使不看屏幕也能感知操作结果。将Stepper放在ScalingLazyColumn的item中，可以很好地融入滚动列表。

Chip则适合作为选项或单一动作的载体。与普通按钮不同，Chip提供更大的点击热区，允许设置图标和文字，并且会自动适配圆形屏幕的圆角。下面是一个启动操作的示例。

Chip(
    onClick = { /* 启动计时 */ },
    label = { Text("开始专注") },
    icon = { Icon(Icons.Filled.PlayArrow, contentDescription = null) },
    modifier = Modifier.fillMaxWidth()
)

如果页面内容需要横向切换，比如多个表盘设置页，可以使用HorizontalPager。它处理了手表上的横向滑动手势，并支持页面指示器。Wear OS Compose提供了配套的HorizontalPageIndicator，用来显示当前页位置。

val pagerState = rememberPagerState(initialPage = 0) { 3 }
HorizontalPager(state = pagerState) { page ->
    Text("第 $page 页", modifier = Modifier.fillMaxSize())
}

四、实际案例：组装一个番茄钟设置页

下面把前面提到的组件组合起来，实现一个简单的番茄钟设置页。页面包含当前时间、专注时长调节、休息时长调节和一个开始按钮。所有内容都放在ScalingLazyColumn中，保证圆形屏幕下滚动自然。

@Composable
fun TimerSettingsScreen() {
    val listState = rememberScalingLazyListState()
    var workMinutes by remember { mutableStateOf(25) }
    var breakMinutes by remember { mutableStateOf(5) }

    ScalingLazyColumn(
        modifier = Modifier.fillMaxSize(),
        state = listState
    ) {
        item {
            TimeText(
                modifier = Modifier.fillMaxWidth()
                    .padding(horizontal = 16.dp, vertical = 12.dp)
            )
        }
        item {
            Text(
                "专注时长",
                style = MaterialTheme.typography.titleMedium,
                modifier = Modifier.fillMaxWidth()
                    .padding(horizontal = 16.dp)
            )
        }
        item {
            Stepper(
                value = workMinutes,
                onValueChange = { workMinutes = it },
                valueRange = 5..60,
                steps = 5,
                modifier = Modifier.fillMaxWidth()
            ) {
                Text("$workMinutes 分钟")
            }
        }
        item {
            Text(
                "休息时长",
                style = MaterialTheme.typography.titleMedium,
                modifier = Modifier.fillMaxWidth()
                    .padding(horizontal = 16.dp)
            )
        }
        item {
            Stepper(
                value = breakMinutes,
                onValueChange = { breakMinutes = it },
                valueRange = 1..30,
                steps = 1,
                modifier = Modifier.fillMaxWidth()
            ) {
                Text("$breakMinutes 分钟")
            }
        }
        item {
            Chip(
                onClick = { /* 启动计时器 */ },
                label = { Text("开始") },
                icon = { Icon(Icons.Filled.PlayArrow, contentDescription = null) },
                modifier = Modifier.fillMaxWidth()
                    .padding(horizontal = 16.dp, vertical = 8.dp)
            )
        }
    }
}

在这个页面中，TimeText负责顶部常显时间，两个Stepper分别调节专注和休息时长，Chip提供清晰的启动动作。整个页面没有使用任何手机版Material的底部按钮或弹窗，因为那类元素在手表上会占据过多空间。

实际运行时会发现，ScalingLazyColumn在滚动到边缘时自动缩放，顶部TimeText和底部Chip都不会被圆形屏幕裁切。旋转表冠可以直接调整Stepper的数值，手指滑动则用于滚动列表。这种组合符合Wear OS应用的人机交互习惯。

五、旋转表冠与圆形屏幕适配建议

旋转表冠是Wear OS非常高效的输入设备，但并非所有组件都自动响应它。ScalingLazyColumn和Stepper内部已经处理了旋转事件，如果需要自定义滚动行为，可以使用Modifier.onRotaryScrollEvent。下面是一个简单的处理模板。

Modifier.onRotaryScrollEvent { event ->
    if (event.verticalScrollPixels != 0f) {
        // 根据滚动量更新自定义状态
        true
    } else {
        false
    }
}

在这种回调中返回true表示事件已被消费，系统不会再继续传递给其他组件。对于自定义绘制或非标准列表，可以借助这个API实现与表冠的交互。

圆形屏幕适配还要注意内容安全区域。不要把关键操作放在屏幕的四个角，因为那些位置很可能已被裁掉。可以借助BoxWithConstraints计算可用尺寸，或者直接使用Wear OS Compose的预设间距。预览时尽量使用圆形设备配置，模拟器默认的表盘形状可能掩盖边缘问题。

最后，真机测试不可替代。模拟器无法完全模拟触觉反馈、旋转表冠的不同阻尼和常显模式的亮度变化。建议在至少一台圆形屏幕手表上验证所有条目的可读性和点击热区。

Wear OS Compose手表组件Compose for Wear OS修改时间：2026-09-18 00:19:16