快速入门

为了在使用 Compose 进行开发时获得最佳体验,请下载并安装 Android Studio。它包含许多智能编辑器功能,例如新项目模板以及立即预览 Compose 界面和动画的功能。

获取 Android Studio

请按照下列说明创建新的 Compose 应用项目,为现有应用项目设置 Compose,或导入使用 Compose 编写的示例应用。

创建支持 Compose 的新应用

如果您想要创建一个默认支持 Compose 的新项目,Android Studio 提供了新项目模板来帮助您入手。如需创建正确设置了 Compose 的新项目,请按以下步骤操作:

  1. 如果您位于 Welcome to Android Studio 窗口中,请点击 Start a new Android Studio project。如果您已打开 Android Studio 项目,请从菜单栏中依次选择 File > New > New Project
  2. Select a Project Template 窗口中,选择 Empty Compose Activity,然后点击 Next
  3. Configure your project 窗口中,执行以下操作:
    1. 按照常规方法设置 Name、Package nameSave location。请注意,在 Language 下拉菜单中,Kotlin 是唯一可用的选项,因为 Jetpack Compose 仅适用于使用 Kotlin 编写的类。
    2. Minimum API level dropdown 菜单中,选择 API 级别 21 或更高级别。
  4. 点击 Finish

现在,您可以开始使用 Jetpack Compose 开发应用了。为了帮助您入门并了解使用该工具包可以做些什么,请试试 Jetpack Compose 教程

为现有应用设置 Compose

要开始使用 Compose,您需要先向项目中添加一些 build 配置。将以下定义添加到应用的 build.gradle 文件中:

Groovy

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.3.2"
    }
}

Kotlin

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.3.2"
    }
}

需要注意以下几点:

  • 在 Android BuildFeatures 代码块内将 compose 标志设置为 true 会启用 Compose 功能。
  • ComposeOptions 代码块中定义的 Kotlin 编译器扩展版本控制与 Kotlin 版本控制相关联。请务必参阅兼容性对应图,并选择与您项目的 Kotlin 版本匹配的库版本。

此外,请将以下部分中您需要的 Compose BoM 和 Compose 库依赖项的子集添加到您的依赖项:

Groovy

dependencies {

    def composeBom = platform('androidx.compose:compose-bom:2022.10.00')
    implementation composeBom
    androidTestImplementation composeBom

    // Choose one of the following:
    // Material Design 3
    implementation 'androidx.compose.material3:material3'
    // or Material Design 2
    implementation 'androidx.compose.material:material'
    // or skip Material Design and build directly on top of foundational components
    implementation 'androidx.compose.foundation:foundation'
    // or only import the main APIs for the underlying toolkit systems,
    // such as input and measurement/layout
    implementation 'androidx.compose.ui:ui'

    // Android Studio Preview support
    implementation 'androidx.compose.ui:ui-tooling-preview'
    debugImplementation 'androidx.compose.ui:ui-tooling'

    // UI Tests
    androidTestImplementation 'androidx.compose.ui:ui-test-junit4'
    debugImplementation 'androidx.compose.ui:ui-test-manifest'

    // Optional - Included automatically by material, only add when you need
    // the icons but not the material library (e.g. when using Material3 or a
    // custom design system based on Foundation)
    implementation 'androidx.compose.material:material-icons-core'
    // Optional - Add full set of material icons
    implementation 'androidx.compose.material:material-icons-extended'
    // Optional - Add window size utils
    implementation 'androidx.compose.material3:material3-window-size-class'

    // Optional - Integration with activities
    implementation 'androidx.activity:activity-compose:1.5.1'
    // Optional - Integration with ViewModels
    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.5.1'
    // Optional - Integration with LiveData
    implementation 'androidx.compose.runtime:runtime-livedata'
    // Optional - Integration with RxJava
    implementation 'androidx.compose.runtime:runtime-rxjava2'

}

Kotlin

