第二篇：搭建你的第一个 Compose 项目——开发环境与项目结构

2.1 环境准备

必备工具

工具	最低版本要求	说明
Android Studio	Koala (2024.1.1) 或更高	推荐使用最新稳定版
Kotlin	2.0+	Compose 编译器 Kotlin 2.0 起内置于 Kotlin 插件
Gradle	8.5+	Android Gradle Plugin 8.x
compileSdk	35	目标 SDK
minSdk	21+	Compose 最低支持 API 21

Compose BOM 版本

Compose BOM（Bill of Materials）统一管理所有 Compose 库版本：

// libs.versions.toml
[versions]
compose-bom = "2026.02.00"
kotlin = "2.1.0"
agp = "8.7.0"

[libraries]
compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
compose-ui = { group = "androidx.compose.ui", name = "compose-ui" }
compose-ui-graphics = { group = "androidx.compose.ui", name = "compose-ui-graphics" }
compose-ui-tooling = { group = "androidx.compose.ui", name = "compose-ui-tooling" }
compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "compose-ui-tooling-preview" }
compose-material3 = { group = "androidx.compose.material3", name = "material3" }
compose-activity = { group = "androidx.activity", name = "activity-compose" }
compose-navigation = { group = "androidx.navigation", name = "navigation-compose" }
compose-lifecycle = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose" }

2.2 使用模板创建项目

Android Studio 创建新项目时选择 "Empty Activity (Compose)" 模板，会自动配置好 Compose 依赖。

创建后项目的关键文件结构：

MyApp/
├── app/
│   ├── build.gradle.kts        # 模块构建配置
│   └── src/main/
│       ├── AndroidManifest.xml
│       └── java/com/example/myapp/
│           ├── MainActivity.kt   # 入口 Activity
│           └── ui/theme/         # 主题目录
│               ├── Color.kt
│               ├── Theme.kt
│               └── Type.kt
├── build.gradle.kts             # 项目级构建
├── settings.gradle.kts
└── gradle/
    └── libs.versions.toml       # 版本目录

app/build.gradle.kts 关键配置

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)  // Kotlin 2.0+ 的 Compose 编译器
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 24
        targetSdk = 35
        versionCode = 1
        versionName = "1.0"
    }

    buildFeatures {
        compose = true
    }
}

dependencies {
    // Compose BOM —— 统一版本管理
    val composeBom = platform(libs.compose.bom)
    implementation(composeBom)

    implementation(libs.compose.ui)
    implementation(libs.compose.ui.graphics)
    implementation(libs.compose.ui.tooling.preview)
    implementation(libs.compose.material3)
    implementation(libs.compose.activity)
    implementation(libs.compose.lifecycle)

    // Debug
    debugImplementation(libs.compose.ui.tooling)
    debugImplementation(libs.compose.ui.test.manifest)
}

2.3 Hello World 详解

package com.example.myapp

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.myapp.ui.theme.MyAppTheme

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 1. 使用 setContent 替代 setContentView
        setContent {
            // 2. 主题包裹
            MyAppTheme {
                // 3. Surface 提供背景色和裁剪边界
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    // 4. 你的第一个 Composable
                    Greeting("Android")
                }
            }
        }
    }
}

// 5. 定义可组合函数
@Composable
fun Greeting(name: String, modifier: Modifier = Modifier) {
    Text(
        text = "Hello $name!",
        modifier = modifier
    )
}

// 6. 预览 —— 无需编译运行即可看到 UI
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
    MyAppTheme {
        Greeting("Android")
    }
}

逐行解读：

• setContent：Compose 的入口函数，将 Composable 树设置到 Activity 的内容视图中。它在内部创建了一个 ComposeView 并 set 到 DecorView 中。
• MyAppTheme：自动生成的主题包装器，控制颜色、字体、形状。后续文章详解。
• Surface：Material Design 中的基础容器，提供背景色、圆角剪裁等。相当于传统 View 中的根布局。
• Modifier.fillMaxSize()：Modifier 链的起始，填充父布局的最大尺寸。
• @Composable：注解标识这是一个可组合函数，编译器插件会为其插入重组追踪代码。
• @Preview：让 Android Studio 的 Preview 面板渲染此函数。

2.4 项目结构深度解析

Theme 目录

// Color.kt
val Blue80 = Color(0xFFB3D4FF)
val BlueGrey80 = Color(0xFFB0C4DE)
// ...更多颜色

// Type.kt
val Typography = Typography(
    bodyLarge = TextStyle(
        fontFamily = FontFamily.Default,
        fontWeight = FontWeight.Normal,
        fontSize = 16.sp
    )
)

// Theme.kt
@Composable
fun MyAppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    // 根据条件选择颜色方案
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context)
            else dynamicLightColorScheme(context)
        }
        darkTheme -> DarkColorScheme
        else -> LightColorScheme
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = Typography,
        content = content
    )
}

Module 级 build.gradle.kts 注意事项

// Kotlin 2.0+ 的 Compose 编译器配置
plugins {
    alias(libs.plugins.kotlin.compose)  // 自动配置 compiler plugin
}

// 或者手动配置（Kotlin < 2.0）
composeOptions {
    kotlinCompilerExtensionVersion = "1.5.15"
}

重要更新：从 Kotlin 2.0 开始，Compose 编译器不再作为独立的 Gradle 插件发布，而是集成到 Kotlin 编译器中。使用 kotlin("plugin.compose") 或 kotlin-compose 插件来启用。

2.5 常见问题与排错

Q1：编译时报 Incompatible Compose compiler version

原因：Kotlin 版本与 Compose 编译器版本不匹配
解决：使用 Compose BOM 管理版本，确保 kotlin 和 compose compiler 对应

Compose Compiler 与 Kotlin 版本对应关系（Kotlin 2.0+）：

Kotlin	Compose Compiler
2.0.0	2.0.0
2.0.10	2.0.10
2.1.0	2.1.0

// 正确方式 —— 使用 Kotlin 内置的 Compose 编译器
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.0.0"
}

Q2：Preview 不显示

• 确保添加了 @Preview 注解
• 确保函数有 @Composable 注解
• 重启 Android Studio 的 Preview 面板
• 检查是否是 Internal 或 Private 函数（Preview 不支持 Private）

Q3：编译超慢

• 升级 Gradle 到 8.7+ 利用缓存
• 使用 Compose BOM 避免版本冲突
• Debug 构建使用 debugImplementation 引入 Tooling 库

2.6 本章练习

1. 使用模板创建你的第一个 Compose 项目
2. 修改 Greeting 函数的文字内容，观察 Preview 实时更新
3. 在 Text 上添加 Modifier：fontSize(24.sp)、fontWeight(FontWeight.Bold) 观察变化
4. 添加一个 Button 和一个点击计数显示

// 💡 参考答案
@Composable
fun GreetingWithCounter() {
    var count by remember { mutableStateOf(0) }

    Column(
        horizontalAlignment = Alignment.CenterHorizontally,
        modifier = Modifier.padding(16.dp)
    ) {
        Text("点击了 $count 次")
        Button(onClick = { count++ }) {
            Text("点我")
        }
    }
}

2.7 本章小结

内容	要点
环境准备	Android Studio + Kotlin 2.0+ + Compose BOM
入口函数	setContent 替代 setContentView
三个组件	Theme 提供主题、Surface 提供容器、Composable 函数描述 UI
预览机制	@Preview 注解实现实时 UI 预览
版本管理	使用 Compose BOM 统一管理所有 Compose 库版本

下一篇：深入理解可组合函数——Compose 的构建基石。