2-Compose开发-第一个Compose项目
·
创建第一个Compose项目，熟悉预览功能
恭喜你完成了声明式思想的学习！现在，让我们动手创建第一个 Jetpack Compose 项目，并深入掌握预览功能——这是 Compose 开发中提升效率的利器。本文将从环境准备、项目创建、核心代码解析，到预览功能的详细使用和动手实践，带你全面入门 Compose 开发。
一、创建第一个 Compose 项目（Android Studio 环境）
1. 前置条件
在开始之前，确保你的开发环境满足以下要求：
- Android Studio：版本 Electric Eel (2022.1.1) 或更高（推荐使用最新版 Hedgehog/Ijjira）。低版本对 Compose 支持不完善。
- JDK：11 或更高版本。
- Android SDK：API 级别 21 或更高（正式开发建议 24+）。
2. 分步创建项目
步骤 1：新建项目
打开 Android Studio → 点击「New Project」→ 在模板列表中选择 「Empty Compose Activity」（这是专门为 Compose 准备的空项目模板）→ 点击「Next」。
步骤 2：配置项目信息
- Name：填写项目名（如
FirstComposeApp） - Package name：自定义包名（如
com.example.firstcomposeapp） - Language：选择「Kotlin」（Compose 仅支持 Kotlin）
- Minimum SDK：建议选择 24 及以上 → 点击「Finish」
步骤 3：等待项目初始化
Android Studio 会自动下载 Compose 相关依赖（如 compose-ui、compose-material3 等），首次创建可能需要几分钟，耐心等待 Gradle 同步完成。
3. 项目核心结构解析
创建完成后，你会看到以下关键文件和目录：
FirstComposeApp/
├── app/
│ ├── src/main/
│ │ ├── java/com/example/firstcomposeapp/
│ │ │ └── MainActivity.kt # Compose 入口 Activity
│ │ ├── ui/theme/ # 自动生成的主题相关文件
│ │ │ ├── Color.kt # 颜色定义
│ │ │ ├── Theme.kt # 主题配置（Material3）
│ │ │ └── Type.kt # 排版定义
│ │ └── AndroidManifest.xml
│ └── build.gradle.kts # 模块级构建文件
└── settings.gradle.kts # 项目级配置
关键依赖说明（在 app/build.gradle.kts 中）：
dependencies {
// Compose 核心库
implementation("androidx.compose.ui:ui:1.6.0")
// Material Design 3 组件
implementation("androidx.compose.material3:material3:1.2.0")
// Compose 预览支持库（关键！）
implementation("androidx.compose.ui:ui-tooling-preview:1.6.0")
// Activity 集成 Compose
implementation("androidx.activity:activity-compose:1.8.0")
// 调试阶段才需要的工具库
debugImplementation("androidx.compose.ui:ui-tooling:1.6.0")
}
二、核心代码解析（默认生成的项目）
1. MainActivity.kt 完整代码
package com.example.firstcomposeapp
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
import com.example.firstcomposeapp.ui.theme.FirstComposeAppTheme
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// setContent 是 Compose 的入口，替代传统的 setContentView
setContent {
// 应用 Compose 主题（Material3）
FirstComposeAppTheme {
// Surface：Material Design 的基础容器，提供背景等
Surface(
modifier = Modifier.fillMaxSize(),
color = MaterialTheme.colorScheme.background
) {
// 调用自定义可组合函数
Greeting("Android")
}
}
}
}
}
// 这是一个可组合函数，用 @Composable 注解标记
@Composable
fun Greeting(name: String, modifier: Modifier = Modifier) {
Text(
text = "Hello $name!",
modifier = modifier
)
}
// 预览函数，用于在 IDE 中查看 UI 效果
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
FirstComposeAppTheme {
Greeting("Compose")
}
}
2. 关键代码解释
| 代码/注解 | 作用 |
|---|---|
setContent { ... } | 替代传统 setContentView，用于设置 Compose 编写的 UI 内容 |
@Composable | 标记 Compose 函数，只能在其他 @Composable 函数中调用，用于描述 UI |
Modifier | Compose 的 UI 修饰符，用于控制布局（大小、位置）、样式、交互等 |
@Preview | 预览注解，标记预览函数，Android Studio 会在右侧显示 UI 预览效果 |
showBackground = true | 预览时显示背景色，便于查看 UI 边界 |
MaterialTheme | Compose 的 Material Design 3 主题，统一管理颜色、字体、形状等样式规范 |
三、熟悉 Compose 预览功能（核心重点）
预览是 Compose 最具生产力的特性之一，它让你在不运行应用的情况下直接看到 UI 效果。下面从基础到高级，详细讲解预览功能。
1. 基础预览使用
查看预览效果
- 打开
MainActivity.kt，找到GreetingPreview函数。 - Android Studio 右侧会自动显示「Preview」面板，展示
Hello Compose!的预览效果。 - 如果没显示，可以点击代码左侧的「Preview」小图标（类似眼睛），或按
Alt+Shift+P（Windows）/Option+Shift+P（Mac）。
修改代码实时预览
- 把
Greeting函数中的text = "Hello $name!"改成text = "你好，$name!"； - 预览面板会实时刷新，无需编译/运行 App，立即看到「你好，Compose!」的效果。
2. 预览参数配置
@Preview 注解支持多种参数，帮助你模拟不同场景：
@Preview(
// 显示名称（在预览面板中标识）
name = "Dark Mode Preview",
// 分组（便于组织多个预览）
group = "greeting",
// 显示背景
showBackground = true,
// 背景颜色（ARGB 格式）
backgroundColor = 0xFFFF0000, // 红色背景
// 设置预览宽度（dp）
widthDp = 200,
// 设置预览高度（dp）
heightDp = 100,
// 模拟不同语言环境
locale = "de-rDE", // 德语
// 显示系统状态栏
showSystemUi = true,
// 模拟不同设备
device = "spec:width=360dp,height=640dp,dpi=480" // 或使用 Devices.FOLDABLE
)
@Composable
fun AdvancedPreview() {
FirstComposeAppTheme {
Greeting("Preview")
}
}
3. 多预览组合
同一个可组合函数可以添加多个 @Preview 注解，同时查看不同配置下的效果：
import android.content.res.Configuration
@Preview(name = "Light Mode", uiMode = Configuration.UI_MODE_NIGHT_NO)
@Preview(name = "Dark Mode", uiMode = Configuration.UI_MODE_NIGHT_YES)
@Composable
fun ThemePreview() {
FirstComposeAppTheme {
Greeting("Multi Preview")
}
}
4. 预览带参数的 Composable
如果可组合函数需要参数，有几种方式支持预览：
方法一：包装函数（最简单）
@Preview
@Composable
fun GreetingWrapper() {
Greeting(name = "Jetpack Compose")
}
方法二：默认参数值
@Composable
fun Greeting(name: String = "Compose") {
Text(text = "Hello $name!")
}
方法三：使用 @PreviewParameter（高级）
import androidx.compose.ui.tooling.preview.PreviewParameter
import androidx.compose.ui.tooling.preview.PreviewParameterProvider
class NameProvider : PreviewParameterProvider<String> {
override val values = sequenceOf("Alice", "Bob", "Charlie")
}
@Preview
@Composable
fun ParameterizedGreeting(
@PreviewParameter(NameProvider::class) name: String
) {
Greeting(name)
}
5. 预览分组管理
当有多个预览时，可以通过 group 参数分组，便于筛选：
@Preview(group = "profile")
@Composable
fun ProfileSmall() { /* ... */ }
@Preview(group = "profile")
@Composable
fun ProfileLarge() { /* ... */ }
在预览面板右上角可以按组筛选显示。
6. 预览功能注意事项
- 预览函数不能有参数（必须无参）；
- 预览函数必须同时标记
@Composable和@Preview； - 预览仅在 Android Studio 中生效，运行 App 时不会执行预览函数；
- 如果预览面板报错，先检查：① 代码无语法错误 ② Gradle 同步完成 ③ Android Studio 版本足够新。
四、动手实践：构建一个简单的 Quote 卡片
让我们创建一个显示名言警句的卡片组件，充分体验预览功能。
1. 创建 QuoteCard 组件
在 MainActivity.kt 中添加以下代码：
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Surface
import androidx.compose.ui.unit.dp
import androidx.compose.ui.draw.shadow
@Composable
fun QuoteCard(quote: String, author: String) {
Surface(
color = MaterialTheme.colorScheme.primaryContainer,
modifier = Modifier
.padding(16.dp)
.fillMaxWidth()
.wrapContentHeight()
.shadow(4.dp, RoundedCornerShape(12.dp)),
shape = RoundedCornerShape(12.dp)
) {
Column(modifier = Modifier.padding(16.dp)) {
Text(
text = "\"$quote\"",
style = MaterialTheme.typography.headlineSmall,
color = MaterialTheme.colorScheme.onPrimaryContainer
)
Spacer(modifier = Modifier.height(8.dp))
Text(
text = "- $author",
style = MaterialTheme.typography.bodyLarge,
color = MaterialTheme.colorScheme.onPrimaryContainer
)
}
}
}
2. 更新主界面
修改 setContent 中的内容：
setContent {
FirstComposeAppTheme {
Surface(
modifier = Modifier.fillMaxSize(),
color = MaterialTheme.colorScheme.background
) {
QuoteCard(
quote = "The best way to predict the future is to invent it.",
author = "Alan Kay"
)
}
}
}
3. 添加多种预览
@Preview(showBackground = true, name = "Default Quote")
@Composable
fun QuoteCardPreview() {
FirstComposeAppTheme {
QuoteCard(
quote = "Imagination is more important than knowledge.",
author = "Albert Einstein"
)
}
}
@Preview(showBackground = true, widthDp = 200, name = "Compact View")
@Composable
fun CompactQuotePreview() {
FirstComposeAppTheme {
QuoteCard(
quote = "Less is more",
author = "Ludwig Mies van der Rohe"
)
}
}
@Preview(showBackground = true, uiMode = Configuration.UI_MODE_NIGHT_YES)
@Composable
fun DarkModeQuotePreview() {
FirstComposeAppTheme {
QuoteCard(
quote = "Simplicity is the ultimate sophistication.",
author = "Leonardo da Vinci"
)
}
}
4. 查看效果
现在打开 Split 视图，你会看到：
- 三个不同配置的预览卡片
- 可以切换明暗主题查看效果
- 点击某个预览，可以在右侧调整尺寸
五、运行 Compose 项目
运行到真机/模拟器
- 连接安卓真机（开启开发者模式+USB调试），或启动安卓模拟器；
- 点击 Android Studio 顶部的「Run」按钮（绿色三角），选择设备；
- 等待编译完成，设备上会显示你构建的 UI 界面，和预览效果一致。
六、常见问题与解决方案
1. 预览不显示
- 检查依赖：确保
ui-tooling-preview已添加，且ui-tooling（debugImplementation）已配置。 - 检查注解：预览函数必须同时有
@Preview和@Composable注解。 - 清理项目：Build → Clean Project，然后重新构建。
2. 预览显示错误 "Composable functions with non-default parameters..."
- 原因：预览函数不能直接调用带必需参数的可组合函数。
- 解决：使用包装函数、默认参数或
@PreviewParameter。
3. 预览更新不及时
- 点击预览面板顶部的刷新按钮。
- 或者执行 Build → Make Project (Ctrl+F9)。
4. 预览无法显示 Material 主题
- 确保在预览函数中包裹了主题（如
FirstComposeAppTheme）。 - 检查主题文件中的颜色、字体定义是否正确。
七、总结
通过本文，你已经掌握了：
- 创建 Compose 项目的完整步骤。
- 可组合函数的基本概念和写法。
- 预览功能的详细使用方法，包括参数配置、多预览组合、分组管理、高级技巧等。
- 实践项目：构建了一个支持多种预览的 Quote 卡片。
预览功能是 Compose 开发的核心生产力工具——它让你能够快速迭代 UI，即时看到修改效果，大大减少了运行应用等待的时间。随着你深入学习，你会发现预览在组件库开发、主题适配、多设备测试等方面都能发挥巨大作用。
八、线上资料链接
官方文档
- 创建第一个 Compose 项目（官方文档）
https://developer.android.com/jetpack/compose/setup?hl=zh-cn
谷歌官方分步教程，包含环境配置、项目创建、核心概念讲解。 - Compose 预览功能详解（官方文档）
https://developer.android.com/jetpack/compose/tooling/previews?hl=zh-cn
涵盖预览的所有进阶用法（多预览、尺寸、主题、本地化等）。 - Compose 修饰符（Modifier）官方指南
https://developer.android.com/jetpack/compose/modifiers?hl=zh-cn
学习 Modifier 的核心用法，Compose UI 布局的基础。 - Compose Material3 主题配置
https://developer.android.com/jetpack/compose/themes/material3?hl=zh-cn
了解 Compose 主题的自定义，适配不同样式需求。
优秀教程
- Build Your First Compose App
https://dev.videosdk.live/developer-hub/social/jetpack-compose-tutorial-beginners - Quote of the Day 实验教程
https://coda.io/@peter-sigurdson/android-with-jet-pack-compose-lab-1-quote-of-the-day - Compose 预览高级用法
https://kotlinlang.org/docs/multiplatform/compose-previews.html
现在，打开 Android Studio，创建你的第一个 Compose 项目，并开始享受声明式 UI 和即时预览带来的高效开发体验吧！
开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。
更多推荐
8
0- 0
已为社区贡献4条内容
所有评论(0)