dependencies {

    val composeBom = platform("androidx.compose:compose-bom:2022.10.00")
    implementation composeBom
    androidTestImplementation composeBom

    // Choose one of the following:
    // Material Design 3
    implementation("androidx.compose.material3:material3")
    // or Material Design 2
    implementation("androidx.compose.material:material")
    // or skip Material Design and build directly on top of foundational components
    implementation("androidx.compose.foundation:foundation")
    // or only import the main APIs for the underlying toolkit systems,
    // such as input and measurement/layout
    implementation("androidx.compose.ui:ui")

    // Android Studio Preview support
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")

    // UI Tests
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
    debugImplementation("androidx.compose.ui:ui-test-manifest")

    // Optional - Included automatically by material, only add when you need
    // the icons but not the material library (e.g. when using Material3 or a
    // custom design system based on Foundation)
    implementation("androidx.compose.material:material-icons-core")
    // Optional - Add full set of material icons
    implementation("androidx.compose.material:material-icons-extended")
    // Optional - Add window size utils
    implementation("androidx.compose.material3:material3-window-size-class")

    // Optional - Integration with activities
    implementation("androidx.activity:activity-compose:1.5.1")
    // Optional - Integration with ViewModels
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.5.1")
    // Optional - Integration with LiveData
    implementation("androidx.compose.runtime:runtime-livedata")
    // Optional - Integration with RxJava
    implementation("androidx.compose.runtime:runtime-rxjava2")

}

尝试 Jetpack Compose 示例应用

如要试用 Jetpack Compose 功能,最快的方法是尝试在 GitHub 上托管的 Jetpack Compose 示例应用。如需从 Android Studio 导入示例应用项目,请按以下步骤操作:

  1. 如果您位于 Welcome to Android Studio 窗口中,请选择 Import an Android code sample。如果您已打开 Android Studio 项目,请从菜单栏中依次选择 File > New > Import Sample
  2. Browse Samples 向导顶部附近的搜索栏中,输入“compose”。
  3. 从搜索结果中选择一个 Jetpack Compose 示例应用,然后点击 Next
  4. 您可以更改 Application nameProject location,也可以保留默认值。
  5. 点击 Finish

Android Studio 会将示例应用下载到您指定的路径并打开项目。然后,您可以在 IDE 预览界面中检查每个示例中的 MainActivity.kt,以查看各种 Jetpack Compose API 的效果,例如,交叉淡入淡出动画、自定义组件、使用字体排版以及显示浅色和深色。

如需使用适用于 Wear OS 的 Jetpack Compose,请参阅在 Wear OS 上设置 Jetpack Compose

使用物料清单

借助 Compose 物料清单 (BoM),您只需指定 BoM 的版本,即可管理所有 Compose 库版本。BoM 本身包含指向不同 Compose 库的稳定版的链接,以便它们能够很好地协同工作。在应用中使用 BoM 时,您无需向 Compose 库依赖项本身添加任何版本。更新 BoM 版本时,您使用的所有库都会自动更新到新版本。

如需了解哪些 Compose 库版本已映射到特定 BoM 版本,请查看 BoM 到库的版本映射

为什么 BoM 中不包含 Compose 编译器库?

Compose Kotlin 编译器扩展 (androidx.compose.compiler) 未关联到 Compose 库版本。相反,它会关联到 Kotlin 编译器插件的版本,并与 Compose 的其余部分分开发布,因此请务必使用与您的 Kotlin 版本兼容的版本。您可以在 Compose 与 Kotlin 的兼容性对应关系页面找到映射到每个插件版本的 Kotlin 版本。

如何使用 BoM 中未指定的库版本?

build.gradle 依赖项部分中,保留 BoM 平台的导入内容。在导入库依赖项时,指定所需的版本。例如,如果您想使用 Alpha 版 Material 3(无论 BoM 中指定了哪个版本),声明依赖项的方法如下:

