reveal

Reveal 效果（也称为指导标记、新手引导、教程、操作指引等）为 Compose 多平台 提供了一个优雅的 API，可用于 Android、iOS、桌面和网页应用。

术语

入门

Compose 多平台

从版本 3.0 开始，Reveal 基于 Compose 多平台，可用于 Android、iOS、桌面和网页应用。但请注意，除 Android 外，其他平台目前尚未经过充分测试，一些目标平台仍处于 alpha 或实验阶段。

在 Android 上使用 Reveal 时，请确保 Google 的 Jetpack Compose 版本与 Reveal 使用的 Compose 多平台版本兼容，您可以在这里找到相关信息。

安装

支持的最低 Android SDK 版本为 21（Android 5.0），这是 Jetpack Compose 的要求。将 Reveal 作为依赖项添加到您的项目中。它可在 Maven Central 上获取。

dependencies {
    implementation("com.svenjacobs.reveal:reveal-core:$REVEAL_VERSION")
}

构件

Compose

有两个重要的可组合项：

首先是 RevealCanvas，负责渲染效果。Compose 层次结构中应该只有一个 RevealCanvas 实例，它应该位于树的顶部或最顶部位置，以确保效果在所有其他元素之上以"全屏"方式渲染。

其次，Reveal 可组合项负责注册可显示项目并与之交互。可以有多个 Reveal 实例，它们与 RevealCanvas 实例直接相关。通常一个应用的每个"屏幕"最多应有一个 Reveal。

@Composable
fun App() {
    val revealCanvasState = rememberRevealCanvasState()

    // 单个实例，应位于 Compose 层次结构的顶部
    RevealCanvas(
        modifier = Modifier.fillMaxSize(),
        revealCanvasState = revealCanvasState,
    ) {
        MainScreen(revealCanvasState = revealCanvasState)
    }
}

@Composable
fun MainScreen(revealCanvasState: RevealCanvasState) {
    val revealState = rememberRevealState()

    // 通常每个屏幕一个实例
    Reveal(
        revealCanvasState = revealCanvasState,
        revealState = revealState,
        onRevealableClick = {},
        onOverlayClick = {},
    ) {
        // 内容
    }
}

在 Reveal 内部，通过 revealable 修饰符指定可显示项目。

enum class Keys { HelloWorld }

Column {
    Text(
        modifier = Modifier.revealable(key = Keys.HelloWorld),
        text = "Hello world",
    )
}

现在通过 revealState.reveal(Keys.HelloWorld) 启动显示效果。

很好，您刚刚启动了第一个显示效果。但是还缺少一些解释性项目，比如显示区域旁边的文本或图像。所以让我们添加一个。

解释性项目通过 Reveal 可组合项的 overlayContent 指定。

Reveal(
    overlayContent = { key ->
        when (key) {
            Keys.HelloWorld -> {
                Surface(
                    modifier = Modifier
                        .align(horizontalArrangement = RevealOverlayArrangement.Horizontal.Start)
                        .padding(8.dp),
                    shape = RoundedCornerShape(4.dp),
                    color = Color.White,
                ) {
                    Text("这是一个解释")
                }
            }
        }
    }
) {
    // 内容
}

遮罩层内容可组合项的作用域提供了 align() 修饰符，用于将项目对齐到显示区域的开始、顶部、结束或底部。

Reveal 提供了两个点击监听器：当点击显示区域时，onRevealableClick 会被调用，第一个参数是当前可显示项目的键。当点击遮罩层的某个位置时，onOverlayClick 会被调用，同样带有键参数。使用这些点击监听器来显示下一个项目，例如用于某种教程，或通过 revealState.hide() 隐藏效果。

目前就是这些。有关更多详细信息，请查看演示应用程序和 JavaDoc。该库文档齐全 😉

常见问题

请参阅 FAQ.md