今天大概會聊到的範圍

@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