Compose 核心组件学习指南

📐 Modifier（修饰符）- 控制 UI 的外观和布局

什么是 Modifier？

Modifier 是 Compose 中用来修饰和配置 UI 组件的工具。

常用的 Modifier

kotlin 复制代码

// 1. 大小相关
Modifier
    .fillMaxSize()           // 填充父容器（宽高都最大）
    .fillMaxWidth()          // 填充父容器宽度
    .fillMaxHeight()         // 填充父容器高度
    .size(100.dp)            // 指定大小：100x100
    .width(200.dp)           // 指定宽度
    .height(100.dp)          // 指定高度

// 2. 内边距（padding）- 内容和边框之间的距离
Modifier
    .padding(16.dp)          // 四周各 16dp
    .padding(horizontal = 16.dp, vertical = 8.dp)  // 横向16，纵向8
    .padding(start = 16.dp, end = 16.dp, top = 8.dp, bottom = 8.dp)

// 3. 背景色
Modifier
    .background(Color.Blue)  // 纯色背景
    .background(Color.Blue, shape = RoundedCornerShape(8.dp))  // 带圆角

// 4. 边框
Modifier
    .border(2.dp, Color.Black)  // 2dp 黑色边框
    .border(2.dp, Color.Black, shape = CircleShape)  // 圆形边框

// 5. 圆角
Modifier
    .clip(RoundedCornerShape(8.dp))  // 8dp 圆角
    .clip(CircleShape)                // 圆形

// 6. 对齐（用在 Box 中）
Modifier
    .align(Alignment.Center)     // 在父容器中居中
    .align(Alignment.TopStart)   // 左上角

// 7. 点击事件
Modifier
    .clickable { println("被点击了") }  // 点击事件
    .pointerInput(Unit) { /* 高级手势检测 */ }

// 8. 阴影
Modifier
    .shadow(elevation = 8.dp)  // 8dp 的阴影

// 9. 链式调用（修饰符可以链式组合）
Modifier
    .fillMaxWidth()
    .padding(16.dp)
    .background(Color.LightGray)
    .clickable { /* ... */ }

实际例子：从你的代码中

kotlin 复制代码

// ContactsScreen.kt 中的例子
Box(
    modifier = Modifier
        .fillMaxSize()           // 填满整个屏幕
        .background(Color.Transparent),  // 透明背景
    contentAlignment = Alignment.TopStart  // 内容对齐方式
)

// ContactList 中的例子
LazyColumn(
    modifier = Modifier.fillMaxSize()  // 列表填满屏幕
)

🎛️ 布局容器（Layout）

1. Box - 堆叠布局（可以重叠）

kotlin 复制代码

Box(
    modifier = Modifier.size(200.dp),
    contentAlignment = Alignment.Center  // 内容在中心
) {
    // 子组件会重叠排列
    Image(...)  // 背景
    Text(...)   // 文字在图片上方
}

用途： 堆叠元素，比如：

图片 + 文字
背景 + 内容
列表 + 浮动按钮

2. Column - 竖向排列

kotlin 复制代码

Column(
    modifier = Modifier.fillMaxSize(),
    verticalArrangement = Arrangement.Center,  // 竖向排列方式
    horizontalAlignment = Alignment.CenterHorizontally  // 横向对齐
) {
    Text("标题", fontSize = 24.sp)
    Spacer(modifier = Modifier.height(8.dp))  // 间隔
    Text("描述", fontSize = 14.sp)
}

输出：

复制代码

┌─────────────────┐
│   标题          │
│                 │
│   描述          │
└─────────────────┘

3. Row - 横向排列

kotlin 复制代码

Row(
    modifier = Modifier.fillMaxWidth(),
    horizontalArrangement = Arrangement.SpaceBetween,  // 两端对齐
    verticalAlignment = Alignment.CenterVertically  // 竖向居中
) {
    Image(...)
    Text("标题")
    Icon(...)
}

输出：

复制代码

┌─────────────────────┐
│[图] 标题      [图标]│
└─────────────────────┘

4. LazyColumn - 懒加载竖向列表（性能好）

kotlin 复制代码

LazyColumn(
    modifier = Modifier.fillMaxSize(),
    state = rememberLazyListState(),  // 记住滚动位置
    contentPadding = PaddingValues(16.dp)  // 列表内边距
) {
    // 遍历列表数据
    items(contactList.size) { index ->
        ContactItem(contact = contactList[index])
        Divider()  // 分割线
    }
    
    // 或者使用 itemsIndexed
    itemsIndexed(contactList) { index, contact ->
        ContactItem(contact = contact)
    }
    
    // 在列表末尾加东西
    item {
        LoadMoreButton()
    }
}