dependencies {
    // Import the Compose BOM
    implementation platform('androidx.compose:compose-bom:2022.10.00')

    // Override Material Design 3 library version with a pre-release version
    implementation 'androidx.compose.material3:material3:1.1.0-alpha01'

    // Import other Compose libraries without version numbers
    // ..
    implementation 'androidx.compose.foundation:foundation'
}

BoM 是否会自动将所有 Compose 库添加到我的应用中?

不会。要在您的应用中实际添加和使用 Compose 库,您必须在模块(应用级)Gradle 文件(通常是 app/build.gradle)中将每个库声明为单独的依赖项行。

使用 BoM 可确保应用中的任何 Compose 库版本兼容,但 BoM 实际上并不会将这些 Compose 库添加到您的应用中。

今后,Compose 库将单独进行版本控制,这意味着版本号将开始按照自己的节奏递增。每个库的最新稳定版本已经过测试,并保证能够很好地协同工作。不过,找到每个库的最新稳定版本可能比较困难,而 BoM 会帮助您自动使用这些最新版本。

我是否必须使用 BoM?

不会。您仍然可以选择手动添加各个依赖项版本。不过,我们建议您使用 BoM,因为这样您可以更轻松地同时使用所有最新的稳定版本。

BoM 是否支持版本目录?

支持。您可以在版本目录中添加 BoM 本身,并省略其他 Compose 库版本:

[libraries]
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "androidxComposeBom" }
androidx-compose-foundation = { group = "androidx.compose.foundation", name = "foundation" }

不要忘记在模块的 build.gradle 中导入 BoM:

dependencies {
    val composeBom = platform(libs.androidx.compose.bom)
    implementation(composeBom)
    androidTestImplementation(composeBom)

    // import Compose dependencies as usual
}

如何报告问题或提供与 BoM 有关的反馈?

您可以在我们的问题跟踪器上提交问题。

BoM 到库的版本映射

库组 版本 (2022.10.00) 版本 (2022.11.00)
androidx.compose.animation:animation 1.3.0 1.3.1
androidx.compose.animation:animation-core 1.3.0 1.3.1
androidx.compose.animation:animation-graphics 1.3.0 1.3.1
androidx.compose.foundation:foundation 1.3.0 1.3.1
androidx.compose.foundation:foundation-layout 1.3.0 1.3.1
androidx.compose.material:material 1.3.0 1.3.1
androidx.compose.material:material-icons-core 1.3.0 1.3.1
androidx.compose.material:material-icons-extended 1.3.0 1.3.1
androidx.compose.material:material-ripple 1.3.0 1.3.1
androidx.compose.material3:material3 1.0.0 1.0.1
androidx.compose.material3:material3-window-size-class 1.0.0 1.0.1
androidx.compose.runtime:runtime 1.3.0 1.3.1
androidx.compose.runtime:runtime-livedata 1.3.0 1.3.1
androidx.compose.runtime:runtime-rxjava2 1.3.0 1.3.1
androidx.compose.runtime:runtime-rxjava3 1.3.0 1.3.1
androidx.compose.runtime:runtime-saveable 1.3.0 1.3.1
androidx.compose.ui:ui 1.3.0 1.3.1
androidx.compose.ui:ui-geometry 1.3.0 1.3.1
androidx.compose.ui:ui-graphics 1.3.0 1.3.1
androidx.compose.ui:ui-test 1.3.0 1.3.1
androidx.compose.ui:ui-test-junit4 1.3.0 1.3.1
androidx.compose.ui:ui-test-manifest 1.3.0 1.3.1
androidx.compose.ui:ui-text 1.3.0 1.3.1
androidx.compose.ui:ui-text-google-fonts 1.3.0 1.3.1
androidx.compose.ui:ui-tooling 1.3.0 1.3.1
androidx.compose.ui:ui-tooling-data 1.3.0 1.3.1
androidx.compose.ui:ui-tooling-preview 1.3.0 1.3.1
androidx.compose.ui:ui-unit 1.3.0 1.3.1
androidx.compose.ui:ui-util 1.3.0 1.3.1
androidx.compose.ui:ui-viewbinding 1.3.0 1.3.1