4. 组件
上一章介绍了 [Material 3] 的组件和状态。本章展示如何编写你自己的组件:它们的参数、它们如何通知其父组件、组合、它们的生命周期、远程提供给它们的数据,以及可复用的行为。在 [Compose] 中,组件就是一个简单的 [@Composable] 函数:相当于 [Flutter] 的 widget。
4.1. 示例 10:组件及其参数
一张显示医生信息的卡片,在一个屏幕上多次使用。父组件和子组件共享的数据类型:
| // 父组件(DoctorsPage)和子组件(DoctorCard)共享的数据类型
package fr.stahe.examples.ex10
data class Doctor(
val id: Int,
val title: String,
val firstName: String,
val lastName: String,
val specialty: String,
val available: Boolean,
)
|
子组件,即卡片:
| // =========================================================================
// ex10/DoctorCard.kt - 一个子组件
// -------------------------------------------------------------------------
// 它通过参数从父组件接收数据。它们的类型在编译时
// 检查:DoctorCard(doctor = 42, ...) 会被拒绝。
// - 没有默认值的参数:父组件必须提供它;
// - compact: Boolean = false:一个可选参数,带有默认
// 值;
// - modifier: Modifier = Modifier:Compose 的约定,父组件
// 可以调整子组件的大小、边距等。
//
// 黄金法则:组件绝不修改它的参数(它们是
// val)。数据从父组件向下流向子组件;要请求
// 修改,子组件调用父组件传给它的函数
// (参见示例 11)。当父组件修改它的数据时,Compose 会用新的参数重新执行
// 子组件。
// =========================================================================
package fr.stahe.examples.ex10
import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
// 卡片的“样式”:此文件私有的常量。其他组件
// 看不到它们,也不会受它们的干扰
private val initialsColor = Color(0xFF087EA4)
@Composable
fun DoctorCard(doctor: Doctor, rank: Int, modifier: Modifier = Modifier, compact: Boolean = false) {
// 由参数计算得出的值
val initials = "${doctor.firstName.first()}${doctor.lastName.first()}"
Card(
modifier = modifier.padding(vertical = 4.dp),
shape = RoundedCornerShape(12.dp),
// 对于可预约的医生带有绿色边框(null:无边框)
border = if (doctor.available) BorderStroke(2.dp, Color(0xFF4CAF50)) else null,
) {
Row(Modifier.padding(12.dp), verticalAlignment = Alignment.CenterVertically) {
// 一个彩色圆形,中央是姓名首字母
Box(
contentAlignment = Alignment.Center,
modifier = Modifier.size(40.dp).background(initialsColor, CircleShape),
) {
Text(initials, color = Color.White, fontWeight = FontWeight.Bold)
}
Spacer(Modifier.width(12.dp))
// weight(1f):文本占据所有剩余的宽度
Column(Modifier.weight(1f)) {
Text("$rank. ${doctor.title} ${doctor.firstName} ${doctor.lastName}", style = MaterialTheme.typography.titleMedium)
if (!compact) {
Text(doctor.specialty, color = Color.Gray)
}
}
}
}
}
|
- 第 43 行:一个 [private] 常量:只在这个文件中可见;
- 第 46 行:卡片的参数。它们的类型在编译时验证;[doctor] 和 [rank] 是必需的;[compact] 是可选的;[modifier: Modifier = Modifier] 是 [Compose] 的约定:父组件 可以调整子组件的大小、边距等,子组件把这个 [modifier] 应用到它最外层的组件上;
- 第 48 行:由参数计算得出的值;
- 第 49–53 行:[Card],一张 [Material] 卡片,对于可预约的医生带有绿色边框([null]:无边框);
- 第 57–61 行:带有姓名首字母的彩色圆形([CircleShape]);
- 第 67–68 行:专业仅在普通模式下显示。
黄金法则:组件绝不修改它的参数(它们是 [val];事实上,编译器禁止这样做)。数据从父组件流向子组件;当父组件修改它的数据时,[Compose] 会用新的参数重新执行子组件。父组件:
| // =========================================================================
// ex10/Ex10Activity.kt - 父组件
// -------------------------------------------------------------------------
// 它根据需要多次使用 DoctorCard 组件,就像
// 任何 Compose 组件一样:@Composable 函数是一个
// 可复用的界面片段,有自己的参数和
// 样式。编写自己的组件是使用 Compose 的核心:
// 一个写得好的屏幕是由小组件构成的。
// =========================================================================
package fr.stahe.examples.ex10
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.width
import androidx.compose.material3.ListItem
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Switch
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.key
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
class Ex10Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent { ExamplesTheme { DoctorsPage() } }
}
}
@Composable
fun DoctorsPage() {
var doctors by remember {
mutableStateOf(
listOf(
Doctor(1, "Mme", "Marie", "PELISSIER", "general practitioner", true),
Doctor(2, "Mr", "Paul", "TATOU", "pediatrician", false),
Doctor(3, "Melle", "Sophie", "DUPONT", "general practitioner", true),
),
)
}
var compact by remember { mutableStateOf(false) }
ExamplePage("Example 10 - components and their parameters") {
ListItem(
headlineContent = { Text("compact display") },
trailingContent = { Switch(checked = compact, onCheckedChange = { compact = it }) },
)
// 父组件修改它自己的数据:Compose 重新执行这个函数,它
// 用新的参数再次调用各个子组件
OutlinedButton(onClick = { doctors = doctors.map { it.copy(available = !it.available) } }) {
Text("Toggle availabilities")
}
Spacer(Modifier.height(8.dp))
doctors.forEachIndexed { i, d ->
// 每张卡片接收它自己的参数;key:它的标识(参见示例 04)
key(d.id) {
DoctorCard(doctor = d, rank = i + 1, compact = compact)
}
}
Spacer(Modifier.height(16.dp))
Text("The same card, in compact version, by setting the parameter:", color = Color.Gray)
// 父组件还通过 modifier 参数设置子组件的宽度
DoctorCard(doctor = doctors[0], rank = 1, compact = true, modifier = Modifier.width(260.dp))
}
}
|
- 第 63 行:父组件修改它自己的数据:一个新的列表,其中每位医生都被替换为一个副本;
- 第 67–70 行:每位医生一条记录,各自带有它自己的参数;[key(d.id)]:医生的标识(见示例 04);
- 第 76 行:父组件还通过参数 [modifier] 设置子组件的宽度。


