3. 使用 Kotlin 和 Jetpack Compose 入门
3.1. 示例 01:Android 应用的结构
3.1.1. 项目
示例项目由 [Android Studio] 创建(模板为 [Empty Activity],见上一章),然后补全。[Android] 项目就是一个 [Gradle] 项目:这个工具负责下载库、编译 [Kotlin] 代码,并生成安装到手机上的 [.apk] 文件。它由几个用 [Kotlin] 编写的文件来描述(即 [.kts] 文件,“Kotlin 脚本”)。
3.1.2. settings.gradle.kts 文件
- 第 7–17 行:[Gradle] 查找其插件的位置([Gradle] 的扩展:[Android] 插件、[Compose] 编译器等):Google 仓库和 Java 库的中央仓库([Maven Central]);
- 第 25–29 行:[Gradle] 查找应用所用库的位置;
- 第 3–11 行:项目名称及其唯一的模块,即位于 [app/] 文件夹中的应用。
3.1.3. 版本目录:gradle/libs.versions.toml
所有插件和库的版本都集中在一个 TOML 格式的文件中:
- [[versions]] 部分:带名称的版本号;
- [[libraries]] 部分:库,由其组和名称([Maven])以及版本来标识。[Compose] 库没有版本:由“BOM”([compose-bom],“Bill of Materials”,物料清单)一次性为它们全部设定相互兼容的版本;
- [[plugins]] 部分:用于 [Gradle] 的插件。[build.gradle.kts] 文件通过名称引用它们:[libs.okhttp]、[libs.plugins.kotlin.compose](连字符被替换为句点)。
每个库的用途都在注释中说明;每个库都将在使用它的示例中演示。
3.1.4. app/build.gradle.kts 文件
应用本身的配置:
- 第 6–13 行:应用于该模块的插件:[Android] 插件(它同时负责编译 [Kotlin])、[Compose] 编译器(负责转换 [@Composable] 函数),以及 [kotlinx.serialization] 插件(为 [@Serializable] 类生成 JSON 转换代码;见示例 05);
- 第 18–21 行:[namespace],基础代码包(即资源类 [R] 所在的包);[compileSdk],编译所用的 API 和 [Android] 版本;
- 第 24–32 行:[applicationId],应用在手机上的唯一标识符;[minSdk = 26]:该应用可安装在 [Android] 8.0 及更高版本上;[targetSdk],应用经过测试所针对的版本;
- 第 33–36 行:[BuildConfig] 类的一个字段,在编译时生成:JSON 服务器的地址(示例 22–25),可以在编译时更改([-Pserver=...]);
- 第 52–55 行:[compose = true] 激活 [Compose];[buildConfig = true] 生成 [BuildConfig] 类;
- 第 59–88 行:应用所用的库([implementation])、插桩测试所用的库([androidTestImplementation]),以及仅用于调试的版本所用的库([debugImplementation])。
3.1.5. AndroidManifest.xml 文件
清单是应用面向 [Android] 系统的“身份证”:它声明应用的权限、[Application] 类以及 Activity,即 [Android] 可以启动的屏幕:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | |
- 第 13 行:访问网络的权限(示例 22 到 25);
- 第 20–32 行:应用:它的 [Application] 类(示例 23)、图标、名称([@string/app_name],一个资源,见示例 21)、主题,以及“明文”HTTP 流量(本课程的服务器不使用 HTTPS);
- 第 37–43 行:菜单,即启动 Activity:意图过滤器 [MAIN] / [LAUNCHER] 实际上表示由应用图标启动的 Activity;
- 第 49–71 行:一个示例 Activity;[exported="false"]:只有本应用才能打开它们。
3.1.6. Activity:Ex01Activity.kt
示例 01 的代码:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | |
- 第 16 行:文件的包([package]):每个示例都有自己的包,因此两个示例中可以出现同名的函数(如 [HomePage]);
- 第 14 行:[@file:OptIn(...)]:[Material 3] 的某些函数([TopAppBar])仍被标记为“实验性”;我们声明在充分知晓风险的前提下使用它们;
- 第 47–48 行:普通数据,位于任何 [@Composable] 函数之外;[const val]:编译时已知的常量;
- 第 54 行:Activity,一个继承自 [ComponentActivity] 的类。[Android] 在启动屏幕时创建它,然后调用它的函数 [onCreate];
- 第 59–64 行:[enableEdgeToEdge()]:应用也会绘制到状态栏下方和手机导航栏下方(自 [Android] 15 起这是规则);[setContent [ ... ]]:[Compose] 接管屏幕并在其中显示该代码块的内容。[ExamplesTheme](文件 [common/Theme.kt])将 [Material 3] 的颜色应用到它所包含的一切内容上;
- 第 7–73 行:一个 [@Composable] 函数:它通过调用其他 [@Composable] 函数来描述屏幕的一部分。按惯例,它的名称以大写字母开头,就像类名一样;它不返回任何值;
- 第 79–80 行:状态。[mutableIntStateOf(0)] 创建一个被 [Compose] 观察的值:当它变化时,[Compose] 会重新执行读取它的函数(重组)。[by] 将变量 [counter] 委托给这个状态:[counter++] 的写法与普通变量完全一样。[rememberSaveable]:该值在函数的前后两次执行之间得以保留(如果没有 [remember],每次执行都会把状态重置为 0)……甚至当 [Android] 重建 Activity 时也是如此,而每次屏幕旋转都会发生这种重建;
- 第 83–85 行:[Scaffold],[Material] 屏幕的结构:一个顶部栏([topBar])和内容。内容是一个 lambda,它接收必须遵守的边距(顶部栏的位置);
- 第 88 行:[Column] 将其子元素自上而下排列。[Modifier]:[Compose] 的用于调整组件(边距、大小、背景、手势响应等)的方法:修饰符按其应用的顺序串联在一起;
- 第 89–97 行:文本和间距([Spacer]);[MaterialTheme.typography.headlineSmall]:主题的文本样式之一;["$[...]"] 将表达式插入字符串;
- 第 101–105 行:一个按钮。[onClick] 接收按下按钮时要执行的函数(一个 lambda):它修改状态,仅此而已。我们从不直接与屏幕交互:[Compose] 会重新执行 [HomePage],从而显示新的计数器;圆括号之后用花括号括起来的最后一个 lambda 是按钮的内容(即它的文本);
- 第 109–111 行:读取状态的文本;每次点击后它都会更新。
示例的主题,[common/Theme.kt]:
- [lightColorScheme(...)]、[darkColorScheme(...)]:[Material 3] 的浅色和深色配色;未指定的颜色保留其默认值;
- [ExamplesTheme(dark, content)]:一个 [@Composable] 函数,它接收……另一个 [@Composable] 函数作为其内容。这是组合的核心机制(见示例 12):[ExamplesTheme [ HomePage() ]] 以这个内容调用 [MaterialTheme]。
3.1.7. 执行
在 [Android Studio] 中,[Run] 按钮会启动应用:出现示例菜单;第一行打开示例 01。点击按钮两次之后:


