如何为Galaxy Watch 4 Classic在Wear OS 3.0(Jetpack Compose)实现表圈位置指示器

前提配置检查 #

• 使用Wear Compose开发时，确保wear-compose-material依赖版本不低于1.2.0，低版本对旋转表圈的支持存在已知缺陷
• AndroidManifest.xml中不要添加android:windowDisablePreview、自定义输入模式等会拦截系统输入事件的配置
• Galaxy Watch 4系列默认开启旋转表圈输入能力，不需要额外申请权限

旋转事件监听实现 #

列表场景原生适配 #

ScalingLazyColumn默认支持旋转表圈输入，只需绑定ScalingLazyListState即可自动响应滚动，同时可以直接绑定系统自带的位置指示器：

val listState = rememberScalingLazyListState()
Scaffold(
    positionIndicator = {
        // 系统自带位置指示器，自动关联列表滚动状态
        ScalingLazyColumnPositionIndicator(state = listState)
    }
) {
    ScalingLazyColumn(
        state = listState,
        modifier = Modifier.fillMaxSize()
    ) {
        items(30) { index ->
            Text(
                text = "列表项 $index",
                modifier = Modifier.padding(8.dp)
            )
        }
    }
}

如果该场景下无法响应旋转事件，优先检查是否给ScalingLazyColumn或其父布局添加了clickable、自定义pointerInput等会拦截输入事件的修饰符。

自定义场景手动监听 #

非列表场景需要手动接收旋转事件时，使用onRotaryScrollEvent修饰符实现：

var scrollOffset by remember { mutableStateOf(0f) }
val focusRequester = remember { FocusRequester() }

Box(
    modifier = Modifier
        .fillMaxSize()
        .onRotaryScrollEvent { event ->
            // event.verticalScrollPixels为旋转偏移量，顺时针为正，逆时针为负
            scrollOffset += event.verticalScrollPixels
            // 此处添加自定义滚动逻辑、位置指示器更新逻辑
            true
        }
        // 必须添加focusable并主动请求焦点才能接收旋转事件
        .focusable()
        .focusRequester(focusRequester)
) {
    Text(
        text = "当前旋转偏移：${scrollOffset.toInt()}",
        modifier = Modifier.align(Alignment.Center)
    )
}

// 页面加载时主动请求焦点
LaunchedEffect(Unit) {
    focusRequester.requestFocus()
}

自定义位置指示器实现 #

如果系统自带的指示器不符合设计需求，可以基于列表状态自定义实现：

@Composable
fun CustomPositionIndicator(state: ScalingLazyListState) {
    // 计算滚动进度
    val scrollProgress by remember {
        derivedStateOf {
            val totalCount = state.layoutInfo.totalItemsCount
            val visibleCount = state.layoutInfo.visibleItemsInfo.size
            if (totalCount <= visibleCount) return@derivedStateOf 0f
            state.firstVisibleItemIndex.toFloat() / (totalCount - visibleCount).toFloat()
        }
    }

    // 侧边滚动条样式指示器
    Box(
        modifier = Modifier
            .align(Alignment.CenterEnd)
            .padding(end = 4.dp)
            .width(4.dp)
            .fillMaxHeight(0.6f)
            .background(Color.Gray.copy(alpha = 0.3f), RoundedCornerShape(2.dp))
    ) {
        Box(
            modifier = Modifier
                .fillMaxWidth()
                .fillMaxHeight(0.1f)
                .align(Alignment.TopStart)
                .offset(y = (scrollProgress * (0.9f * 48.dp.value)).dp)
                .background(Color.White, RoundedCornerShape(2.dp))
        )
    }
}

问题排查点 #

• 不要在父布局添加nestedScroll修饰符拦截滚动事件
• 手动监听旋转事件时，确保目标布局当前持有焦点
• 不要在Activity的window层级修改默认输入模式，会导致系统旋转事件被拦截

内容的提问来源于stack exchange，提问作者Erick Agüero