4.2. 示例 11:子组件通知其父组件
数据通过参数向下传递;信息则通过父组件传给子组件的函数向上传递(按惯例,这些函数的名称以 [on] 开头)。第一个子组件是一个计数器,它有自己的状态,并通知其父组件:
| // =========================================================================
// ex11/Counter.kt - 一个通知其父组件的子组件
// -------------------------------------------------------------------------
// 父组件把函数作为参数传给它(按惯例,其
// 名称以“on”开头),子组件在发生某件事时
// 调用它们:
// Counter(label = "Coffees", max = 3, onIncrement = { ... }, onLimit = { ... })
// 函数的类型写作 (parameters) -> result:
// - (Int) -> Unit:接收一个 Int 且不返回任何值的函数;
// - () -> Unit :没有参数且不返回任何值的函数。
// =========================================================================
package fr.stahe.examples.ex11
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.width
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
@Composable
fun Counter(label: String, max: Int, onIncrement: (Int) -> Unit, onLimit: () -> Unit) {
// 这个计数器特有的状态:每个 Counter 都有自己的状态
var value by remember { mutableIntStateOf(0) }
fun plus() {
if (value >= max) {
onLimit()
return
}
value++
// 我们通知父组件,并把新的值传给它
onIncrement(value)
}
Row(verticalAlignment = Alignment.CenterVertically) {
Text(label, Modifier.width(110.dp))
OutlinedButton(onClick = { plus() }) { Text("+1") }
Spacer(Modifier.width(12.dp))
SuggestionChip(onClick = {}, label = { Text("$value / $max") })
}
}
|
- 第 30 行:函数的类型写作 [(parameters) -> result]:[(Int) -> Unit] 接收一个 [Int] 且不返回任何值;[() -> Unit] 没有参数;
- 第 32 行:计数器自己的状态:每个 [Counter] 都有各自的状态;
- 第 34–41 行:当计数达到最大值时,计数器通知父组件([onLimit()]);否则就递增,并传递它的新值([onIncrement(value)])。
第二个子组件是一个受控组件,其用法与 [Compose] 的字段相同:值属于父组件,由父组件传给子组件([value]),子组件则在每次按键时通知父组件([onChange])。这个组件没有状态:
| // =========================================================================
// ex11/TextField.kt - 一个受控组件
// -------------------------------------------------------------------------
// 一个“自制”的表单字段(标签 + 字段 + 帮助 + 字符
// 计数器),其用法与 Compose 的字段相同:
// TextField(value = firstName, onChange = { firstName = it }, ...)
// 值属于父组件,由父组件传入(value),并且组件会
// 在每次按键时通知父组件(onChange)。决定权在父组件。
// 该组件没有状态:给它什么它就显示什么。如果
// 父组件自己修改了值(“Clear”按钮),字段会随之变化,无需
// 再编写任何其他代码。
// =========================================================================
package fr.stahe.examples.ex11
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
@Composable
fun TextField(value: String, onChange: (String) -> Unit, label: String, max: Int, help: String = "") {
val full = value.length == max
OutlinedTextField(
value = value,
// 字段拒绝多余的字符:只有当文本不超过 max 个字符时,
// 按键才会传给父组件
onValueChange = { text -> if (text.length <= max) onChange(text) },
label = { Text(label) },
singleLine = true,
// 字段已满时边框变红
isError = full,
supportingText = { Text(if (full) "Maximum length reached - ${value.length}/$max" else "$help - ${value.length}/$max") },
modifier = Modifier.fillMaxWidth(),
)
}
|
- 第 28 行:只有当文本不超过 [max] 个字符时,按键才会发送给父组件:该字段“拒绝”任何超出的字符;
- 第 32–33 行:当字段已满时边框变红,提示文字也会指出这一点。
父组件:
| // =========================================================================
// ex11/Ex11Activity.kt - 父组件监听它的子组件
// -------------------------------------------------------------------------
// 数据向下流动(参数);信息通过作为参数传入的
// 函数向上传递:
// 1. 子组件的“事件”:onIncrement、onLimit;
// 2. 一个受控组件:value + onChange,就像 TextField。
// 状态仍然归父组件所有,父组件可以自己修改它
// (Clear)。
// =========================================================================
package fr.stahe.examples.ex11
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
class Ex11Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent { ExamplesTheme { ParentPage() } }
}
}
@Composable
fun ParentPage() {
var total by remember { mutableIntStateOf(0) }
var message by remember { mutableStateOf("") }
var firstName by remember { mutableStateOf("Marie") }
var lastName by remember { mutableStateOf("PELISSIER") }
// 被计数器调用的函数:它接收计数器传来的值
fun onIncrement(label: String, value: Int) {
total++
message = "$label is now $value"
}
val titleStyle = MaterialTheme.typography.titleSmall
ExamplePage("Example 11 - the child notifies its parent") {
Card {
Column(Modifier.padding(12.dp)) {
Text("1. Functions called by the children", style = titleStyle)
Counter(
label = "Coffees",
max = 3,
onIncrement = { v -> onIncrement("Coffees", v) },
onLimit = { message = "No more than 3 coffees!" },
)
Counter(
label = "Glasses of water",
max = 8,
onIncrement = { v -> onIncrement("Glasses of water", v) },
onLimit = { message = "Enough drinking." },
)
Spacer(Modifier.height(8.dp))
Text("Total of clicks: $total - $message", fontStyle = FontStyle.Italic)
}
}
Card {
Column(Modifier.padding(12.dp)) {
Text("2. Controlled components", style = titleStyle)
TextField(value = firstName, onChange = { firstName = it }, label = "First name", max = 20, help = "Required")
TextField(value = lastName, onChange = { lastName = it }, label = "Last name", max = 20, help = "Displayed in upper case")
Spacer(Modifier.height(8.dp))
Text(
buildAnnotatedString {
append("Data of the parent: ")
withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append("$firstName ${lastName.uppercase()}") }
},
)
Spacer(Modifier.height(8.dp))
OutlinedButton(onClick = {
firstName = ""
lastName = ""
}) { Text("Clear (from the parent)") }
}
}
}
}
|
- 第 57–59 行:被计数器调用的函数;
- 第 68–71 行:每个计数器接收两个 lambda 表达式;第一个接收传来的值([v]),并在其后附加计数器的标签;
- 第 86–87 行:受控字段:值,以及每次按键时要做什么;
- 第 97–99 行:父组件修改它自己的数据:字段随之变化,无需再编写任何其他代码。


