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“拆分视图”选择器

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

@Preview 接受参数以自定义 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 标签页,显示了采用所有配置的可组合项

代码导航和可组合项大纲

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

用户将鼠标悬停在预览上,使 Studio 显示其可组合项的大纲

复制 @Preview 呈现

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

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

设置背景颜色

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

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

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

尺寸

默认情况下,系统会自动选择 @Preview 尺寸来封装其内容。如需手动设置尺寸,可以添加 heightDpwidthDp 参数。请注意,这些值已解释为 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)
}

界面模式

参数 uiMode 可接受任意 Configuration.UI_* 常量,并允许您相应地更改预览的行为。例如,您可以将预览设置为夜间模式,看看主题如何响应。

Compose 预览界面

编辑器操作

Android Studio 在编辑器区域也提供了一些功能,可提高使用 Jetpack Compose 时的工作效率。

实时模板

Android Studio 添加了下面这些与 Compose 相关的实时模板,您可以通过输入相应的模板缩写来输入代码段,以实现快速插入:

  • comp,用于设置 @Composable 函数
  • prev,用于创建 @Preview 可组合函数
  • paddp,用于以 dp 为单位添加 padding 修饰符
  • weight,用于添加 weight 修饰符
  • WWRWC,用于通过 BoxRowColumn 容器设置当前可组合项的呈现效果

边线图标

边线图标是边栏中可见的上下文操作,位于行号旁边。Android Studio 引入了多个 Jetpack Compose 专用边线图标,以便开发者更轻松地使用。

部署预览

您可以直接通过边线图标将 @Preview 部署到模拟器或实体设备上:

用户点击预览函数的部署边线图标,并将预览部署到设备上

颜色选择器

无论是在可组合项内部还是外部定义颜色,边线上都会显示其预览。您可以点击颜色,通过颜色选择器进行更改,如下所示:

用户点击边线中的颜色,弹出一个颜色选择器

图像资源选择器

无论是在可组合项内部还是外部定义可绘制对象、矢量或图像,边线上都会显示其预览。您可以点击它,通过图像资源选择器进行更改,如下所示:

用户点击边线中的图标,弹出资源选择器

迭代代码开发

作为移动开发者,您通常需要逐步开发应用界面,而不是一次性开发所有内容。Android Studio 通过提供不需要完整 build 即可检查、修改值和验证最终结果的工具,支持使用 Jetpack Compose 进行逐步开发。

实时修改字面量

Android Studio 可以实时更新在预览、模拟器和实体设备中的可组合项中使用的一些常量字面量。下面是一些受支持的类型:

  • Int
  • String
  • Color
  • Dp
  • Boolean

用户在源代码中更改字面量且预览动态更新的视频

通过“Live Edit of Literals”界面指示器启用字面量修饰功能,无需进行编译即可查看触发实时更新的常量字面量:

启用“Live Editing of Literals”

实时编辑

您可以在 Android Studio Electric Eel 的 Canary 版本中使用实时编辑功能加快 Compose 开发过程。相较于实时编辑字面量功能,“实时编辑”是具备更强大功能的版本。借助此功能,您可以自动将代码更改部署到模拟器或设备上,从而实时查看可组合项更新后的效果。

实时编辑界面概览

Apply Changes

Apply Changes 可让您更新代码和资源,而不必将应用重新部署到模拟器或实体设备上,不过,这项功能存在一些限制

每当您添加、修改或删除可组合项时,您只需点击一下此按钮,即可更新应用,而不必重新部署:

用户点击“Apply Changes”按钮

布局检查器

借助布局检查器,您可以在模拟器或实体设备上检查正在运行的应用中的 Compose 布局。

获取重组次数

您可以使用布局检查器检查某个可组合项的重组频率或跳过重组的频率。如果界面呈现效果不佳,通常是因为出现编码错误,导致界面过度重组。另一方面,某些编码错误可能会在界面需要重组时阻止其重组,这意味着界面更改将不会呈现在屏幕上。跟踪重组有助于发现这两类问题。

如需跟踪重组,请在视图选项中启用 Show Recomposition Counts

已在视图选项中启用“Show Recomposition Counts”

启用后,布局检查器会在左侧显示重组次数,在右侧显示跳过重组的次数:

布局检查器中显示的重组次数

如果双击布局检查器中的某个可组合项,系统会将您转到相应的代码以便进行分析。

动画

Android Studio 允许您从动画预览中检查动画。如果您在可组合项预览中描述了动画效果,则可以检查每个动画值在给定时间点的确切值,并且可以暂停、循环播放、快进或放慢动画,以便在动画过渡过程中调试动画:

播放、拖动 AnimatedVisibility 以及降低 AnimatedVisibility 的速度

您还可以使用动画预览以图形方式呈现动画曲线,这对于确保正确编排动画值非常有用:

动画曲线的可视化呈现

动画预览会自动检测可检查的动画,即带有 Start Animation Inspection 图标 “Run”图标 的动画。

设计窗口中的“Start Animation Inspection”图标

动画预览目前支持 updateTransition API。如需将动画预览与 updateTransition 搭配使用,请使用 Compose 版本 1.0.1 或更高版本。

启用实验性功能

有些功能只有在 Android Studio 偏好设置的“Experimental”部分中手动启用后才能使用:File > Settings > Experimental(在 Mac 上:Android Studio > Preferences > Experimental)。

在 Android Studio 的“Experiemental”偏好设置部分内启用了 Compose 工具