旋转手机(或模拟器,使用其工具栏上的旋转按钮):Activity 被 [Android] 销毁后重新创建,但计数器保持不变,这要归功于 [rememberSaveable]。将 [rememberSaveable] 换成 [remember]:每次旋转后计数器都会重置为 0。这是与 [Flutter] 的一个关键区别,在 Flutter 中屏幕在旋转时会保持不变:而在 [Android] 中,当设备的设置(方向、语言、文字大小等)发生变化时,Activity 会被重新创建。
3.2. 示例 02:状态与计算值
一个简单的含增值税价格计算器,它区分状态(用户输入的内容)与由此得到的计算结果。在这个示例中,屏幕结构(顶部栏、可滚动的内容)在 [common/ExamplePage.kt] 中一次性定义好:
- [content: @Composable ColumnScope.() -> Unit]:内容是在 [Column] 内部调用的 [@Composable] 函数(因此可以使用列专属的修饰符,例如 [weight]);
- [verticalScroll(rememberScrollState())]:当列超出屏幕高度时可以滚动;[imePadding()]:手机键盘不会遮住屏幕底部;
- 调用时使用尾随 lambda:[ExamplePage("title") [ Text(...) ; Button(...) ]]。
示例的代码:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 | |
- 第 72–75 行:纯函数,位于屏幕之外:将输入的价格(["2,5"] 或 ["2.5"])转换为数字,以及含增值税的总价;
- 第 88–94 行:状态。[history] 是一个不可修改的列表([listOf]):每次变化时都会用新列表替换它,[Compose] 会检测到这一点(即状态的赋值);
- 第 98–101 行:计算值就是简单的局部变量。每次状态变化时函数都会重新执行:它们始终是最新的,因此无需同步;
- 第 106–112 行:一个局部函数,所有修改都经由它进行:它记录修改前的总价,应用修改([update()]:作为参数传入的函数),计算新的总价,并更新历史记录。状态变量在赋值之后立即就有了新值;[take(5)] 保留前五行;
- 第 117 行:最近使用的应用列表中的应用标题会随状态变化(来自 [common/TaskTitle.kt] 的函数 [TaskTitle],它调用 Activity 的 [setTaskDescription]);
- 第 125–136 行:一个受控字段:它显示 [value],并在每次按键时以新文本调用 [onValueChange]。在 [Compose] 中,字段中的文本只是又一个状态:既不需要创建也不需要释放任何控制器,[Reset] 只需修改状态即可;
- 第 143 行:[KeyboardOptions(keyboardType = KeyboardType.Decimal)]:手机的数字键盘;
- 第 147–156 行:数量:[enabled = quantity > 0] 在数量为 0 时禁用“减号”按钮;[Modifier.weight(1f)]:文本占据该行剩余的全部宽度;
- 第 44–168 行:“分段”按钮,其中只有一个被选中:增值税率。[forEachIndexed] 连同每个元素的序号一起遍历列表;[itemShape] 将第一个和最后一个元素的角设为圆角;
- 第 209–212 行:[Line],一个带参数的 [@Composable] 函数,其中一个参数是可选的([style],有默认值)。