左图:已达到咖啡的最大数量,姓名长度为 20 个字符;右图:点击“Clear (from the parent)”之后。
4.3. 示例 12:组合
组件的参数传递的是数据……也可以传递内容:参数可以是一个 [@Composable] 函数,组件在它想要的任何位置调用它。[Compose] 到处都是这样做的([Card]、[Scaffold]、字段的 [label] 等)。第一个模板,一张带有三个槽位的卡片:
| // =========================================================================
// ex12/Card.kt - 一个可复用的模板
// -------------------------------------------------------------------------
// 组件的参数传递的是数据……也可以传递
// 内容:参数可以是一个 @Composable 函数,组件
// 在它想要的任何位置调用它。Compose 到处都在用这种方式:Card 的内容、
// Scaffold 的 topBar、字段的 label 等。
// - content:按惯例是最后一个参数,即“主要”
// 内容。它写在调用的圆括号之后:
// Card(color = ...) { Text("the content") }
// - header、footer:其他位置(“槽位”),由
// 父组件提供;header 有默认内容,footer 是可选的。
// 卡片确定框架(边框、页眉、页脚),父组件提供
// 里面的内容。
// =========================================================================
package fr.stahe.examples.ex12
import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Card
import androidx.compose.material3.ProvideTextStyle
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
@Composable
fun Card(
color: Color? = null, // “?”:可选(默认为 null)
header: @Composable () -> Unit = { Text("Untitled") },
footer: (@Composable () -> Unit)? = null,
content: @Composable () -> Unit,
) {
val fill = color ?: Color(0xFFE0E0E0) // “?:”:使用 color,否则使用这种灰色
Card(
modifier = Modifier.padding(vertical = 4.dp),
shape = RoundedCornerShape(8.dp),
border = BorderStroke(1.dp, fill),
) {
Column {
Box(Modifier.fillMaxWidth().background(fill).padding(10.dp)) {
// ProvideTextStyle:所有页眉文本的样式,
// 无论父组件提供的内容是什么
ProvideTextStyle(TextStyle(color = if (color == null) Color.Black else Color.White, fontWeight = FontWeight.Bold)) {
header()
}
}
Box(Modifier.padding(10.dp)) { content() }
// 没有提供页脚:就根本没有页脚
if (footer != null) {
Box(Modifier.fillMaxWidth().background(Color(0xFFF5F5F5)).padding(8.dp)) {
ProvideTextStyle(TextStyle(color = Color.Gray, fontSize = 12.sp)) { footer() }
}
}
}
}
}
|
- 第 38–41 行:三个内容参数:[header],带有默认内容;[footer],可选的([(@Composable () -> Unit)?]:一个函数,或者 [null]);[content],最后一个,在调用时写在圆括号之后;
- 第 53–54 行:[ProvideTextStyle] 设置所有标题文本的样式,无论父组件提供的内容是什么;
- 第 59–61 行:没有提供页脚,就根本没有页脚。
第二个模板,一个泛型表格:它可以遍历各行,但不能显示单元格;父组件通过描述各列来告诉它该怎么做:
| // =========================================================================
// ex12/DataTable.kt - 一个泛型表格
// -------------------------------------------------------------------------
// DataTable<T> 是一个泛型组件:它显示任意类型 T 的
// 行。它知道如何遍历各行,但不知道如何
// 显示一个单元格:由父组件通过描述它的
// 列来告诉它。每个 TableColumn<T> 有一个标题、一个相对宽度(weight)和
// 一个 @Composable 函数 cell(row, index),用于显示它的单元格。
// 父组件提供的内容使用属于
// 子组件的数据(行及其序号):这就是 Compose 列表的原理
// (LazyColumn 及其 items { ... } 函数)。
// =========================================================================
package fr.stahe.examples.ex12
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.ProvideTextStyle
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
// T 表格的一列
class TableColumn<T>(val title: String, val weight: Float = 1f, val cell: @Composable (row: T, index: Int) -> Unit)
@Composable
fun <T> DataTable(
rows: List<T>,
columns: List<TableColumn<T>>,
// 没有行时显示
empty: @Composable () -> Unit = { Text("No data.") },
) {
Column {
// 标题行
Row {
for (c in columns) {
Text(c.title, Modifier.weight(c.weight).padding(6.dp), fontWeight = FontWeight.Bold)
}
}
HorizontalDivider()
if (rows.isEmpty()) {
Box(Modifier.padding(6.dp)) { ProvideTextStyle(TextStyle(color = Color.Gray)) { empty() } }
}
rows.forEachIndexed { i, row ->
if (i > 0) HorizontalDivider(color = Color(0xFFE0E0E0))
Row(verticalAlignment = Alignment.CenterVertically) {
// 这一行的单元格,由父组件的函数来显示
for (c in columns) {
Box(Modifier.weight(c.weight).padding(6.dp)) { c.cell(row, i) }
}
}
}
}
}
|
- 第 31 行:[T] 表格的一列:一个标题、一个相对宽度,以及一个在行中显示单元格的 [@Composable] 函数;
- 第 55–56 行:每一行中的单元格,由父组件的函数来显示。父组件提供的内容使用属于子组件的数据(行及其序号):这就是 [Compose] 中列表([LazyColumn],见案例研究)背后的原理。
使用这两个模板的屏幕:
| // =========================================================================
// ex12/Ex12Activity.kt - 使用 Card 和 DataTable 模板
// =========================================================================
package fr.stahe.examples.ex12
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Icon
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.SuggestionChipDefaults
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
// 一个时间段;patient:如果时间段空闲则为 null
data class Slot(val id: Int, val timeRange: String, val patient: String?)
val slots = listOf(
Slot(1, "8:00 - 8:20", null),
Slot(2, "8:20 - 8:40", "Mme Alice DURAND"),
Slot(3, "8:40 - 9:00", null),
)
data class Person(val id: Int, val name: String)
class Ex12Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent { ExamplesTheme { CompositionPage() } }
}
}
@Composable
fun CompositionPage() {
val free = slots.count { it.patient == null }
ExamplePage("Example 12 - composition") {
// 页眉和页脚:作为参数传入的 @Composable 函数;
// 内容:写在圆括号之后的 lambda
Card(
color = Color(0xFF3F51B5),
header = {
Row(verticalAlignment = Alignment.CenterVertically) {
Icon(Icons.Default.DateRange, contentDescription = null, tint = Color.White)
Spacer(Modifier.width(8.dp))
Text("Schedule of Mme PELISSIER")
}
},
footer = { Text("$free free slot(s)") },
) {
// DataTable<Slot>:T 由 rows 的类型推导出来
DataTable(
rows = slots,
columns = listOf(
// s 接收行,i 接收它的序号
TableColumn("#", 0.4f) { _, i -> Text("${i + 1}") },
TableColumn("Slot", 1.2f) { s, _ -> Text(s.timeRange) },
TableColumn("Status", 1.6f) { s, _ ->
if (s.patient != null) {
SuggestionChip(onClick = {}, label = { Text(s.patient) })
} else {
SuggestionChip(
onClick = {},
label = { Text("Free") },
colors = SuggestionChipDefaults.suggestionChipColors(containerColor = Color(0xFFC8E6C9)),
)
}
},
),
)
}
Card(color = Color(0xFF4CAF50), header = { Text("A card without a footer") }) {
Text("The footer is not provided: the card does not display it.")
}
// 没有提供页眉:默认内容“Untitled”
Card {
DataTable(
rows = emptyList<Person>(),
columns = listOf(TableColumn("Name") { p, _ -> Text(p.name) }),
empty = { Text("Nobody for now.") },
)
}
}
}
|
- 第 52–61 行:页眉和页脚,按名称传入的 lambda 函数;内容,写在圆括号之后的 lambda 函数;
- 第 64–70 行:[DataTable<Slot>]:[T] 是推导出来的,它确定了行的类型。每一列接收该行及其序号;[_]:一个未使用的参数;
- 第 88–92 行:一张没有页眉的卡片(默认内容“Untitled”)和一个空表格。

