原生移动开发 / 系统课时
Compose Preview
Compose Preview
Compose Preview 让你不启动模拟器也能检查 Composable 的外观。本文用同一个组件分别预览普通设备、深色主题和不同业务状态,并说明预览函数的限制与验证方式。
学习目标
- 使用
@Preview为 Composable 创建可视化预览 - 分别验证设备尺寸、明暗主题和组件状态
- 识别 Preview 可做什么,以及何时仍需真机或模拟器验证
写出可预览的组件
Preview 的核心不是给业务组件“加预览能力”,而是额外写一个无参数的 @Composable 函数,在其中传入一组固定状态。业务组件继续保持参数化,这样预览和运行时界面使用的是同一份 UI 代码。
下面示例把消息卡片的状态放在参数中,再创建三个 Preview。device 选择一个预置手机设备,uiMode 用来切换夜间模式,第三个预览则直接传入错误状态。
package com.example.previewdemo
import android.content.res.Configuration
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Devices
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
@Composable
fun PreviewTheme(content: @Composable () -> Unit) {
val colors = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
MaterialTheme(colorScheme = colors, content = content)
}
@Composable
fun StatusCard(
title: String,
detail: String
) {
Surface {
Column(modifier = Modifier.padding(16.dp)) {
Text(text = title, style = MaterialTheme.typography.titleMedium)
Text(text = detail, style = MaterialTheme.typography.bodyMedium)
}
}
}
@Preview(
name = "Phone",
showBackground = true,
device = Devices.PIXEL_4
)
@Composable
private fun PhonePreview() {
PreviewTheme {
StatusCard("同步完成", "所有数据已经更新")
}
}
@Preview(
name = "Dark",
showBackground = true,
uiMode = Configuration.UI_MODE_NIGHT_YES
)
@Composable
private fun DarkPreview() {
PreviewTheme {
StatusCard("同步完成", "所有数据已经更新")
}
}
@Preview(name = "Error", showBackground = true)
@Composable
private fun ErrorPreview() {
PreviewTheme {
StatusCard("同步失败", "请检查网络后重试")
}
}预期结果:Android Studio 的 Compose Preview 区域会出现三个独立预览,分别显示 Pixel 4 设备、深色模式和错误状态。实际渲染尺寸会受 Android Studio 与 Compose 工具版本影响。
调整设备、主题与状态
@Preview 只负责描述预览环境。设备差异适合放在 device,主题差异可以通过 uiMode 或你自己的主题参数表达;业务状态不要写进 @Preview 参数,而应像示例一样传给真正的 Composable。
如果一个组件有“加载、成功、失败”三种状态,可以写三个短小的预览函数。这样每个预览只回答一个问题,也更容易在代码评审时发现某个状态被遗漏。
知道 Preview 的边界
Preview 适合检查布局、排版、颜色和固定状态,但它不是完整运行环境。依赖 Activity 生命周期、运行时权限、真实导航、相机、定位、蓝牙或网络的数据,仍应在模拟器或真机中验证。
如果预览区域报错,先把问题缩小到一个纯 UI 组件:移除外部依赖,传入固定数据,再重新渲染。能在 Preview 中稳定展示的组件,通常也更容易测试和复用。