左图:点按 [+] 两次、选择 10% 并输入 3.2 之后;右图:该项已发生变化,数量已恢复为 1,历史记录记下了总价的每一次变化。
3.3. 示例 03:编写组件树
[Compose] 没有模板语言:对于条件和循环,我们直接在 [@Composable] 函数中使用 [Kotlin] 的语句。一个按输入内容过滤的医生列表:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 | |
- 第 68–78 行:一个枚举和一个数据类([data class]):[Kotlin] 会自动生成 [equals]、[hashCode]、[toString] 和 [copy];
- 第 89–99 行:一个 [when] 表达式:在多个值中取其一;编译器会验证枚举中的所有情形都已处理([else]:所有其他情形)。[to] 创建一个键值对([Pair]);
- 第 117–120 行:显示的列表,每次执行时根据状态计算得出([filter]);
- 第 126–130 行:[icon]:[ExamplePage] 中用于顶部栏图标的槽位。[painterResource(R.drawable.doctor)]:应用中的一张图像(一个矢量文件,即 [Android] 的矢量格式,由 Flutter 示例中的 SVG 文件通过 [Android Studio] 的 [New / Vector Asset] 转换而来)。[R]:为每个资源分配一个编号的生成类;
- 第 136 行:[it]:lambda 唯一参数的名称;
- 第 150 行:一个 [if]:只有当条件为真时,组件才存在;
- 第 159–165 行:不带参数的 [when](一连串 [if]):三个代码块之一;一个 [for] 循环,带有每个元素的序号([withIndex()] 和 [(i, d)] 解构);
- 第 173 行:计算得出的样式:文字大小取决于医生的数量([sp]:文本的单位,会随手机的文字大小设置变化;[dp]:距离的单位);
- 第 180–199 行:一个列表行([ListItem],带有各个位置 [leadingContent]、[headlineContent]……),如果医生不可预约,则通过 [Modifier.alpha] 将其置灰;[FlowRow]:空间不足时自动换行的一行;一个小标签([SuggestionChip]),其颜色取决于医生。



