求助：如何在Jetpack Compose中实现Coach mark引导标记？

核心思路 #

Coach Mark的本质是在界面上层叠加半透明遮罩，高亮目标交互元素并显示引导提示。通过Compose的Box布局可以轻松实现层级叠加，结合状态控制引导的显示/隐藏及多步骤切换。

基础单步引导实现 #

以下是一个简单的引导示例，高亮中心按钮并显示提示：

@Composable
fun SingleStepCoachMark() {
    var showCoachMark by remember { mutableStateOf(true) }

    Box(modifier = Modifier.fillMaxSize()) {
        // 主界面核心元素
        Button(
            onClick = { /* 业务逻辑 */ },
            modifier = Modifier.align(Alignment.Center)
        ) {
            Text("核心操作按钮")
        }

        // 引导层
        if (showCoachMark) {
            // 半透明背景遮罩
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(Color.Black.copy(alpha = 0.7f))
                    .clickable { showCoachMark = false } // 点击遮罩关闭引导
            ) {
                // 高亮目标区域（圆形边框）
                Box(
                    modifier = Modifier
                        .align(Alignment.Center)
                        .size(80.dp)
                        .clip(CircleShape)
                        .background(Color.Transparent)
                        .border(2.dp, Color.White, CircleShape)
                )

                // 引导提示卡片
                Column(
                    modifier = Modifier
                        .align(Alignment.BottomCenter)
                        .padding(bottom = 60.dp)
                        .background(Color.White, RoundedCornerShape(8.dp))
                        .padding(16.dp),
                    horizontalAlignment = Alignment.CenterHorizontally
                ) {
                    Text("点击这个按钮完成核心操作", color = Color.Black)
                    Spacer(modifier = Modifier.height(12.dp))
                    Button(onClick = { showCoachMark = false }) {
                        Text("知道了")
                    }
                }
            }
        }
    }
}

多步骤引导实现 #

如果需要按流程引导用户完成多个操作，可以通过状态管理当前引导步骤：

@Composable
fun MultiStepCoachMark() {
    var currentStep by rememberSaveable { mutableStateOf(0) }
    val totalSteps = 2

    Box(modifier = Modifier.fillMaxSize()) {
        // 主界面元素
        Button(
            onClick = {},
            modifier = Modifier.align(Alignment.TopCenter).padding(top = 40.dp),
            content = { Text("进入设置") }
        )
        Button(
            onClick = {},
            modifier = Modifier.align(Alignment.Center),
            content = { Text("确认操作") }
        )

        // 多步骤引导层
        if (currentStep < totalSteps) {
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(Color.Black.copy(alpha = 0.7f))
            ) {
                when (currentStep) {
                    0 -> {
                        // 高亮顶部按钮
                        Box(
                            modifier = Modifier
                                .align(Alignment.TopCenter)
                                .padding(top = 40.dp)
                                .sizeIn(minWidth = 120.dp, minHeight = 48.dp)
                                .clip(RoundedCornerShape(8.dp))
                                .background(Color.Transparent)
                                .border(2.dp, Color.White, RoundedCornerShape(8.dp))
                        )
                        // 提示文本
                        Column(
                            modifier = Modifier
                                .align(Alignment.TopCenter)
                                .padding(top = 120.dp)
                                .background(Color.White, RoundedCornerShape(8.dp))
                                .padding(16.dp),
                            horizontalAlignment = Alignment.CenterHorizontally
                        ) {
                            Text("先点击这里进入设置页面", color = Color.Black)
                            Spacer(modifier = Modifier.height(12.dp))
                            Button(onClick = { currentStep += 1 }) {
                                Text("下一步")
                            }
                        }
                    }
                    1 -> {
                        // 高亮中间按钮
                        Box(
                            modifier = Modifier
                                .align(Alignment.Center)
                                .size(80.dp)
                                .clip(CircleShape)
                                .background(Color.Transparent)
                                .border(2.dp, Color.White, CircleShape)
                        )
                        // 提示文本
                        Column(
                            modifier = Modifier
                                .align(Alignment.BottomCenter)
                                .padding(bottom = 60.dp)
                                .background(Color.White, RoundedCornerShape(8.dp))
                                .padding(16.dp),
                            horizontalAlignment = Alignment.CenterHorizontally
                        ) {
                            Text("点击这里完成最终操作", color = Color.Black)
                            Spacer(modifier = Modifier.height(12.dp))
                            Button(onClick = { currentStep += 1 }) {
                                Text("完成")
                            }
                        }
                    }
                }
            }
        }
    }
}

优化要点 #

• 使用rememberSaveable替代remember，确保配置变更（如旋转屏幕）后引导状态不丢失
• 高亮区域的尺寸和位置需与目标元素完全对齐，避免视觉偏移
• 可配合AnimatedVisibility添加进入/退出动画，提升交互体验
• 若需要镂空高亮效果（而非边框），可通过Canvas绘制clipPath实现透明区域

内容的提问来源于stack exchange，提问作者Alejandro Pozas O.