Compose 工具

Android Studio 引入了许多专用于 Jetpack Compose 的新功能。它支持使用代码优先方法，同时提高了开发者的工作效率，因为开发者不必在设计界面或代码编辑器之间二选一。

基于 View 的界面与 Jetpack Compose 之间的一个基本区别在于，Compose 不依赖 View 来呈现其可组合项。通过采用这种架构方法，Android Studio 为 Jetpack Compose 提供了扩展功能，让其不必像 Android View 一样打开模拟器或连接到设备，从而加快了开发者实现其界面设计的迭代过程。

如需为 Jetpack Compose 启用 Android Studio 特定功能，您需要在应用 build.gradle 文件中添加以下依赖项：

debugImplementation "androidx.compose.ui:ui-tooling:1.2.1"
implementation "androidx.compose.ui:ui-tooling-preview:1.2.1"

可组合项预览

可组合项由函数定义，并使用 @Composable 进行注解：

@Composable
fun SimpleComposable() {
    Text("Hello World")
}

包含“Hello World”字样的简单文本元素

如需实现此可组合项的预览，您需要再创建一个使用 @Composable 和 @Preview 进行注解的可组合项，并发出您最初创建的可组合项：

@Preview
@Composable
fun ComposablePreview() {
    SimpleComposable()
}

最后，点击拆分（设计/代码）视图，打开显示预览的右侧面板：

Android Studio“拆分视图”选择器

预览窗口中显示的简单文本视图

您可以在代码中手动添加参数，以自定义 Android Studio 呈现 @Preview 的方式。

`@Preview` 功能

Android Studio 提供了一些功能来扩展可组合项预览。您可以更改其容器设计，与之互动，或直接将其部署到模拟器或设备。

LocalInspectionMode

您可以通过读取 LocalInspectionMode CompositionLocal 来确认可组合项是否正在预览中呈现。这可让您执行诸如在预览窗口中显示占位符图片之类的操作，而不是显示实际数据。如果可组合项在预览中呈现，LocalInspectionMode.current 的结果为 true。

if (LocalInspectionMode.current) {
    // Show this text in a preview window:
    Text("Hello preview user!")
} else {
    // Show this text in the app:
    Text("Hello $name!")
}

互动模式

借助互动模式，您可以采用类似于在设备上互动的方式与预览互动。互动模式被隔离在沙盒环境中（与其他预览隔离），在该模式下，您可以在预览中点击元素并输入用户输入；预览甚至还可以播放动画。通过使用这种模式，您可以快速测试可组合项的不同状态和手势，例如勾选或清空复选框。

预览互动模式直接在 Android Studio 中运行，并未运行模拟器，因此存在一些限制：

无法访问网络
无法访问文件
有些 Context API 不一定完全可用

用户点击预览的“互动”按钮

用户与预览互动的视频

部署预览

您可以将特定 @Preview 部署到模拟器或实体设备上。预览将作为新的 activity 部署在同一项目应用中，因此它具有相同的上下文和权限，这意味着您无需编写样板代码，诸如为了实现在已获得某个权限的情况下请求该权限而编写的代码。

点击 @Preview 注解旁边或预览顶部的 Deploy to Device 图标，Android Studio 会将该 @Preview 部署到连接的设备或模拟器上。

用户点击预览的“部署”按钮

用户将预览部署到设备的视频

Multipreview 注解

使用 Multipreview 时，您可以定义一个注解类，该类本身可具有多个采用不同配置的 @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")
}

Android Studio 的 Design 标签页，显示了分别采用小号和大号字体的可组合项

您可以将多个 MultiPreview 注解和普通 preview 注解结合使用，从而创建一个更完整的预览集。结合使用 MultiPreview 注解并不意味着所有不同的组合都会得以呈现。实际上，每个 MultiPreview 注解会独立运行，并且仅会呈现自己的变体。

@Preview(
    name = "dark theme",
    group = "themes",
    uiMode = UI_MODE_NIGHT_YES
)
@FontScalePreviews
@DevicePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview() {
    MyTheme { Surface { Text("Hello world") } }
}

Android Studio 的 Design 标签页，显示了采用所有配置的可组合项

代码导航和可组合项大纲

您可以将鼠标悬停在预览上，以查看其中包含的可组合项的大纲。点击可组合项大纲会触发您的编辑器视图，从而导航到其定义。

复制 `@Preview` 呈现

通过右键点击呈现的每个预览，即可将其作为图像来复制。

用户点击预览以将其作为图像来复制。

设置背景颜色

默认情况下，您的可组合项将以透明背景来显示。如需添加背景，请添加 showBackground 和 backgroundColor 参数。请注意，backgroundColor 是 ARGB Long，而不是 Color 值：

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}

包含“Hello World”字样的绿色矩形

尺寸

默认情况下，系统会自动选择 @Preview 尺寸来封装其内容。如需手动设置尺寸，可以添加 heightDp 和 widthDp 参数。请注意，这些值已解释为 Dp，您无需在值末尾添加 .dp：

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}

包含“Hello World”字样的黄色方形

语言区域

如需测试不同的用户语言区域，您需要添加 locale 参数：

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greetings))
}

一个简单的文本元素，其中包含“Bonjour”一词和一面法国国旗

系统界面

如需在预览中显示状态栏和操作栏，请添加 showSystemUi 参数：

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}

一个预览窗口，其中显示了一个具有状态栏和操作栏的 activity

@PreviewParameter

您可以使用 @PreviewParameter 注解来添加参数，以将示例数据传递给某个可组合项预览函数。

@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 UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}