3.4. 示例 04:事件
一个待办事项列表:可以添加事项、勾选事项并删除事项(使用按钮,或滑动该行,这是移动设备上典型的手势),此外还有一个对触摸敏感的区域。交互式组件接收函数作为参数,在发生某件事时调用:这些就是 [Compose] 的“事件”。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 | |
- 第 84 行:一个任务,一个不可修改的对象;勾选它会创建一个副本([copy(done = true)])来替换它;
- 第 99–102 行:[mutableStateListOf]:一个被 [Compose] 观察的列表;添加、删除或替换元素都会触发重建。这里我们保留 [remember](而不是 [rememberSaveable]):如果 Activity 被重新创建,这些列表就会丢失;
- 第 107 行:一个 [FocusRequester],代码通过它在每次添加之后把焦点(光标和键盘)交给该字段([focus.requestFocus()]);
- 第 115–135 行:三个修改状态并维护日志的局部函数;
- 第 149–150 行:[imeAction = ImeAction.Done]:手机键盘的确认键变为“OK”,[keyboardActions] 指定按下它时要做什么:添加任务;
- 第 68–160 行:[onPreviewKeyEvent] 接收来自物理键盘(模拟器中的 PC 键盘,或平板的键盘)的按键:[Escape] 会清空该字段。返回 [true] 会终止该事件;
- 第 171–175 行:[key(t.id)] 为每一行分配一个标识。没有 [key] 时,[Compose] 会把一行的状态(此处是其滚动位置)与该行在列表中的位置关联起来:删除之后,下一行就会继承被删除行的状态。两个 lambda 表达式 [onToggle] 和 [onRemove]“捕获”任务 [t],并把该行传给它们的任何内容转发出去;
- 第 187–192 行:[Modifier.pointerInput] 使任何组件都能响应手势:它区分单击、双击和长按。位置以像素给出:借助屏幕密度([LocalDensity])将其转换为 [dp];
- 第 208 行:[TaskRow] 接收任务,以及两个用于通知其调用者的函数:它自己不会修改列表(见示例 11);
- 第 212–218 行:[SwipeToDismissBox]:该行向左移动([enableDismissFromStartToEnd = false] 阻止向另一个方向移动),露出 [backgroundContent];到达末端时,调用 [onDismiss];
- 第 230 行:复选框传递它的新值([Boolean]):类型正好是 [(Boolean) -> Unit] 的 [onToggle] 被直接传给它。



左图:已添加一个任务,勾选了另一个任务,并点按了该区域;中图:第一行向左滑动;右图:它已被删除,日志对此予以确认。
3.5. 示例 05:所有类型的字段
在 [Compose] 中,所有字段都是受控的:字段显示来自状态的值,并通过一个更新状态的函数通知每一次变化。这个函数传递什么取决于字段:
- [OutlinedTextField]:新的文本([String]);
- [Checkbox]、[Switch]:一个 [Boolean];
- [RadioButton]、[FilterChip]:什么也不传,该项就是被选中的;
- [Slider]:一个 [Float];
- [DatePickerDialog]:一个日期,在确认时传递。
对于下拉列表,[Material 3] 并没有提供单一的、自成一体的组件:它在 [common/DropdownList.kt] 中一次性组装好:
- 第 36–44 行:[fun <T> DropdownList]:一个泛型函数:选项可以是字符串、数字、医生等等。[text] 指定如何显示一个选项(默认为其 [toString()]);
- 第 47 行:每个列表特有的状态:菜单是否展开?
- 第 48–49 行:[ExposedDropdownMenuBox] 将一个只读字段([readOnly = true],显示当前选项)与一个菜单关联起来;[menuAnchor] 使该字段成为菜单的锚点;
- 第 63–68 行:每个选项对应一行菜单;按下它会通知调用者([onChange(c)])并关闭菜单。
示例的代码:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 | |
- 第 89–101 行:所有表单值,归并在一个 [@Serializable] 类中:[kotlinx.serialization] 插件在编译时生成将其转换为 JSON 的代码([Json.encodeToString(Model.serializer(), model)]);
- 第 118–130 行:每个字段一个状态。[myHobbies] 是一个不可修改的集合([Set]):[myHobbies + h] 和 [myHobbies - h] 会生成新的集合;[birthDate] 是一个“可空”的日期([LocalDate?]):在选定值之前为 [null];
- 第 133–143 行:模型,每次执行时计算的值;[toIntOrNull()]:返回该数字,如果文本不是数字则返回 [null];
- 第 150–157 行:单选按钮。[Modifier.selectable] 使整行(按钮和文本)都可点击;因此按钮本身没有动作([onClick = null]);[selectableGroup] 为无障碍工具将这些按钮分组;
- 第 177–182 行:只有在离开字段时,才会把展示内容复制到状态中;[onFocusChanged] 在字段获得或失去焦点时触发通知;
- 第 187–189 行:一个复选框,其工作方式与单选按钮相同(整行使用 [Modifier.toggleable]);
- 第 193–198 行:用于选择多个值的复选框([FilterChip]);空间不足时 [FlowRow] 会将它们换到下一行;
- 第 203–208 行:来自 [common/] 的下拉列表;
- 第 224–228 行:一个从 1 到 5 的滑块:[steps = 3] 表示带有中间档位;
- 第 236–248 行:“通过代码填充”:修改状态,字段随之变化;
- 第 251–259 行:以缩进的 JSON 显示的模型([Json [ prettyPrint = true ]]);[sent?.let [ ... ]]:只有当 [sent] 不是 [null] 时该代码块才存在;
- 第 271–288 行:只有当 [calendarOpen] 为 true 时日历窗口才存在。[DatePicker] 以自 1970 年 1 月 1 日起的毫秒数(UTC 时间)工作:借助 [java.time]([LocalDate]、[Instant]、[ZoneOffset.UTC])可以双向转换。