4.4. 示例 13:组件的生命周期
组件进入组合(它的函数首次执行),按需被重组任意多次,然后永久地离开组合。[Compose] 提供了在这些时间点触发的“副作用”:
- [LaunchedEffect(key) [ ... ]]:在进入时启动一个协程(可以等待的代码;见示例 19),如果 [key] 变化则重新启动它,并在退出时取消它;
- [DisposableEffect(key) { ... ; onDispose [ ... ] }]:进入时执行的代码,以及退出时的清理。
一个启动定时器的时钟……并且在它消失时必须停止该定时器:
| // =========================================================================
// ex13/Clock.kt - 一个会启动和停止的组件
// -------------------------------------------------------------------------
// 组件在屏幕中的生命历程(“组合”):
// 1. 它进入组合:它的函数首次
// 执行。需要启动的东西在这里启动;
// 2. 它被重组任意多次(它的状态或
// 参数发生了变化);
// 3. 它离开组合:它从屏幕上消失,永远不再回来。
// 启动过的东西在这里被停止。
// Compose 提供“副作用”,用于在这些时刻执行操作,而不是在
// 显示本身之中:
// - LaunchedEffect(key) { ... }:在进入组合时启动一个协程(可以
// 等待的代码,参见示例 19),如果 key 变化则重新启动它,
// 在离开时取消它;
// - DisposableEffect(key) { ...; onDispose { ... } }:进入时执行的代码,
// 以及离开时的清理(onDispose)。
// 时钟在出现时启动一个定时器……而在消失时
// 必须停止它:使用 LaunchedEffect,
// 这是自动完成的。
// =========================================================================
package fr.stahe.examples.ex13
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.runtime.setValue
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.sp
import kotlinx.coroutines.delay
import java.time.LocalTime
import java.time.format.DateTimeFormatter
fun currentTime(): String = LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm:ss"))
@Composable
fun Clock(onLog: (String) -> Unit, color: Color = Color(0xFF3F51B5)) {
var time by remember { mutableStateOf(currentTime()) }
// 最后收到的 onLog 函数(下面的副作用
// 存续时间比函数的一次执行更长)
val log by rememberUpdatedState(onLog)
// 进入组合,以及离开组合
DisposableEffect(Unit) {
log("Clock: entering the composition - timer started")
onDispose { log("Clock: leaving the composition - timer stopped") }
}
// 定时器:一个协程,在离开时自动取消
LaunchedEffect(Unit) {
while (true) {
delay(1000) // 等待一秒钟,而不阻塞手机
time = currentTime()
}
}
// 一个会变化的参数:副作用会被重新启动(第一次除外)
var firstColor by remember { mutableStateOf(true) }
LaunchedEffect(color) {
if (firstColor) firstColor = false else log("Clock: recomposed with a new color")
}
Text(time, fontSize = 40.sp, fontFamily = FontFamily.Monospace, color = color)
}
|
- 第 47 行:[rememberUpdatedState]:副作用的存续时间比一次函数调用更长;它们必须调用最后收到的函数([onLog]),而不是第一个;
- 第 50–52 行:进入组合,以及退出([onDispose]);
- 第 57–59 行:定时器,一个无限循环……位于协程中:[delay(1000)] 等待一秒而不会阻塞手机;该协程在退出组合时被取消,循环也随之结束;
- 第 65 行:一个以参数为键的副作用:当颜色变化时它会再次触发。
屏幕:
| // =========================================================================
// ex13/Ex13Activity.kt - 生命周期
// -------------------------------------------------------------------------
// - if (withClock) Clock(...):勾选 / 取消勾选复选框会使
// 时钟进入 / 离开组合(参见 Clock.kt);
// 更改它的颜色会使它重组;
// - 一个在出现后立即获得焦点的字段(手机的
// 键盘随之打开);
// - 应用的标题跟随输入内容变化(TaskTitle);
// - Activity 本身的生命历程(它的“Lifecycle”):在手机上,
// 它会进入后台(打开另一个应用、屏幕
// 熄灭),然后返回:我们可以对此作出反应(保存、停止
// 定时器等)。
// =========================================================================
package fr.stahe.examples.ex13
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.selection.toggleable
import androidx.compose.material3.Card
import androidx.compose.material3.Checkbox
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.lifecycle.LifecycleEventObserver
import androidx.lifecycle.compose.LocalLifecycleOwner
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.common.TaskTitle
class Ex13Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent { ExamplesTheme { LifecyclePage() } }
}
}
@Composable
fun LifecyclePage() {
var withClock by remember { mutableStateOf(true) }
var red by remember { mutableStateOf(false) }
val log = remember { mutableStateListOf<String>() }
var search by remember { mutableStateOf("") }
var showSearch by remember { mutableStateOf(false) }
fun trace(message: String) {
log.add("${currentTime()} $message")
}
// Activity 的生命周期:进入组合时,我们订阅它的状态变化,
// 离开时取消订阅(onDispose)
val lifecycle = LocalLifecycleOwner.current.lifecycle
DisposableEffect(lifecycle) {
val observer = LifecycleEventObserver { _, event -> trace("Activity: ${event.name}") }
lifecycle.addObserver(observer)
onDispose { lifecycle.removeObserver(observer) }
}
TaskTitle(if (search.isEmpty()) "Example 13" else "Search: $search")
ExamplePage("Example 13 - the lifecycle") {
Card {
Column(Modifier.padding(12.dp)) {
CheckboxRow("show the clock", withClock) { withClock = it }
CheckboxRow("in red", red) { red = it }
if (withClock) {
Clock(onLog = { trace(it) }, color = if (red) Color.Red else Color(0xFF3F51B5))
}
}
}
Card {
Column(Modifier.padding(12.dp)) {
if (!showSearch) {
OutlinedButton(onClick = { showSearch = true }) { Text("Search...") }
} else {
// 一个在出现后立即获得焦点的字段
val focus = remember { FocusRequester() }
OutlinedTextField(
value = search,
onValueChange = { search = it },
placeholder = { Text("the title follows the input") },
modifier = Modifier.fillMaxWidth().focusRequester(focus),
)
LaunchedEffect(Unit) { focus.requestFocus() }
}
}
}
Text("Log", style = MaterialTheme.typography.titleSmall)
log.forEachIndexed { i, line -> Text("${i + 1}. $line", fontSize = 12.sp) }
}
}
// 一个复选框及其标签;整行都会对按下作出反应。
// onChange 是最后一个参数:它可以写在圆括号之后
@Composable
fun CheckboxRow(label: String, checked: Boolean, onChange: (Boolean) -> Unit) {
ListItem(
modifier = Modifier.toggleable(value = checked, onValueChange = onChange),
leadingContent = { Checkbox(checked = checked, onCheckedChange = null) },
headlineContent = { Text(label) },
)
}
|
- 第 74–78 行:Activity 本身的生命周期:在手机上,它会进入后台(切换到另一个应用、屏幕熄灭),然后返回。我们在进入组合时订阅它的变化([addObserver]),在退出时取消订阅;
- 第 4–89 行:[if (withClock) Clock(...)]:取消勾选该复选框会使时钟离开组合;再次勾选则会创建一个新的时钟;
- 第 99–106 行:一个在出现后立即获得焦点的字段:[LaunchedEffect] 在显示之后、字段已经存在时运行。

