D02 / 怎麽看到我在写什麽? - @Preview

今天大概会聊到的范围

@Preview annotation 及相关用法

原先的 xml 的 layout 系统，已经被 Android development tool team 优化的很强大
那 Compose 呢？我如何在开发 Compose 的过程一边知道自己在开发什麽？

答案就是 @Preview！使用 @Preview 这个 annotation 就能启动 Compose 的预览功能

什麽是 @Preview

@Preview
@Composable
fun PreviewMyComposable() {
  MyComposable("Nice")
}

@Preview  其实是 compose tooling 的其中一员，必须得标记在没有参数的 composable function (有标记 @Composable 的 function) 上，用来向 Android Studio 标记你需要预览这个 composable function。

加上了 @Preview 的 component 将会被显示在右手边的预览区块，让整个开发流程变得非常的直觉且清楚，所见即所得

@Preview 虽然在 document 上写说他是给 "Android  Studio" 使用的，但 Compose UI 其实是一个跨平台的专案，因此，开发 Compose 时不定会使用 Android Studio。 若你使用了别的工具 (ex. IntelliJ IDEA)，只要有这个 Plugin Compose Multiplatform IDE Support - IntelliJ IDEA & Android Studio Plugin ，你的 IDE 就可以认得 @Preview annotation 并显示预览

设定你的 @Preview

更进一步就会发现，@Preview 这个 annotation 是可以吃参数的。透过这些参数，可以创造自己想要预览的场景

举个例，当我今天希望我的 Composable 显示在黑色的背景上，我可以透过 showBackground 和 backgroundColor来设定：

@Preview(
    showBackground = true,
    backgroundColor = 0xFF191414  // black
)
@Composable
fun PreviewHomeScreen() {
    HomeScreen()
}

点进 @Preview 的 source 来看看，就会看到所有可以带进去的参数

annotation class Preview(
    val name: String = "",
    val group: String = "",
    @IntRange(from = 1) val apiLevel: Int = -1,
    val widthDp: Int = -1,
    val heightDp: Int = -1,
    val locale: String = "",
    @FloatRange(from = 0.01) val fontScale: Float = 1f,
    val showSystemUi: Boolean = false,
    val showBackground: Boolean = false,
    val backgroundColor: Long = 0,
    @UiMode val uiMode: Int = 0,
    @Device val device: String = Devices.DEFAULT
)

大致上，这些参数可以分成几组

标记组

name 可以标记这个预览图的名称。在每个预览图的上方会有各个预览图的名称
group 可以对这些 Preview 分组。在右手边预览区块的左上角，会有下拉选单，可以分群检视

装置组

apiLevel , device 可以来模拟运行的装置，showSystemUi 则可以显示边框

画面组

widthDp 和 heightDp 可以预览这个 component 装在不同大小的区块时的情景
最後如同前面说到的，showBackground 可以显示 default 白色的背景，还可以用backgroundColor 调整颜色

系统设定组

uiMode 主要是可以调整 Day / Night 、fontScale 可以模拟 user 设定的文字大小，locale 则可以展示不同语系。

在 Android Developer's Backstage podcast 中有聊到，目前 Compose 的 Preview 当有结构改变时就需要重新 compile。因为在 Compose 中，基本上每个 component 都可以说是一个 custom view 。原本 xml 的预览工具，Android Studio 可以用预先产好的画面做拼装；但 Compose 没有任何画面可以被“预产”，於是每次修改都要请 Gradle 重新 compile 一次。因此，越小的 module 其实是有利於 preview 的运算与展示的

另外， primitive type 的参数调整，就可以立即看到修改。例如 padding 、长宽、文字等等。

我觉得写 Compose 的 Preview 很像写 TDD，在架构 Composable function 之前先把 Preview 开出来、同时开出 function 的 signature，等於时先确立 interface 後再来完成 function 内部的实作。用这种单元化的工作流程处理 UI 的工作，也更能将问题简化，是很方便好用的工具。

不过我一直找不到证据来证明，如果我写了很多很多的 Preview，会不会对专案或是 app 造成任何的负担？这题看来就只好等之後再来研究了。

reference:

• EXPLORING JETPACK COMPOSE: @PREVIEW ANNOTATION
• @Preview Annotation Properties
• Compose tooling  |  Android Developers
• Android Developers Backstage - Episode 174: Compose tooling