日历([DatePickerDialog])是英文的:[Material 3] 会遵循应用的语言(见示例 21)。
3.6. 示例 06:表单、对象、reducer
示例 05 中每个字段有一个状态变量。对于真正的表单,我们更倾向于用一个包含所有值的对象,并在一个纯函数,即 REDUCER 中描述它的各种变化:[reducer(currentState, action) -> newState]。屏幕不再修改状态:它只报告发生了什么(“LASTNAME 字段现在的值为‘Dupont’”“LASTNAME 字段已被离开”),由 reducer 据此推导出新的状态。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 | |
- 第 77 行:每个字段的名称,一个列表;
- 第 82–113 行:不可修改的 profile,带有两个函数,用于读取或替换由其名称指定的字段([v as String]:一种类型转换,在运行时验证);
- 第 117–123 行:JSON 形式的 profile:[Field.entries],枚举值的列表;[associate] 生成一个 [Map];[is Int]:一个类型检查,之后 [v] 会被识别为 [Int](即“智能转换”);
- 第 141 行:完整的状态:各个值,以及所有已经被离开(“touched”)的字段;
- 第 145–149 行:可能的动作。[sealed]:除了这里声明的以外没有其他动作,编译器知道这一点。[data object]:不带数据的动作,一个单例对象;
- 第 155–161 行:reducer:对动作使用 [when],没有 [else]:编译器会验证所有动作都已被处理。在每个分支中,[action] 具有该分支的类型:对于 [Update],可以访问 [action.field];
- 第 179–183 行:状态,以及修改它的唯一方式 [dispatch(action)];
- 第 188–190 行:由状态推导出的值:如果字段的值与初始值不同,则该字段为“已修改”;未订阅新闻通讯时,电子邮件被禁用;
- 第 195–209 行:一个局部的 [@Composable] 函数(定义在另一个函数内部):一个绑定到模型的文本字段。每个字段有自己的状态([hadFocus]):当它在获得焦点之后又失去焦点时,即被视为“已离开”;
- 第 236–241 行:年龄滑块:松开时调用 [onValueChangeFinished];
- 第 277–285 行:一个简单的表格,每行一个 [Row],各列宽度相等([weight(1f)]);
- 第 291–293 行:带有多种样式的文本:[buildAnnotatedString]。