日志显示了这个顺序:Activity 被创建、启动并恢复([ON_CREATE]、[ON_START]、[ON_RESUME]);时钟被加入布局;它的颜色变化;然后取消勾选,再重新勾选。
4.5. 示例 14:提供的数据
如何在相距较远的组件之间共享数据,而不必经过所有中间组件一级一级地传递参数?使用 [CompositionLocal],一种“组合局部”的数据:它只声明一次;某个组件把它提供给它的所有后代([CompositionLocalProvider]);任何后代都可以读取它。[Compose] 自己也在使用它:[MaterialTheme.colorScheme]、[LocalContext.current]、[LocalDensity.current] 等。这相当于 [Flutter] 的 [InheritedWidget] 和 [provider] 包。
一个全屏显示的日志:
| // =========================================================================
// ex14/providers/Log.kt - 一份供整个应用使用的数据
// -------------------------------------------------------------------------
// 如何在相距较远的组件之间共享数据和函数,
// 而不必经过所有
// 中间组件一级一级地传递参数?使用 CompositionLocal,一种“组合局部”的
// 数据:
// 1. 它只声明一次:val LocalLog = staticCompositionLocalOf<Log> { ... };
// 2. 位于树的高层的某个组件把它提供给它的所有
// 后代:CompositionLocalProvider(LocalLog provides log) { ... };
// 3. 任何后代,无论深度如何,都可以读取它:
// LocalLog.current。
// 这是 Compose 自己使用的机制:MaterialTheme.colorScheme、
// LocalContext.current、LocalDensity.current 等,都是对
// CompositionLocal 的读取。
//
// 日志本身是一个普通对象,它的状态(它的各行)被
// Compose 观察(mutableStateListOf):读取它的各行的
// 组件在各行变化时会被重组。
// =========================================================================
package fr.stahe.examples.ex14.providers
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.staticCompositionLocalOf
import java.time.LocalTime
import java.time.format.DateTimeFormatter
class Log {
// 被观察的列表;对外它只被视为不可修改的 List
private val _lines = mutableStateListOf<String>()
val lines: List<String> get() = _lines
fun trace(message: String) {
_lines.add(0, "${LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm:ss"))} $message")
if (_lines.size > 6) _lines.removeAt(_lines.lastIndex)
}
}
// 声明:数据的类型,以及无人提供它时会发生什么
// (这里是一个明确的错误)。
// static:所提供的日志永远不变(变化的是它的内容)
val LocalLog = staticCompositionLocalOf<Log> { error("LocalLog: no log provided above this component") }
|
- 第 30–31 行:日志状态,一个被观察的列表,它对外只作为不可修改的 [List] 暴露;
- 第 8 行:声明:数据类型,以及无人提供它时会发生什么(一个明确的错误)。[static]:所提供的数据永远不变(变化的是它的内容)。
一个购物车,由一个提供者组件提供给屏幕的一部分,该组件负责创建它:
| // =========================================================================
// ex14/providers/Cart.kt - 一份由一个组件提供的数据
// -------------------------------------------------------------------------
// 购物车只提供给树的一部分:即 CartProvider 所包裹的
// 组件(参见 Ex14Activity.kt)。放在屏幕两处的两个提供者
// 会得到两个相互独立的购物车。
// 创建购物车的是提供者(remember);它
// 自己使用日志。
// =========================================================================
package fr.stahe.examples.ex14.providers
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.staticCompositionLocalOf
data class Item(val label: String, val price: Double)
class Cart(private val log: Log) {
private val _items = mutableStateListOf<Item>()
val items: List<Item> get() = _items
// 一个计算值:sumOf 把每个商品的一个值累加起来
val total: Double get() = _items.sumOf { it.price }
fun add(item: Item) {
_items.add(item)
log.trace("cart: + ${item.label}")
}
fun remove(index: Int) {
log.trace("cart: - ${_items[index].label}")
_items.removeAt(index)
}
}
val LocalCart = staticCompositionLocalOf<Cart> { error("LocalCart: no cart provided above this component") }
// 提供者:它只创建一次购物车,并把它提供给它的内容
@Composable
fun CartProvider(content: @Composable () -> Unit) {
val log = LocalLog.current
val cart = remember { Cart(log) }
CompositionLocalProvider(LocalCart provides cart, content = content)
}
|
- 第 25 行:[total],一个计算属性;[sumOf] 将每个商品的值累加起来;
- 第 42–45 行:提供者只创建一次购物车([remember])并用内容填充它;它自己读取上层提供的日志。
一个时钟,以可配置的周期提供:
| // =========================================================================
// ex14/providers/Clock.kt - 一个带参数的提供者
// -------------------------------------------------------------------------
// 一个时钟,其刷新周期是提供者的一个
// 参数:ClockProvider(periodMs = 5000) { ... }。
// 两个嵌套的提供者:组件读取的是它上方
// 最近的那一个。
// 这一次,所提供的数据会变化(时间,每次滴答都会变化):
// 使用 compositionLocalOf(而不是 staticCompositionLocalOf)。这样 Compose 只会
// 重组读取时间的那些组件。
// 当提供者消失时,时钟停止(LaunchedEffect)。
// =========================================================================
package fr.stahe.examples.ex14.providers
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.compositionLocalOf
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import kotlinx.coroutines.delay
import java.time.LocalDateTime
// 默认值:一个冻结的日期,由没有提供者的组件读取
val LocalClock = compositionLocalOf { LocalDateTime.of(2026, 1, 1, 0, 0) }
@Composable
fun ClockProvider(periodMs: Long = 1000, content: @Composable () -> Unit) {
var now by remember { mutableStateOf(LocalDateTime.now()) }
// 如果周期变化,协程会被取消并重新启动
LaunchedEffect(periodMs) {
while (true) {
delay(periodMs)
now = LocalDateTime.now()
}
}
CompositionLocalProvider(LocalClock provides now, content = content)
}
|
- 第 27 行:这一次,所提供的数据会变化(时间,每次滴答都会变化):使用 [compositionLocalOf],而不是 [staticCompositionLocalOf]。[Compose] 随后只重建读取时间的那些组件;
- 第 33–36 行:如果周期变化,协程会被取消并重新启动。
使用购物篮的两个后代:
| // ex14/Catalog.kt - 一个向购物车添加商品的后代
package fr.stahe.examples.ex14
import androidx.compose.foundation.layout.Column
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ShoppingCart
import androidx.compose.material3.Card
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import fr.stahe.examples.ex14.providers.Item
import fr.stahe.examples.ex14.providers.LocalCart
val catalog = listOf(Item("Consultation", 30.0), Item("Vaccine", 12.5), Item("Certificate", 5.0))
@Composable
fun Catalog() {
// 由 ShopPage 提供的购物车(如果无人提供则报错)
val cart = LocalCart.current
Card {
Column {
for (item in catalog) {
ListItem(
headlineContent = { Text("${item.label} (€${item.price})") },
trailingContent = {
IconButton(onClick = { cart.add(item) }) {
Icon(Icons.Default.ShoppingCart, contentDescription = "add ${item.label}")
}
},
)
}
}
}
}
// =========================================================================
// ex14/CartSummary.kt
// -------------------------------------------------------------------------
// 另一个后代:与 Catalog 使用同一个购物车,但有它自己的
// 时钟,每 5 秒刷新一次。组件只读取位于它上方的
// 提供者:因此 CartSummary 在它的内容周围放置了第二个
// ClockProvider,并把内容交给一个小
// 组件 Content,后者读取最近的那个时钟:5 秒的那个。
// =========================================================================
package fr.stahe.examples.ex14
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import fr.stahe.examples.ex14.providers.ClockProvider
import fr.stahe.examples.ex14.providers.LocalClock
import fr.stahe.examples.ex14.providers.LocalCart
@Composable
fun CartSummary() {
ClockProvider(periodMs = 5000) { Content() }
}
@Composable
private fun Content() {
val cart = LocalCart.current
val now = LocalClock.current // 最近的那个:5 秒的那个
Card {
Column(Modifier.padding(12.dp)) {
Text(
"Cart (${cart.items.size} item(s)) - ${now.toLocalTime().withNano(0)}",
style = MaterialTheme.typography.titleSmall,
)
cart.items.forEachIndexed { i, item ->
Row(verticalAlignment = Alignment.CenterVertically) {
Text(item.label)
TextButton(onClick = { cart.remove(i) }) { Text("remove") }
}
}
Text("Total: €${cart.total}", fontWeight = FontWeight.Bold)
}
}
}
|
- 第 29–30 行:[CartSummary] 在它的内容外围放置了第二个时钟提供者(5 秒):组件读取的是它上方最近的那个时钟提供者。
屏幕:
| // =========================================================================
// ex14/Ex14Activity.kt - 三个层级的提供数据
// -------------------------------------------------------------------------
// - 日志:由 Activity 在最顶层提供给整个屏幕;
// - 购物车,由 ShopPage 提供:由 Catalog 和
// CartSummary 共享,它们看到的是同一个购物车;
// - 时钟,由 ShopPage(默认周期,1 秒)以及
// CartSummary(5 秒)提供:各有各的时钟。
// =========================================================================
package fr.stahe.examples.ex14
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.ex14.providers.ClockProvider
import fr.stahe.examples.ex14.providers.CartProvider
import fr.stahe.examples.ex14.providers.Log
import fr.stahe.examples.ex14.providers.LocalClock
import fr.stahe.examples.ex14.providers.LocalLog
class Ex14Activity : ComponentActivity() {
// 日志:与 Activity 一起创建的对象
private val log = Log()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent {
// 日志,提供给整个屏幕
CompositionLocalProvider(LocalLog provides log) {
ExamplesTheme { ShopPage() }
}
}
}
}
// 页面时钟显示的时间:一个小组件,放在提供者之下
@Composable
private fun PageTime() {
Text("Clock of the page: ${LocalClock.current.toLocalTime().withNano(0)}", color = Color.Gray)
}
@Composable
fun ShopPage() {
// 页面读取日志:每出现一行新内容,它就会被重组
val log = LocalLog.current
ClockProvider {
CartProvider {
ExamplePage("Example 14 - provided data") {
PageTime()
Catalog()
CartSummary()
Spacer(Modifier.height(12.dp))
Text("Log (provided to the whole screen)", style = MaterialTheme.typography.titleSmall)
for (line in log.lines) {
Text(line, fontSize = 12.sp)
}
}
}
}
}
|
- 第 43–44 行:日志,一个 Activity 对象,渲染在屏幕上;
- 第 60–65 行:时钟(1 秒)和购物车,提供给页面;[Catalog] 和 [CartSummary] 看到的是同一个购物车。

