可组合项由一个函数定义，并用 @Composable 进行注释
@Composable
fun SimpleComposable() {
Text("Hello World")
}
要启用此组合的可视化预览，请创建另一个组合，并使用@Composable和@Preview进行注释。这个新的带注释的组合现在包含了您最初创建的组合SimpleComposable。
@Preview
@Composable
fun SimpleComposablePreview() {
SimpleComposable()
}
该@Preview注释告诉Android Studio此组合应显示在此文件的“设计”视图中。在进行编辑时，您可以看到组合预览的实时更新。
您可以在代码中手动添加参数来自定义Android Studio渲染@Preview的方式。您甚至可以多次将@Preview注释添加到同一函数中，以使用不同的属性预览组合。
使用@Preview组合的主要优势之一是避免依赖Android Studio中的模拟器。您可以将模拟器占用大量内存的启动过程留到进行更最终的视觉效果和外观更改时，并利用@Preview轻松进行和测试小的代码更改。
为了最有效地利用@Preview注释，请确保根据其接收的输入状态和输出的事件来定义屏幕。
定义您的@Preview
Android Studio提供了一些功能来扩展组合预览。您可以更改其容器设计、与之交互或将其直接部署到模拟器或设备上。
尺寸
默认情况下，@Preview尺寸会自动选择以包裹其内容。要手动设置尺寸，请添加heightDp和widthDp参数。这些值已解释为dp，因此您无需向其添加.dp
@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
Box(Modifier.background(Color.Yellow)) {
Text("Hello World")
}
}
动态颜色预览
如果您已在应用中启用了动态颜色，请使用wallpaper属性切换壁纸，并查看 UI 对不同用户选择的壁纸的反应。从Wallpaper类提供的不同壁纸主题中进行选择。此功能需要 Compose 1.4.0 或更高版本。
与不同设备一起使用
在 Android Studio Flamingo 中，您可以编辑 Preview 注释的device参数以定义不同设备中组合的配置。
当 device 参数为空字符串（@Preview(device = "")）时，您可以通过按Ctrl + Space来调用自动完成。然后，您可以设置每个参数的值。
从自动完成中，您可以从列表中选择任何设备选项，例如@Preview(device = "id:pixel_4")。或者，您可以通过选择spec:width=px,height=px,dpi=int…来输入自定义设备，以设置每个参数的各个值。
要应用，请按Enter，或按Esc取消。
如果设置了无效值，则声明将以红色下划线显示，并且可能提供修复方案（Alt + Enter（macOS 上为⌥ + ⏎）> 替换为…。检查会尝试提供一个最接近您输入的修复方案。
区域设置
要测试不同的用户区域设置，请添加locale参数
@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
Text(text = stringResource(R.string.greeting))
}
设置背景颜色
默认情况下，您的组合将显示为透明背景。要添加背景，请添加showBackground和backgroundColor参数。请记住，backgroundColor是ARGB Long，而不是Color值
@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
Text("Hello World")
}
系统 UI
如果需要在预览中显示状态栏和操作栏，请添加showSystemUi参数
@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
Text("Hello World")
}
UI 模式
参数uiMode可以采用任何Configuration.UI_*常量，并允许您相应地更改预览的行为。例如，您可以将预览设置为夜间模式以查看主题的反应。
LocalInspectionMode
您可以从LocalInspectionModeCompositionLocal中读取以查看组合是否在预览中呈现（在可检查组件内）。如果组合在预览中呈现，则LocalInspectionMode.current将评估为true。此信息允许您自定义预览；例如，您可以在预览窗口中显示占位符图像，而不是显示真实数据。
这样，您还可以解决限制。例如，显示示例数据而不是调用网络请求。
@Composable
fun GreetingScreen(name: String) {
if (LocalInspectionMode.current) {
// Show this text in a preview window:
Text("Hello preview user!")
} else {
// Show this text in the app:
Text("Hello $name!")
}
}
与您的@Preview交互
Android Studio提供了允许您与定义的预览进行交互的功能。这种交互可以帮助您了解预览的运行时行为，并允许您更好地使用预览导航 UI。
交互模式
交互模式允许您与预览进行交互，就像在运行程序的设备（如手机或平板电脑）上一样。交互模式在沙盒环境中隔离（这意味着与其他预览隔离），您可以在其中单击元素并在预览中输入用户输入。这是一种快速测试组合的不同状态、手势甚至动画的方法。
代码导航和组合轮廓
您可以将鼠标悬停在预览上以查看其中包含的组合的轮廓。单击组合轮廓会触发编辑器视图导航到其定义。
运行预览
您可以在模拟器或物理设备上运行特定的@Preview。预览作为新的Activity部署在与同一项目应用中，因此它共享相同的上下文和权限。如果权限已授予，则不需要编写样板代码来请求权限。
单击@Preview注释旁边或预览顶部的运行预览图标
，Android Studio会将该@Preview部署到您连接的设备或模拟器上。
复制@Preview渲染
每个渲染的预览都可以通过右键单击将其复制为图像。
同一@Preview注释的多个预览
您可以展示同一@Preview组合的不同版本的不同规范，或传递给组合的不同参数。这样，您可以减少否则需要编写的样板代码。
多预览模板
androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ 引入了多预览 API 模板：@PreviewScreenSizes、@PreviewFontScales、@PreviewLightDark和@PreviewDynamicColors，以便使用单个注释即可在常见场景中预览 Compose UI。
创建自定义多预览注释
使用多预览，您可以定义一个注释类，该类本身具有多个具有不同配置的@Preview注释。将此注释添加到组合函数会自动同时渲染所有不同的预览。例如，您可以使用此注释同时预览多个设备、字体大小或主题，而无需为每个组合重复这些定义。
首先创建您自己的自定义注释类
@Preview(
name = "small font",
group = "font scales",
fontScale = 0.5f
)
@Preview(
name = "large font",
group = "font scales",
fontScale = 1.5f
)
annotation class FontScalePreviews
您可以将此自定义注释用于您的预览组合。
@FontScalePreviews
@Composable
fun HelloWorldPreview() {
Text("Hello World")
}
您可以组合多个多预览注释和普通预览注释以创建更完整的预览集。组合多预览注释并不意味着会显示所有不同的组合。相反，每个多预览注释都独立运行，仅渲染其自己的变体。
@Preview(
name = "Spanish",
group = "locale",
locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews
@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
多预览（以及普通预览！）的混合搭配特性使您可以更全面地测试大型项目的许多属性。
@Preview和大型数据集
很多时候，您需要将大型数据集传递到组合预览中。为此，只需通过添加带有@PreviewParameter注释的参数将示例数据传递到 Composable Preview 函数即可。
@Preview
@Composable
fun UserProfilePreview(
@PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
UserProfile(user)
}
要提供示例数据，请创建一个实现PreviewParameterProvider的类，并将其作为序列返回示例数据。
class UserPreviewParameterProvider : PreviewParameterProvider<User> {
override val values = sequenceOf(
User("Elise"),
User("Frank"),
User("Julia")
)
}
这将为序列中的每个数据元素渲染一个预览
您可以将同一提供程序类用于多个预览。如有必要，可以通过设置 limit 参数来限制预览数量。
@Preview
@Composable
fun UserProfilePreview2(
@PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
UserProfile(user)
}
限制和最佳实践
Android Studio 直接在预览区域中执行预览代码。它不需要运行模拟器或物理设备，因为它利用了名为Layoutlib的移植版 Android 框架。Layoutlib是 Android 框架的自定义版本，设计用于在 Android 设备外部运行。该库的目标是在 Android Studio 中提供一个布局预览，使其非常接近在设备上的渲染效果。
预览限制
由于在 Android Studio 中渲染预览的方式，它们非常轻量级，并且不需要整个 Android 框架来渲染它们。但是，这会带来以下限制
- 无法访问网络
- 无法访问文件
- 某些
ContextAPI 可能无法完全使用
预览和ViewModels
在组合中使用ViewModel时，预览存在限制。预览系统无法构造传递给ViewModel的所有参数，例如存储库、用例、管理器或类似内容。此外，如果您的ViewModel参与依赖项注入（例如使用Hilt），则预览系统无法构建整个依赖项图以构造ViewModel。
当您尝试预览带有ViewModel的组合时，Android Studio在渲染特定组合时会显示错误
如果您想预览使用 ViewModel 的可组合项，您应该创建另一个可组合项，并将 ViewModel 的参数作为该可组合项的参数传递。这样，您就不需要预览使用 ViewModel 的可组合项。
@Composable
fun AuthorColumn(viewModel: AuthorViewModel = viewModel()) {
AuthorColumn(
name = viewModel.authorName,
// ViewModel sends the network requests and makes posts available as a state
posts = viewModel.posts
)
}
@Preview
@Composable
fun AuthorScreenPreview(
// You can use some sample data to preview your composable without the need to construct the ViewModel
name: String = sampleAuthor.name,
posts: List<Post> = samplePosts[sampleAuthor]
) {
AuthorColumn(...) {
name = NameLabel(name),
posts = PostsList(posts)
}
}
注解类 @Preview
您始终可以在 Android Studio 中“ctrl 或 ⌘ + 点击” @Preview 注解，以获取可在自定义预览时调整的所有参数的完整列表。
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,
@Wallpaper val wallpaper: Int = Wallpapers.NONE,
)
其他资源
要详细了解 Android Studio 如何促进 @Preview 的易用性，并学习更多工具提示，请查看博客 Compose 工具。
为您推荐
- 注意：当 JavaScript 关闭时，将显示链接文本
- 使用 CompositionLocal 进行局部作用域数据
- Compose 中的 Material Design 2
- 在 Compose 中使用 Views