reducer 是一个普通函数:无需屏幕,用一个简单的单元测试就可以测试它([assertEquals(expected, reducer(state, action))])。
3.7. 示例 07:手动验证表单
RdvMedecins 应用的“创建账户”表单,规则与服务器相同。一个纯函数 [validate(account)] 返回错误;这些错误只对已经被离开的字段显示,或者在尝试提交表单之后显示。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 | |
- 第 69–70 行:一个正则表达式([Regex])和一个常量;
- 第 75–94 行:规则。[buildMap [ ... ]]:填充一个可修改的 [Map](通过 [put]);该函数返回一个不可修改的 [Map]。最后一条规则比较两个字段;
- 第 113 行:每次执行时都会重新计算错误,而不是从状态中清除:它们始终是最新的;
- 第 116 行:字段要显示的错误:只有在该字段被修改过时才显示;
- 第 118–122 行:提交会将所有字段标记为已触碰(显示所有错误),并且只有在没有错误时才会成功;
- 第 129–151 行:账户的一个字段。[update] 是一个生成修改后账户的函数([[ account.copy(firstName = it) ]]);[isError] 和 [supportingText] 在字段下方显示错误;[PasswordVisualTransformation] 遮蔽字符;对于已更新且有效的字段,显示一个绿色对勾([trailingIcon]);
- 第 183 行:[private]:只在这个文件中可见的组件。


注意:这种验证只是为用户提供的一种便利(即时响应,无需往返服务器)。它不保护任何东西:任何人都可以向服务器发送手工构造的请求(使用 [curl];见关于服务器的章节)。因此服务器总是会重新验证一切(见示例 25)。
3.8. 示例 08:能够自我验证的字段
[Flutter] 有自己的表单([Form]、[FormField]);[Compose] 则没有。所以我们自己用几行代码编写这个工具,使用持有 [Compose] 所观察状态的普通类(“状态持有者”):这是 [Compose] 中的标准做法。
- 第 23 行:[typealias]:函数类型的一个名称:规则接收值,如果值有效则返回 [null],否则返回错误消息;
- 第 26–30 行:规则工厂(返回函数的函数)。[?:] 即“Elvis”运算符:如果左边的值不为 [null] 则取左边的值,否则取右边的值;
- 第 32–56 行:一个字段:它的值和错误是 [Compose] 状态([mutableStateOf]),只能在类内部修改([private set])。字段会按需验证([validate()]),并且在用户修改过它之后,每次按键时都会验证;
- 第 61–64 行:表单将字段归并在一起([vararg]:任意数量的参数)。首先是 [map]:验证所有字段并显示所有错误;然后是 [all]:它们是否全部有效?
使用这些类重写的示例 07:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
- 第 48–77 行:表单字段及其规则,归并在一个类中;确认字段的规则会读取另一个字段([password.value]);
- 第 101 行:[remember [ AccountForm() ]]:该对象只创建一次,并在重组之后依然存在;
- 第 120 行:提交:[account.form.validate()] 验证所有内容,并判断是否可以提交;
- 第 140–152 行:显示一个字段:它的值、它的错误,以及 [after],它指定每次按键之后要做什么:当密码变化时,重新验证确认字段。


3.9. 示例 09:格式化值
在 [@Composable] 函数中,使用标准函数来格式化值。应用中使用的函数汇集在同一个文件中:
- 第 24–30 行:一个可选参数,带有默认值([part = Part.ALL]);[padStart(2, '0')]:得到“8:05”而不是“8:5”;
- 第 36–43 行:扩展:[Kotlin] 允许你为现有类型(此处是所有字符串)添加属性(和函数)。在函数体中,[this] 指代该字符串:["marie pelissier".capitalized] 得到“Marie Pelissier”。
对于日期、数字和金额,[Java] 的类([java.time]、[java.text])遵循每种语言的惯例:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | |
- 第 51–62 行:格式化器,在 [@Composable] 函数之外一次性创建(创建它们的开销比使用它们更大)。[FormatStyle.MEDIUM]、[FULL]……:“现成的”格式;[ofPattern]:一种模式;[apply [ ... ]] 配置刚刚创建的对象并返回它;
- 第 85–103 行:数组中的每一行都是一个(显示的代码,值)对,由 [to] 生成;
- 第 113 行:一个键值对,如同 [Map] 的一个条目,被“解包”:[for ((code, value) in rows)]。


注意 ["%.1f".format(Locale.ROOT, PRICE)]:如果没有“中立”的语言环境 [Locale.ROOT],[format] 会使用手机的语言,在法语下写成“1234,5”。这适用于显示用途,但不适用于发送给服务器的数据。