4.6. 示例 15:复用行为
复用显示需要编写一个组件。要复用行为(及其状态),[Compose] 提供了两种工具:“包装”组件,或 [remember...] 函数。一个在被触摸时高亮其内容的包装组件:
| // =========================================================================
// ex15/Highlighter.kt - 包装组件中的一种行为
// -------------------------------------------------------------------------
// 复用行为(及其状态)的第一种方式:
// 一个包裹任意内容并为它添加这种
// 行为的组件:
// Highlighter(color = ...) { ListItem(...) }
// 这个组件在其内容被触摸(手指放在
// 屏幕上)时,以及在使用鼠标(平板、ChromeOS)时,在其被
// 悬停时高亮其内容。每个 Highlighter 都有自己的状态:两行之间互不干扰。
// =========================================================================
package fr.stahe.examples.ex15
import androidx.compose.animation.animateColorAsState
import androidx.compose.animation.core.tween
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.awaitEachGesture
import androidx.compose.foundation.gestures.awaitFirstDown
import androidx.compose.foundation.gestures.waitForUpOrCancellation
import androidx.compose.foundation.hoverable
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.interaction.collectIsHoveredAsState
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.pointer.pointerInput
@Composable
fun Highlighter(color: Color = Color(0xFFFFF3CD), content: @Composable () -> Unit) {
var touched by remember { mutableStateOf(false) }
// 鼠标悬停:一个“交互源”,其
// “悬停”状态被观察
val interactions = remember { MutableInteractionSource() }
val hovered by interactions.collectIsHoveredAsState()
// 带动画的颜色变化(200 毫秒)
val fill by animateColorAsState(if (touched || hovered) color else Color.Transparent, tween(200), label = "fill")
Box(
Modifier
.background(fill)
.hoverable(interactions)
// 手指的接触,位于最底层:手指按下,
// 然后抬起(或手势被取消)。requireUnconsumed = false:
// 即使内容(一个按钮)已经处理了这次按下
.pointerInput(Unit) {
awaitEachGesture {
awaitFirstDown(requireUnconsumed = false)
touched = true
waitForUpOrCancellation()
touched = false
}
},
) {
content()
}
}
|
- 第 38–39 行:鼠标悬停(平板、[ChromeOS]):一个“交互源”,其“悬停”状态被观察;
- 第 41 行:[animateColorAsState]:带动画的颜色变化;
- 第 49–54 行:最底层的手指触摸:对于每个手势([awaitEachGesture]),我们等待手指触碰屏幕,然后等待它抬起。[requireUnconsumed = false]:即使内容(一个按钮)已经处理了这次按下。
一个带动画的组件:一个必须按住一秒钟的按钮,同时一个圆环逐渐填满:
| // =========================================================================
// ex15/LongPressButton.kt - 一个长按按钮
// -------------------------------------------------------------------------
// LongPressButton(durationMs = 1000, onAction = { remove() }) { Text(...) }
// 只有在按住按钮达到
// 整个时长时才会执行动作:这是防止误按的保护措施。按下期间
// 一个圆环逐渐填满。
// 填充是一个动画:Animatable 是一个值(从 0 到 1),
// 由协程逐帧改变它(animateTo)。取消
// 协程(手指抬起得太早)会停止动画。
// =========================================================================
package fr.stahe.examples.ex15
import androidx.compose.animation.core.Animatable
import androidx.compose.animation.core.LinearEasing
import androidx.compose.animation.core.tween
import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.unit.dp
import kotlinx.coroutines.launch
@Composable
fun LongPressButton(durationMs: Int = 1000, onAction: () -> Unit, content: @Composable () -> Unit) {
val progress = remember { Animatable(0f) }
// 组件协程的作用域:如果组件消失,它们会被取消
val scope = rememberCoroutineScope()
val action by rememberUpdatedState(onAction)
Row(
verticalAlignment = Alignment.CenterVertically,
modifier = Modifier.pointerInput(Unit) {
detectTapGestures(
// onPress:手指按下;tryAwaitRelease 等待它抬起
onPress = {
val filling = scope.launch {
progress.animateTo(1f, tween(durationMs, easing = LinearEasing))
// 动画已走到终点:按压持续的时间足够长
progress.snapTo(0f)
action()
}
tryAwaitRelease()
// 手指抬起得太早:填充被停止,圆环清空
if (filling.isActive) {
filling.cancel()
scope.launch { progress.animateTo(0f, tween(200)) }
}
},
)
},
) {
CircularProgressIndicator(
progress = { progress.value },
modifier = Modifier.size(22.dp),
color = Color.Red,
strokeWidth = 3.dp,
trackColor = Color(0xFFFFEBEE),
)
Spacer(Modifier.width(8.dp))
content()
}
}
|
- 第 37–39 行:一个 [Animatable],一个值(从 0 到 1),由协程逐帧递增;[rememberCoroutineScope]:用于从事件中启动协程的作用域;
- 第 47–58 行:手指按下:启动填充动画([animateTo(1f)],时长为 [durationMs]);如果填充到达终点,则执行该动作。[tryAwaitRelease()] 等待手指抬起:如果填充操作仍在进行,则将其取消,圆环清空。
一个 [remember...] 函数,它在设置好状态和副作用之后返回一个对象(这是 [Compose] 的约定:[rememberScrollState()]、[rememberCoroutineScope()] 等),如下所示:
| // =========================================================================
// ex15/FocusOnStart.kt - “remember...”函数中的一种行为
// -------------------------------------------------------------------------
// 复用行为的第二种方式:一个
// @Composable 函数,在设置好它的状态和
// 副作用之后返回一个对象。这是 Compose 的约定(rememberScrollState()、
// rememberCoroutineScope() 等):它的名称以“remember”开头。
// val focus = rememberFocusOnStart()
// OutlinedTextField(..., modifier = Modifier.focusRequester(focus))
// 使用这个 FocusRequester 的字段在屏幕
// 显示后立即获得焦点。
// =========================================================================
package fr.stahe.examples.ex15
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.ui.focus.FocusRequester
@Composable
fun rememberFocusOnStart(): FocusRequester {
val focus = remember { FocusRequester() }
// 第一次显示之后:字段已经存在,把焦点交给它
LaunchedEffect(Unit) { focus.requestFocus() }
return focus
}
|
屏幕:
| // =========================================================================
// ex15/Ex15Activity.kt - 复用行为
// -------------------------------------------------------------------------
// 三种用于复用行为(及其状态)而不仅仅是
// 复用显示的 Compose 工具:
// - 一个“包装”组件(Highlighter);
// - 一个带有动画的组件(LongPressButton);
// - 一个“remember...”函数(rememberFocusOnStart)。
// =========================================================================
package fr.stahe.examples.ex15
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.material3.ListItem
import androidx.compose.material3.ListItemDefaults
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.key
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
class Ex15Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent { ExamplesTheme { BehavioursPage() } }
}
}
@Composable
fun BehavioursPage() {
val doctors = remember { mutableStateListOf("Mme Marie PELISSIER", "Mr Paul TATOU", "Melle Sophie DUPONT") }
var message by remember { mutableStateOf("") }
// 由 rememberFocusOnStart 准备好的 FocusRequester
val focus = rememberFocusOnStart()
var input by remember { mutableStateOf("") }
ExamplePage("Example 15 - reusing behaviours") {
OutlinedTextField(
value = input,
onValueChange = { input = it },
placeholder = { Text("this field received the focus on its own") },
modifier = Modifier.fillMaxWidth().focusRequester(focus),
)
Spacer(Modifier.height(12.dp))
Text("Touch the lines; hold a button down for one second to delete.", color = Color.Gray)
doctors.forEachIndexed { i, d ->
key(d) {
// 每两行中的一行:默认颜色;其他行为绿色
Highlighter(color = if (i % 2 == 0) Color(0xFFFFF3CD) else Color(0xFFD1E7DD)) {
ListItem(
// 透明背景:Highlighter 的背景会透出来
colors = ListItemDefaults.colors(containerColor = Color.Transparent),
headlineContent = { Text(d) },
trailingContent = {
LongPressButton(onAction = {
doctors.remove(d)
message = "$d has been deleted."
}) {
Text("Delete", color = Color.Red)
}
},
)
}
}
}
Spacer(Modifier.height(12.dp))
if (message.isNotEmpty()) {
Text(message, color = Color(0xFF3F51B5))
}
}
}
|