关键区别：

Column - 一次性加载所有 UI（数据少时用）
LazyColumn - 只加载可见的 UI（列表很长时用）

5. 你的代码中的 LazyColumn

kotlin 复制代码

// 从 ContactsScreen.kt
LazyColumn(
    state = lazyListState,
    modifier = Modifier.fillMaxSize()
) {
    itemsIndexed(contactGroups) { _, (initial, contacts) ->
        // 每个首字母分组
        StickyHeader {
            Text(initial, fontSize = 20.sp)  // 首字母
        }
        
        // 该分组下的所有联系人
        items(contacts.size) { index ->
            CallContactListItem(contact = contacts[index])
        }
    }
}

📝 Text（文字）

kotlin 复制代码

Text(
    text = "Hello Compose",
    modifier = Modifier.padding(16.dp),
    color = Color.Blue,              // 字体颜色
    fontSize = 16.sp,                // 字体大小（sp = 缩放像素）
    fontWeight = FontWeight.Bold,    // 字体粗细
    textAlign = TextAlign.Center,    // 文字对齐
    maxLines = 1,                    // 最多 1 行
    overflow = TextOverflow.Ellipsis // 溢出时显示 ...
)

🖼️ Image（图片）

kotlin 复制代码

// 从本地资源加载
Image(
    painter = painterResource(R.drawable.ic_phone),
    contentDescription = "电话图标",
    modifier = Modifier.size(24.dp),
    contentScale = ContentScale.Fit  // 内容缩放方式
)

// 也可以使用 Icon（图标更简洁）
Icon(
    painter = painterResource(R.drawable.ic_phone),
    contentDescription = "电话",
    modifier = Modifier.size(24.dp),
    tint = Color.Blue  // 图标颜色
)

🔘 Button（按钮）

kotlin 复制代码

Button(
    onClick = { /* 点击事件 */ },
    modifier = Modifier
        .fillMaxWidth()
        .height(48.dp),
    colors = ButtonDefaults.buttonColors(
        containerColor = Color.Blue,  // 背景色
        contentColor = Color.White    // 内容色
    ),
    shape = RoundedCornerShape(8.dp)  // 圆角
) {
    Text("点击我")
}

📋 Card（卡片）

kotlin 复制代码

Card(
    modifier = Modifier
        .fillMaxWidth()
        .padding(16.dp),
    shape = RoundedCornerShape(8.dp),
    elevation = CardDefaults.cardElevation(defaultElevation = 8.dp)
) {
    Column(modifier = Modifier.padding(16.dp)) {
        Text("标题", fontSize = 18.sp, fontWeight = FontWeight.Bold)
        Spacer(modifier = Modifier.height(8.dp))
        Text("卡片内容")
    }
}

输出：

复制代码

┌──────────────────┐
│ 标题             │ ← 阴影效果
│ 卡片内容         │
└──────────────────┘

🎨 常见的排列方式（Arrangement）

kotlin 复制代码

// 竖向排列
Column(
    verticalArrangement = Arrangement.Top         // 靠顶部
    verticalArrangement = Arrangement.Center      // 居中
    verticalArrangement = Arrangement.Bottom      // 靠底部
    verticalArrangement = Arrangement.SpaceBetween // 两端对齐，中间均匀分布
    verticalArrangement = Arrangement.SpaceAround // 四周均等间隔
    verticalArrangement = Arrangement.SpaceEvenly // 均等分布
)

// 横向排列
Row(
    horizontalArrangement = Arrangement.Start     // 靠左
    horizontalArrangement = Arrangement.End       // 靠右
    horizontalArrangement = Arrangement.Center    // 居中
    horizontalArrangement = Arrangement.SpaceBetween
    // ... 其他同上
)

🎯 对齐方式（Alignment）

在 Box 中的对齐

kotlin 复制代码

Box(contentAlignment = Alignment.Center) { ... }  // 中心
Box(contentAlignment = Alignment.TopStart) { ... }  // 左上
Box(contentAlignment = Alignment.TopEnd) { ... }  // 右上
Box(contentAlignment = Alignment.BottomStart) { ... }  // 左下
Box(contentAlignment = Alignment.BottomEnd) { ... }  // 右下
Box(contentAlignment = Alignment.CenterStart) { ... }  // 左中
Box(contentAlignment = Alignment.CenterEnd) { ... }  // 右中

在 Column/Row 中的对齐

kotlin 复制代码

