Jetpack Compose 常用控件

Jetpack Compose 作为 Android 官方推荐的现代 UI 框架，以声明式编程为核心，提供了丰富的控件体系。这些控件不仅覆盖了传统 View 系统的所有功能，还通过可组合性、状态驱动等特性简化了开发流程。本文将系统梳理 Compose 中的核心控件，从基础展示到复杂交互，助你全面掌握 UI 开发利器。

一、基础展示控件：呈现静态内容

基础展示控件用于显示文本、图片等静态内容，是构建 UI 的 “原子单元”。

1. Text：文本展示
   Text 是最基础的控件，用于显示字符串，支持丰富的样式配置。

@Preview
@Composable
fun TextExamples() {Column(modifier = Modifier.padding(16.dp).background(Color.White)) {// 基础文本Text("基础文本")// 带样式的文本Text(text = "大号粗体文本",fontSize = 20.sp,fontWeight = FontWeight.Bold,color = Color.Blue)// 多行文本与换行Text(text = "这是一段很长的文本，会自动换行显示。Compose的Text控件默认支持多行文本，无需额外配置。",maxLines = 2, // 限制最大行数overflow = TextOverflow.Ellipsis, // 超出部分显示省略号modifier = Modifier.width(200.dp))// 带点击事件的文本Text(text = "可点击文本",modifier = Modifier.clickable { println("文本被点击") }.padding(8.dp),color = Color.Red)}
}

核心属性：fontSize（字体大小）、fontWeight（字重）、color（颜色）、maxLines（最大行数）、textAlign（对齐方式）。

2. Image：图片展示
   Image 用于显示本地资源、网络图片或内存中的图像，配合 painter 指定图片源。

@Preview
@Composable
fun ImageExamples() {Column(modifier = Modifier.padding(16.dp)) {// 本地资源图片（res/drawable目录下）Image(painter = painterResource(id = R.drawable.ic_launcher_foreground),contentDescription = "应用Logo", // 无障碍描述（必传）modifier = Modifier.size(100.dp))// 网络图片（需配合Coil等库）AsyncImage(model = "https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png",contentDescription = "baidu",modifier = Modifier.size(100.dp),contentScale = ContentScale.Crop // 裁剪填充)// 圆形图片（配合clip修饰符）Image(painter = painterResource(id = R.drawable.btn_bg),contentDescription = "圆形头像",modifier = Modifier.size(80.dp).clip(CircleShape), // 圆形裁剪contentScale = ContentScale.Fit)}
}

注意：网络图片需添加 coil-compose 依赖；contentDescription 用于无障碍服务，不可省略（纯装饰性图片可传 null，但需显式声明）。

3. Icon：图标展示
   Icon 专门用于显示矢量图标（如 Material Icons），体积小且支持无损缩放。

@Preview
@Composable
fun IconExamples() {Row(Modifier.background(Color.White),horizontalArrangement = Arrangement.spacedBy(16.dp)) {// Material内置图标Icon(imageVector = Icons.Default.Home,contentDescription = "首页",tint = Color.Blue, // 图标颜色modifier = Modifier.size(24.dp))// 自定义矢量图标（res/drawable目录下的xml矢量图）Icon(painter = painterResource(id = R.drawable.ic_launcher_foreground),contentDescription = "自定义图标",modifier = Modifier.size(32.dp))}
}

常用场景：导航栏、按钮、状态指示等，常与 IconButton 结合实现点击交互。

二、交互控件：响应用户操作

交互控件是用户与 APP 交互的核心，包括按钮、开关、滑块等，需配合状态管理实现动态反馈。

1. Button：按钮
   Button 是最常用的交互控件，支持点击事件、文本 + 图标组合、样式定制。

@Preview
@Composable
fun ButtonExamples() {Column(Modifier.background(Color.White),verticalArrangement = Arrangement.spacedBy(8.dp)) {// 基础按钮Button(onClick = { println("基础按钮点击") }) {Text("确定")}// 带图标的按钮Button(onClick = { /* 点击事件 */ }) {Icon(imageVector = Icons.Default.Settings,contentDescription = null,modifier = Modifier.size(ButtonDefaults.IconSize))Spacer(modifier = Modifier.size(ButtonDefaults.IconSpacing)) // 图标与文本间距Text("设置")}// 文本按钮（无背景，仅文本样式）TextButton(onClick = { /* 点击事件 */ }) {Text("取消")}// 图标按钮（圆形，常用于工具栏）IconButton(onClick = { /* 点击事件 */ }) {Icon(imageVector = Icons.Default.Menu,contentDescription = "菜单")}// 禁用状态Button(onClick = { /* 点击事件 */ },enabled = false // 禁用按钮) {Text("禁用按钮")}}
}

扩展：通过 shape（形状）、colors（颜色）、elevation（阴影）自定义按钮样式，或使用 OutlinedButton（描边按钮）。

2. 选择控件：Checkbox、RadioButton、Switch
   这类控件用于接收用户的选择输入，通常与 mutableStateOf 绑定状态。

@Preview
@Composable
fun SelectionControls() {Column(modifier = Modifier.padding(16.dp).background(Color.White)) {// 复选框（可多选）var checked by remember { mutableStateOf(false) }Row(verticalAlignment = Alignment.CenterVertically) {Checkbox(checked = checked,onCheckedChange = { checked = it })Text("同意条款", modifier = Modifier.clickable { checked = !checked })}// 单选按钮（需配合RadioGroup逻辑）val options = listOf("选项1", "选项2", "选项3")var selectedOption by remember { mutableStateOf(options[0]) }options.forEach { option ->Row(verticalAlignment = Alignment.CenterVertically) {RadioButton(selected = selectedOption == option,onClick = { selectedOption = option })Text(option, modifier = Modifier.clickable { selectedOption = option })}}// 开关（类似复选框，常用于启用/禁用功能）var switchChecked by remember { mutableStateOf(false) }Row(verticalAlignment = Alignment.CenterVertically) {Text("开启通知")Switch(checked = switchChecked,onCheckedChange = { switchChecked = it })}}
}

注意：单选按钮需手动实现 “互斥” 逻辑（选中一个时取消其他）；所有选择控件的状态需用 remember 存储以触发重组。

3. 输入控件：TextField
TextField 用于接收用户文本输入（如登录、搜索），支持单行 / 多行、提示文本、输入验证等。

@Preview
@Composable
fun TextFieldExamples() {Column(modifier = Modifier.padding(16.dp)) {// 基础输入框var text by remember { mutableStateOf("") }TextField(value = text,onValueChange = { text = it },label = { Text("请输入内容") }, // 提示标签（聚焦时上移）modifier = Modifier.fillMaxWidth())// 密码输入框var password by remember { mutableStateOf("") }TextField(value = password,onValueChange = { password = it },label = { Text("密码") },visualTransformation = PasswordVisualTransformation(), // 密码隐藏singleLine = true, // 单行输入（避免软键盘换行）modifier = Modifier.fillMaxWidth())// 多行输入框（如备注）var note by remember { mutableStateOf("") }TextField(value = note,onValueChange = { note = it },label = { Text("备注") },maxLines = 3, // 最大3行modifier = Modifier.fillMaxWidth())}
}

进阶：通过 keyboardOptions 指定键盘类型（如 KeyboardType.Number），isError 显示错误状态，leadingIcon 添加前缀图标。

4. 其他交互控件
   Slider：滑动条，用于选择范围内的数值（如音量调节）：

@Preview
@Composable
fun SliderExample(){var sliderValue by remember { mutableStateOf(0f) }Slider(value = sliderValue,onValueChange = { sliderValue = it },valueRange = 0f..100f // 取值范围)
}

DropdownMenu：下拉菜单，点击按钮时显示选项列表：

@Preview
@Composable
fun DropDownMenuExample() {var expanded by remember { mutableStateOf(false) }Box {Button(onClick = { expanded = true }) { Text("选择选项") }DropdownMenu(expanded = expanded,onDismissRequest = { expanded = false }) {DropdownMenuItem(text = { Text("选项1") }, onClick = { expanded = false })DropdownMenuItem(text = { Text("选项2") }, onClick = { expanded = false })}}
}

三、列表与网格控件：展示大量数据

当需要展示多条数据（如联系人、商品列表）时，使用列表 / 网格控件，它们通过 “懒加载” 提升性能。

1. LazyColumn：垂直滚动列表
   LazyColumn 仅渲染可见项，适合大量数据，类似传统 RecyclerView。

@Preview
@Composable
fun LazyColumnExample() {val items = List(100) { "列表项 $it" } // 模拟100条数据LazyColumn(modifier = Modifier.fillMaxSize(),contentPadding = PaddingValues(16.dp), // 列表内边距verticalArrangement = Arrangement.spacedBy(8.dp) // 项间距) {// 头部item {Text("列表标题", fontSize = 20.sp, fontWeight = FontWeight.Bold)Spacer(modifier = Modifier.height(16.dp))}// 数据项items(items) { itemText ->Box(modifier = Modifier.fillMaxWidth().height(60.dp).background(Color.LightGray).padding(16.dp)) {Text(text = itemText)}}// 底部item {Spacer(modifier = Modifier.height(16.dp))Text("列表底部", color = Color.Gray)}}
}

核心 API：item（单个项）、items（批量项）、itemsIndexed（带索引的批量项）。

2. LazyRow：水平滚动列表
   与 LazyColumn 逻辑一致，用于水平方向的滚动列表（如图片轮播）。

@Preview
@Composable
fun LazyRowExample() {LazyRow(modifier = Modifier.height(120.dp),contentPadding = PaddingValues(16.dp),horizontalArrangement = Arrangement.spacedBy(16.dp)) {items(20) { index ->Box(modifier = Modifier.width(100.dp).fillMaxHeight().background(Color(0xFF6200EE)),contentAlignment = Alignment.Center) {Text(text = "Item $index", color = Color.White)}}}
}

3. LazyVerticalGrid：垂直网格
   用于展示多行多列的网格布局（如相册、商品列表）。

@Preview
@Composable
fun LazyGridExample() {LazyVerticalGrid(columns = GridCells.Fixed(2), // 固定2列modifier = Modifier.fillMaxSize(),contentPadding = PaddingValues(16.dp),horizontalArrangement = Arrangement.spacedBy(16.dp),verticalArrangement = Arrangement.spacedBy(16.dp)) {items(20) { index ->Box(modifier = Modifier.aspectRatio(1f) // 正方形.background(Color.LightGray),contentAlignment = Alignment.Center) {Text(text = "Item $index")}}}
}

列数配置：GridCells.Fixed(n)（固定 n 列）、GridCells.Adaptive(minSize)（自适应列数，每列至少minSize宽度）。

四、导航与标签控件：组织页面结构

这类控件用于实现页面导航、内容分类，是多页面 APP 的核心组件。

1. TabRow 与 Tab：标签页
   TabRow 配合 Tab 实现标签切换（如 “推荐”“热门” 标签）。

@Preview
@Composable
fun TabExample() {val tabs = listOf("首页", "设置", "我的")var selectedTabIndex by remember { mutableStateOf(0) }Column(modifier = Modifier.fillMaxSize().background(Color.White)) {// 标签栏TabRow(selectedTabIndex = selectedTabIndex) {tabs.forEachIndexed { index, title ->Tab(selected = selectedTabIndex == index,onClick = { selectedTabIndex = index },text = { Text(title) },icon = {Icon(imageVector = when (index) {0 -> Icons.Default.Home1 -> Icons.Default.Settingselse -> Icons.Default.Person},contentDescription = title)})}}// 标签内容when (selectedTabIndex) {0 -> Text("首页内容", modifier = Modifier.padding(16.dp))1 -> Text("设置内容", modifier = Modifier.padding(16.dp))2 -> Text("我的内容", modifier = Modifier.padding(16.dp))}}
}

2. Navigation 组件：页面导航
   配合 Jetpack Navigation 库实现页面间跳转，通过 NavHost 和 composable 定义路由。

// 首页
@Composable
fun HomeScreen(onNavigateToDetail: () -> Unit) {Button(onClick = onNavigateToDetail) { Text("去详情页") }
}// 详情页
@Composable
fun DetailScreen(onNavigateBack: () -> Unit) {Button(onClick = onNavigateBack) { Text("返回首页") }
}@Preview
@Composable
fun NavigationExample() {val navController = rememberNavController()NavHost(navController = navController,startDestination = "home" // 初始页面) {composable("home") {HomeScreen(onNavigateToDetail = { navController.navigate("detail") })}composable("detail") {DetailScreen(onNavigateBack = { navController.popBackStack() })}}
}

五、反馈控件：提示与加载状态

用于向用户反馈操作结果、加载状态或错误信息。

1. 进度指示器：CircularProgressIndicator、LinearProgressIndicator
   显示操作进度（如网络请求、文件下载）。

@Composable
fun ProgressIndicators() {Column(horizontalAlignment = Alignment.CenterHorizontally) {// 圆形进度条（无限循环）CircularProgressIndicator(modifier = Modifier.size(40.dp),color = Color.Blue,strokeWidth = 4.dp)Spacer(modifier = Modifier.height(16.dp))// 线性进度条（指定进度）var progress by remember { mutableStateOf(0.3f) }LinearProgressIndicator(progress = progress,modifier = Modifier.fillMaxWidth(0.5f),color = Color.Green)}
}

2. 对话框：AlertDialog、BottomSheetDialog
   用于重要操作确认、信息提示或复杂输入。

@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun DialogExamples() {var showAlert by remember { mutableStateOf(false) }var showBottomSheet by remember { mutableStateOf(false) }Column {Button(onClick = { showAlert = true }) { Text("显示对话框") }Button(onClick = { showBottomSheet = true }) { Text("显示底部弹窗") }}//  AlertDialog（居中弹窗）if (showAlert) {AlertDialog(onDismissRequest = { showAlert = false }, // 点击外部关闭title = { Text("提示") },text = { Text("确定要执行此操作吗？") },confirmButton = {Button(onClick = { showAlert = false }) { Text("确定") }},dismissButton = {TextButton(onClick = { showAlert = false }) { Text("取消") }})}// 底部弹窗if (showBottomSheet) {ModalBottomSheet(onDismissRequest = { showBottomSheet = false }) {Column(modifier = Modifier.padding(16.dp)) {Text("底部弹窗内容", fontSize = 18.sp)Spacer(modifier = Modifier.height(16.dp))Button(onClick = { showBottomSheet = false }) { Text("关闭") }}}}
}

3. Snackbar：轻量提示
   用于显示短暂的操作反馈（如 “保存成功”），通常与 Scaffold 配合使用。

@Preview
@Composable
fun SnackbarExample() {val snackbarHostState = remember { SnackbarHostState() }val scope = rememberCoroutineScope()Scaffold(snackbarHost = {SnackbarHost(snackbarHostState) { data ->Snackbar {// The Material spec recommends a maximum of 2 lines of text.Text(data.visuals.message, maxLines = 2, overflow = TextOverflow.Ellipsis)}}},floatingActionButton = {ExtendedFloatingActionButton(onClick = {scope.launch {val longMessage ="Very very very very very very very very very very very very very " +"very very very very very very very very very very very very " +"very very very very very very very very very very long message"snackbarHostState.showSnackbar(longMessage)}}) {Text("Show snackbar")}},content = { innerPadding ->Text(text = "Multiline Snackbar Demo",modifier = Modifier.padding(innerPadding).fillMaxSize().wrapContentSize())})
}

六、布局控件：组织 UI 结构

布局控件用于排列子组件，是构建复杂 UI 的基础（前文布局博客已详细介绍，此处简要回顾核心控件）：

Column：垂直排列子组件；
Row：水平排列子组件；
Box：层叠或定位子组件；
ConstraintLayout：通过约束关系排列子组件；
FlowRow/FlowColumn：自动换行的流式布局。

七、自定义控件：扩展现有功能

当现有控件无法满足需求时，可通过组合现有控件或使用 Layout 函数创建自定义控件。
示例：自定义星级评分控件

@Composable
fun RatingBar(rating: Int,maxRating: Int = 5,onRatingChanged: (Int) -> Unit,starSize: Dp = 24.dp
) {Row {repeat(maxRating) { index ->Icon(imageVector =Icons.Default.Star,contentDescription = "评分 $index",tint = if (index < rating) Color.Yellowelse Color.Gray,modifier = Modifier.size(starSize).clickable { onRatingChanged(index + 1) })}}
}@Preview
@Composable
fun UseRatingBar() {var rating by remember { mutableStateOf(3) }RatingBar(rating = rating,onRatingChanged = { rating = it })
}

总结

Jetpack Compose 的控件体系以 “可组合性” 为核心，从基础的 Text、Button 到复杂的 LazyColumn、NavHost，覆盖了 Android 开发的所有 UI 场景。与传统 View 相比，Compose 控件具有以下优势：

声明式语法：直接描述 UI 状态，无需手动更新视图；
状态驱动：通过 remember、mutableStateOf 等 API 实现状态与 UI 的自动同步；
灵活组合：任何控件都可作为子组件组合，轻松构建复杂 UI；
Material Design 3 原生支持：内置符合现代设计规范的组件，无需额外适配。

掌握这些控件后，你可以快速构建出美观、高效、易维护的 Android 应用。实际开发中，建议结合官方文档和具体场景，选择最合适的控件组合，以实现最佳的用户体验。