左图:手指停在第一行上:该行被高亮;右图:“Delete”按钮被按住了一秒钟。
4.7. 示例 16:可复用的确认窗口
在 [Compose] 中,窗口([AlertDialog])和其他组件一样:只要有状态要求,它就会显示。为了提出问题并给出答案,我们编写一个小类,其 [confirm] 函数是一个挂起函数(见示例 19):
| // =========================================================================
// ex16/Confirmation.kt - “你确定吗?”
// -------------------------------------------------------------------------
// 在 Compose 中,对话框(AlertDialog)和其他组件一样:
// 只要有状态要求,它就会显示。为了提出问题
// 并等待回答,我们编写一个小类 Confirmation,它的
// confirm 函数是一个挂起函数(suspend,参见示例
// 19):它打开对话框,然后在不阻塞手机的情况下等待
// 用户回答。这样,调用它的代码就可以写得非常简单,
// 放在协程中:
//
// if (confirmation.confirm("Delete this doctor?")) { ... }
//
// 不作回答就关闭对话框(点击外部、手机的返回
// 按钮)会被视为“否”。
// 对话框本身由 ConfirmDialog(confirmation) 显示,
// 在屏幕中只放置一次。
// =========================================================================
package fr.stahe.examples.ex16
import androidx.compose.material3.AlertDialog
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.graphics.Color
import kotlinx.coroutines.CompletableDeferred
class Confirmation {
// 提出的问题(null:没有对话框)
var question by mutableStateOf<String?>(null)
private set
// 期望的回答:一个稍后才会到来的值
private var answer: CompletableDeferred<Boolean>? = null
suspend fun confirm(message: String): Boolean {
val waiting = CompletableDeferred<Boolean>()
answer = waiting
question = message // 显示对话框
try {
return waiting.await() // 协程被挂起,直到有了回答
} finally {
question = null // 对话框消失
}
}
fun respond(yes: Boolean) {
answer?.complete(yes)
}
}
// remember:Confirmation 在屏幕重组之后依然存在
@Composable
fun rememberConfirmation(): Confirmation = remember { Confirmation() }
@Composable
fun ConfirmDialog(confirmation: Confirmation) {
// ?: return:没有问题,则没有可显示的内容
val question = confirmation.question ?: return
// AlertDialog:Material 对话框,带有标题、内容和按钮
AlertDialog(
onDismissRequest = { confirmation.respond(false) }, // 未作回答就关闭:视为“否”
title = { Text("Confirmation") },
text = { Text(question) },
dismissButton = { TextButton(onClick = { confirmation.respond(false) }) { Text("No, go back") } },
confirmButton = {
Button(
onClick = { confirmation.respond(true) },
colors = ButtonDefaults.buttonColors(containerColor = Color(0xFFD32F2F)),
) { Text("Yes, confirm") }
},
)
}
|
- 第 36–37 行:提出的问题([null]:无窗口),一个被观察的状态;
- 第 42–49 行:[CompletableDeferred]:一个稍后才会到来的值。[confirm] 显示窗口,然后等待响应([await()]),而不会冻结手机;[finally]:无论如何,窗口都会消失;
- 第 53–54 行:窗口的某个按钮提供响应:正在等待的协程随即恢复;
- 第 63–68 行:窗口:如果没有问题则什么都不显示([?: return]);不作回答就关闭窗口(点击窗口外部或按手机的返回按钮)会被视为“否”。
屏幕:一个联系人列表,并且在每次删除之后弹出一条消息([Snackbar]),带有“Undo”按钮,这是另一种在移动设备上非常常见、用来防止用户犯错的方法:
| // =========================================================================
// ex16/Ex16Activity.kt - 使用确认对话框
// -------------------------------------------------------------------------
// 一次删除,然后在屏幕底部显示一条短暂的消息(Snackbar),
// 带有“Undo”按钮:这是另一种在移动端非常常见的、
// 防止用户出错的方法。
// 两次等待(对问题的回答、消息上的
// “Undo”按钮)都在协程中完成,该协程由 rememberCoroutineScope 启动。
// =========================================================================
package fr.stahe.examples.ex16
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.outlined.Delete
import androidx.compose.material3.Button
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.SnackbarDuration
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.SnackbarResult
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.coroutines.launch
data class Contact(val id: Int, val name: String)
class Ex16Activity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent { ExamplesTheme { ContactsPage() } }
}
}
@Composable
fun ContactsPage() {
val contacts = remember { mutableStateListOf(Contact(1, "Jean MARTIN"), Contact(2, "Alice DURAND"), Contact(3, "Luc GERMAN")) }
var message by remember { mutableStateOf("") }
val confirmation = rememberConfirmation()
// 短暂消息的区域,以及用于启动协程的作用域
val messages = remember { SnackbarHostState() }
val scope = rememberCoroutineScope()
// 一个挂起函数:它“等待”用户的回答
suspend fun remove(c: Contact) {
if (!confirmation.confirm("Delete the contact ${c.name}?")) {
message = "Deletion abandoned."
return
}
val position = contacts.indexOf(c)
contacts.remove(c)
message = "${c.name} has been deleted."
// 屏幕底部的一条短暂消息;showSnackbar 等待它
// 消失,并告知它的按钮是否被触碰过
val result = messages.showSnackbar("${c.name} deleted", actionLabel = "Undo", duration = SnackbarDuration.Short)
if (result == SnackbarResult.ActionPerformed) {
contacts.add(position, c)
message = "${c.name} is back."
}
}
suspend fun removeAll() {
if (confirmation.confirm("Delete the ${contacts.size} contacts?")) {
contacts.clear()
message = "All the contacts have been deleted."
}
}
ExamplePage("Example 16 - a confirmation dialog", messages = messages) {
for (c in contacts) {
ListItem(
leadingContent = { Icon(Icons.Default.Person, contentDescription = null) },
headlineContent = { Text(c.name) },
trailingContent = {
// launch:一个协程,以便能够调用挂起函数
IconButton(onClick = { scope.launch { remove(c) } }) {
Icon(Icons.Outlined.Delete, contentDescription = "delete ${c.name}", tint = Color.Red)
}
},
)
}
if (contacts.isEmpty()) {
ListItem(headlineContent = { Text("No contact.", color = Color.Gray) })
}
Spacer(Modifier.height(12.dp))
Button(
onClick = { scope.launch { removeAll() } },
// 列表为空时,按钮被禁用
enabled = contacts.isNotEmpty(),
colors = ButtonDefaults.buttonColors(containerColor = Color(0xFFD32F2F)),
) { Text("Delete all") }
Spacer(Modifier.height(12.dp))
if (message.isNotEmpty()) {
Text(message, color = Color(0xFF3F51B5))
}
}
// 对话框,在提出问题时显示
ConfirmDialog(confirmation)
}
|
- 第 60–61 行:弹出消息的区域,传给 [ExamplePage](它再传给 [Scaffold]),以及一个协程作用域;
- 第 64–77 行:一个读起来像普通代码的挂起函数:发出请求,等待响应;删除;显示消息,等待它消失([showSnackbar] 指示其按钮是否被点按),必要时取消;
- 第 95 行:[scope.launch [ ... ]]:一个协程,以便能够从事件中调用挂起函数;
- 第 117 行:窗口,在屏幕上只放置一次。