Column(horizontalAlignment = Alignment.CenterHorizontally) { ... }
Column(horizontalAlignment = Alignment.Start) { ... }
Column(horizontalAlignment = Alignment.End) { ... }

Row(verticalAlignment = Alignment.CenterVertically) { ... }
Row(verticalAlignment = Alignment.Top) { ... }
Row(verticalAlignment = Alignment.Bottom) { ... }

🔄 Spacer（间隔）

kotlin 复制代码

// 在 Column 中创建竖向间隔
Column {
    Text("上面的文字")
    Spacer(modifier = Modifier.height(16.dp))  // 16dp 的间隔
    Text("下面的文字")
}

// 在 Row 中创建横向间隔
Row {
    Text("左边的文字")
    Spacer(modifier = Modifier.width(16.dp))   // 16dp 的间隔
    Text("右边的文字")
}

// 推开其他元素（填充剩余空间）
Row(modifier = Modifier.fillMaxWidth()) {
    Text("靠左")
    Spacer(modifier = Modifier.weight(1f))     // 填充中间所有空间
    Text("靠右")
}

📊 Divider（分割线）

kotlin 复制代码

// 竖向分割线
Divider(
    modifier = Modifier.fillMaxWidth(),
    color = Color.LightGray,
    thickness = 1.dp
)

// 横向分割线
Divider(
    modifier = Modifier
        .fillMaxHeight()
        .width(1.dp),
    color = Color.LightGray
)

🎨 常见的完整 UI 组件例子

联系人列表项（类似你的 CallContactListItem）

kotlin 复制代码

@Composable
fun ContactItem(
    contact: Contact,
    onItemClick: (Contact) -> Unit,
    modifier: Modifier = Modifier
) {
    Card(
        modifier = modifier
            .fillMaxWidth()
            .padding(8.dp)
            .clickable { onItemClick(contact) },
        shape = RoundedCornerShape(8.dp)
    ) {
        Row(
            modifier = Modifier
                .fillMaxWidth()
                .padding(16.dp),
            verticalAlignment = Alignment.CenterVertically
        ) {
            // 头像
            Image(
                painter = painterResource(R.drawable.ic_user),
                contentDescription = "头像",
                modifier = Modifier
                    .size(48.dp)
                    .clip(CircleShape),
                contentScale = ContentScale.Crop
            )
            
            Spacer(modifier = Modifier.width(16.dp))
            
            // 联系人信息
            Column(modifier = Modifier.weight(1f)) {
                Text(
                    text = contact.name,
                    fontSize = 16.sp,
                    fontWeight = FontWeight.Bold
                )
                Spacer(modifier = Modifier.height(4.dp))
                Text(
                    text = contact.phone,
                    fontSize = 14.sp,
                    color = Color.Gray
                )
            }
            
            // 拨号按钮
            Icon(
                painter = painterResource(R.drawable.ic_call),
                contentDescription = "拨号",
                modifier = Modifier
                    .size(24.dp)
                    .clickable { /* 拨号 */ },
                tint = Color.Blue
            )
        }
    }
}

🎭 Scaffold（整体布局）

当你需要包含 TopAppBar、BottomBar 等时：

kotlin 复制代码

Scaffold(
    modifier = Modifier.fillMaxSize(),
    topBar = {
        TopAppBar(
            title = { Text("标题") },
            actions = {
                Icon(Icons.Default.Search, contentDescription = "搜索")
            }
        )
    },
    bottomBar = {
        NavigationBar {
            NavigationBarItem(
                selected = true,
                onClick = { /* ... */ },
                icon = { Icon(Icons.Default.Home, contentDescription = "首页") }
            )
        }
    }
) { paddingValues ->
    // 主要内容（会自动留出 TopBar 和 BottomBar 的空间）
    Box(
        modifier = Modifier
            .fillMaxSize()
            .padding(paddingValues)
    ) {
        Text("内容区域")
    }
}

⚡ 快速查询表

UI 组件	用途	何时使用
Text	显示文字	任何需要显示文字的地方
Image/Icon	显示图片/图标	头像、按钮图标
Button	可点击的按钮	用户操作按钮
Card	卡片容器	列表项、信息卡片
Column	竖向排列	手机屏幕
Row	横向排列	一行多个元素
Box	堆叠布局	背景+内容、浮动按钮
LazyColumn	滚动列表	长列表、大数据量
Spacer	间隔	调整元素间距
Divider	分割线	分隔不同的内容区域
Scaffold	整体框架	有 TopBar、BottomBar 的页面

掌握这些组件，你就能构建大多数 Compose UI！ 🚀