Skip to content

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 文件

// =========================================================================
// settings.gradle.kts - Gradle 项目的全局配置
// (由 Android Studio 生成;只修改了 rootProject.name)
// =========================================================================

// Gradle 查找插件的位置(Android 插件、Compose 插件等)
pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
}
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}
// Gradle 查找库的位置:google() 提供 AndroidX 和 Compose,
// mavenCentral() 提供 OkHttp、kotlinx.serialization、AndroidSVG
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "examples_kotlin"
// 只有一个模块:位于 app/ 文件夹中的应用
include(":app")
  • 第 7–17 行:[Gradle] 查找其插件的位置([Gradle] 的扩展:[Android] 插件、[Compose] 编译器等):Google 仓库和 Java 库的中央仓库([Maven Central]);
  • 第 25–29 行:[Gradle] 查找应用所用库的位置;
  • 第 3–11 行:项目名称及其唯一的模块,即位于 [app/] 文件夹中的应用。

3.1.3. 版本目录:gradle/libs.versions.toml

所有插件和库的版本都集中在一个 TOML 格式的文件中:

# =========================================================================
# gradle/libs.versions.toml - 项目的“版本目录”
# -------------------------------------------------------------------------
# 所有插件和库的版本,集中在同一个地方。
# build.gradle.kts 文件通过名称引用它们
# (libs.okhttp、libs.plugins.kotlin.compose 等)。它相当于
# Flutter 的 pubspec.yaml 中的 dependencies 部分。
# =========================================================================

[versions]
agp = "9.4.1"
kotlin = "2.2.10"
coreKtx = "1.17.0"
lifecycle = "2.9.4"
activityCompose = "1.11.0"
composeBom = "2026.02.01"
appcompat = "1.7.1"
navigation = "2.9.5"
datastore = "1.1.7"
okhttp = "4.12.0"
kotlinxSerializationJson = "1.9.0"
androidsvg = "1.4"
junit = "4.13.2"
junitVersion = "1.3.0"
espressoCore = "3.7.0"
testRunner = "1.7.0"

[libraries]
# 由 Android Studio 生成(“Empty Activity”模板)
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycle" }
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-compose-ui = { group = "androidx.compose.ui", name = "ui" }
androidx-compose-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
androidx-compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
androidx-compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
androidx-compose-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
androidx-test-runner = { group = "androidx.test", name = "runner", version.ref = "testRunner" }
# 为示例添加
# 基本的 Material 图标(Add、Delete、Search 等)
androidx-compose-material-icons-core = { group = "androidx.compose.material", name = "material-icons-core" }
# 从 Compose 角度看到的 Activity 生命周期(示例 13、20)
androidx-lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
# 在 @Composable 函数中使用 viewModel()(示例 20、24、25)
androidx-lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
# 应用自己的语言(示例 21、25)
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
# 路由器(示例 17、18)
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }
# 一个保存在设备上的小型键 -> 值字典(示例 20)
androidx-datastore-preferences = { group = "androidx.datastore", name = "datastore-preferences", version.ref = "datastore" }
# HTTP 客户端(示例 22 到 25)
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
# JSON(反)序列化(示例 17、18、22 到 25)
kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
# 绘制 SVG 图像(示例 03,示例 22 到 25 的验证码)
androidsvg = { group = "com.caverock", name = "androidsvg-aar", version.ref = "androidsvg" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
# 生成 @Serializable 类的(反)序列化代码
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
  • [[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 文件

应用本身的配置:

// =========================================================================
// app/build.gradle.kts - “app”模块的配置:包含 25 个示例的应用。
// 由 Android Studio 生成(“Empty Activity”模板),
// 然后补全(标有“added”的行)。
// =========================================================================
plugins {
    // Android 插件:编译 Kotlin 代码(Android 9 插件本身
    // 已包含对 Kotlin 的支持)并生成 .apk 文件
    alias(libs.plugins.android.application)
    // Compose 编译器:转换 @Composable 函数
    alias(libs.plugins.kotlin.compose)
    // 新增:kotlinx.serialization 插件(@Serializable 类)
    alias(libs.plugins.kotlin.serialization)
}

android {
    // 代码的基础“包”(R 类、BuildConfig 等)
    namespace = "fr.stahe.examples"
    // 用于编译的 Android API 版本
    compileSdk {
        version = release(37)
    }

    defaultConfig {
        // 应用在手机上的唯一标识符
        applicationId = "fr.stahe.examples"
        // 接受的最低 Android 版本:Android 8.0(API 26)
        minSdk = 26
        // 应用经过测试所针对的 Android 版本
        targetSdk = 37
        versionCode = 1
        versionName = "1.0"
        // 新增:JSON 服务器的地址(示例 22 到 25),可以在
        // 编译时更改:gradlew installDebug -Pserver=http://192.168.1.20:8080
        val server = providers.gradleProperty("server").getOrElse("http://localhost:8080")
        buildConfigField("String", "SERVER_URL", "\"$server\"")

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            optimization {
                enable = false
            }
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    buildFeatures {
        compose = true
        // 新增:BuildConfig 类(BuildConfig.SERVER_URL)
        buildConfig = true
    }
}

dependencies {
    // Compose 的“BOM”:所有 Compose 库的相互兼容版本,
    // 它们在下面声明时不带版本号
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.activity.compose)
    implementation(libs.androidx.compose.material3)
    implementation(libs.androidx.compose.ui)
    implementation(libs.androidx.compose.ui.graphics)
    implementation(libs.androidx.compose.ui.tooling.preview)
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.lifecycle.runtime.ktx)
    // 为示例添加
    implementation(libs.androidx.compose.material.icons.core)
    implementation(libs.androidx.lifecycle.runtime.compose)
    implementation(libs.androidx.lifecycle.viewmodel.compose)
    implementation(libs.androidx.appcompat)
    implementation(libs.androidx.navigation.compose)
    implementation(libs.androidx.datastore.preferences)
    implementation(libs.okhttp)
    implementation(libs.kotlinx.serialization.json)
    implementation(libs.androidsvg)
    // 测试:这里用于制作课程的截图(androidTest 文件夹)
    testImplementation(libs.junit)
    androidTestImplementation(platform(libs.androidx.compose.bom))
    androidTestImplementation(libs.androidx.compose.ui.test.junit4)
    androidTestImplementation(libs.androidx.espresso.core)
    androidTestImplementation(libs.androidx.junit)
    androidTestImplementation(libs.androidx.test.runner)
    debugImplementation(libs.androidx.compose.ui.test.manifest)
    debugImplementation(libs.androidx.compose.ui.tooling)
}
  • 第 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] 可以启动的屏幕:

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     AndroidManifest.xml - the "identity card" of the application
     ............................................................................
     Its permissions, its Application class, its activities (one per
     example, plus the menu).
     ===================================================================== -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- network access (examples 22 to 25): granted automatically, without
         asking the user -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- android:name: the Application class (ExamplesApplication.kt).
         android:usesCleartextTraffic="true": allows "cleartext" HTTP
         (http:// and not https://), blocked by default since Android 9: the
         JSON server of this course listens in plain HTTP.
         android:localeConfig: the languages of the application (example 21) -->
    <application
        android:name=".ExamplesApplication"
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:localeConfig="@xml/locales_config"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.Examples"
        android:usesCleartextTraffic="true"
        tools:targetApi="33">

        <!-- the menu: the activity launched by the application icon
             (the MAIN / LAUNCHER filter) -->
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- the examples. exported="false": only the application can
             open them (adb, however, always can).
             windowSoftInputMode="adjustResize": the keyboard shrinks the screen
             instead of hiding it -->
        <activity android:name=".ex01.Ex01Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex02.Ex02Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex03.Ex03Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex04.Ex04Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex05.Ex05Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex06.Ex06Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex07.Ex07Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex08.Ex08Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex09.Ex09Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex10.Ex10Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex11.Ex11Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex12.Ex12Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex13.Ex13Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex14.Ex14Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex15.Ex15Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex16.Ex16Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex19.Ex19Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex20.Ex20Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex21.Ex21Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex22.Ex22Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex23.Ex23Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex24.Ex24Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />
        <activity android:name=".ex25.Ex25Activity" android:exported="false" android:windowSoftInputMode="adjustResize" />

        <!-- examples 17 and 18: addresses app://examples/... and
             app://examples18/... ("deep links"), that another
             application (or adb) can open: a VIEW intent filter -->
        <activity android:name=".ex17.Ex17Activity" android:exported="true" android:windowSoftInputMode="adjustResize">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:scheme="app" android:host="examples" />
            </intent-filter>
        </activity>
        <activity android:name=".ex18.Ex18Activity" android:exported="true" android:windowSoftInputMode="adjustResize">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:scheme="app" android:host="examples18" />
            </intent-filter>
        </activity>

        <!-- example 21: before Android 13, it is AppCompat that stores the
             language chosen by the application (autoStoreLocales) -->
        <service
            android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
            android:enabled="false"
            android:exported="false">
            <meta-data
                android:name="autoStoreLocales"
                android:value="true" />
        </service>
    </application>

</manifest>
  • 第 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 的代码:

// =========================================================================
// ex01/Ex01Activity.kt - 第一个应用
// -------------------------------------------------------------------------
// Android 应用的一个屏幕就是一个 Activity:它是一个继承自
// ComponentActivity 的类,由系统在
// 应用启动时创建。使用 Jetpack Compose 时,Activity 几乎什么都不做:
// 它把自己的屏幕交给 @Composable 函数(setContent)。
// @Composable 函数通过调用其他 @Composable 函数来描述屏幕的一部分(文本、
// 按钮、列等):
// 它们构成一棵树。Compose 执行这些函数来构建
// 屏幕;当它们读取的某个数据(一个“状态”)发生变化时,Compose 会再次执行它们
// 这就是重组。我们从不亲自修改屏幕。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex01

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.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplesTheme
import java.time.LocalTime
import java.time.format.DateTimeFormatter

// “普通”数据,位于 @Composable 函数之外:它们永远不变
const val TITLE = "Welcome to Kotlin"
val languages = listOf("Kotlin", "Jetpack Compose", "Material Design")

// “12:05:09”:当前时间
fun currentTime(): String = LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm:ss"))

// Activity:屏幕的入口(在 AndroidManifest.xml 中声明)
class Ex01Activity : ComponentActivity() {
    // onCreate:Activity 创建时由 Android 调用
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 应用也会绘制到状态栏和导航栏下方
        enableEdgeToEdge()
        // setContent:Compose 接管屏幕,并在其中显示
        // 给定的 @Composable 函数,外面包裹着示例的主题
        setContent {
            ExamplesTheme {
                HomePage()
            }
        }
    }
}

// 一个 @Composable 函数:它的名称以大写字母开头,就像
// 类名一样(它是界面的一部分),并且不返回任何值(Unit)
@Composable
fun HomePage() {
    // 状态:被 Compose 观察的变量。修改它们会导致
    // 读取它们的函数重新执行(重组)。
    // rememberSaveable:该值在函数的前后两次执行之间得以保留
    // ……甚至当 Android 重建 Activity 时也是如此(屏幕
    // 旋转、切换语言)
    var counter by rememberSaveable { mutableIntStateOf(0) }
    var time by rememberSaveable { mutableStateOf(currentTime()) }

    // Scaffold:Material 屏幕的结构(顶部栏、内容等)
    Scaffold(
        topBar = { TopAppBar(title = { Text("Example 01 - a first application") }) },
    ) { insets ->
        // Column:子元素自上而下排列;使用 Scaffold 的内边距
        // (为顶部栏留出的空间),再额外加 16 dp
        Column(modifier = Modifier.padding(insets).padding(16.dp)) {
            Text(TITLE, style = MaterialTheme.typography.headlineSmall)
            Spacer(Modifier.height(12.dp))
            Text(
                "This screen is built by Jetpack Compose, from the activity " +
                    "Ex01Activity and the function HomePage.",
            )
            Spacer(Modifier.height(8.dp))
            // ${expression} 把表达式的值插入字符串
            Text("It is written in ${languages.joinToString(", ")} (${languages.size} technologies).")
            Spacer(Modifier.height(16.dp))
            // onClick:按下时调用的函数(这里是一个“lambda”)。
            // 我们修改状态;Compose 更新屏幕
            Button(onClick = {
                counter++
                time = currentTime()
            }) {
                Text("Click me")
            }
            Spacer(Modifier.height(16.dp))
            Text(
                "You clicked $counter times (last click: $time).",
                fontWeight = FontWeight.Bold,
                color = Color(0xFF087EA4),
            )
        }
    }
}
  • 第 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]:

// =========================================================================
// common/Theme.kt - 所有示例共用的主题
// -------------------------------------------------------------------------
// MaterialTheme:Material Design 3 的颜色、文本和形状,
// 放在其中的所有 Material 组件都会使用它们
// (按钮、字段、卡片等)。我们给它一组颜色(一个
// ColorScheme),浅色或深色,围绕靛蓝色构建。
// ExamplesTheme(dark = true):深色主题(参见示例 20)。
// =========================================================================
package fr.stahe.examples.common

import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.darkColorScheme
import androidx.compose.material3.lightColorScheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.graphics.Color

// 浅色主题的颜色:其余的使用 Material 3 的默认值
private val lightColors = lightColorScheme(
    primary = Color(0xFF4355B9),
    onPrimary = Color.White,
    primaryContainer = Color(0xFFDEE0FF),
    onPrimaryContainer = Color(0xFF00105C),
    secondaryContainer = Color(0xFFE0E1F9),
    onSecondaryContainer = Color(0xFF181A2C),
    surface = Color(0xFFFBF8FF),
    surfaceContainer = Color(0xFFEFEDF4),
    surfaceContainerLow = Color(0xFFF5F2FA),
)

// 深色主题的颜色
private val darkColors = darkColorScheme(
    primary = Color(0xFFBAC3FF),
    onPrimary = Color(0xFF08218A),
    primaryContainer = Color(0xFF293CA0),
    onPrimaryContainer = Color(0xFFDEE0FF),
    secondaryContainer = Color(0xFF434659),
    onSecondaryContainer = Color(0xFFE0E1F9),
)

// 一个“包裹”内容的 @Composable 函数:content
// 参数本身就是一个 @Composable 函数(参见示例 12)
@Composable
fun ExamplesTheme(dark: Boolean = false, content: @Composable () -> Unit) {
    MaterialTheme(
        colorScheme = if (dark) darkColors else lightColors,
        content = content,
    )
}
  • [lightColorScheme(...)]、[darkColorScheme(...)]:[Material 3] 的浅色和深色配色;未指定的颜色保留其默认值;
  • [ExamplesTheme(dark, content)]:一个 [@Composable] 函数,它接收……另一个 [@Composable] 函数作为其内容。这是组合的核心机制(见示例 12):[ExamplesTheme [ HomePage() ]] 以这个内容调用 [MaterialTheme]。

3.1.7. 执行

在 [Android Studio] 中,[Run] 按钮会启动应用:出现示例菜单;第一行打开示例 01。点击按钮两次之后:

Image

Image

旋转手机(或模拟器,使用其工具栏上的旋转按钮):Activity 被 [Android] 销毁后重新创建,但计数器保持不变,这要归功于 [rememberSaveable]。将 [rememberSaveable] 换成 [remember]:每次旋转后计数器都会重置为 0。这是与 [Flutter] 的一个关键区别,在 Flutter 中屏幕在旋转时会保持不变:而在 [Android] 中,当设备的设置(方向、语言、文字大小等)发生变化时,Activity 会被重新创建。

3.2. 示例 02:状态与计算值

一个简单的含增值税价格计算器,它区分状态(用户输入的内容)与由此得到的计算结果。在这个示例中,屏幕结构(顶部栏、可滚动的内容)在 [common/ExamplePage.kt] 中一次性定义好:

// =========================================================================
// common/ExamplePage.kt - 各示例屏幕的通用结构
// -------------------------------------------------------------------------
// 所有示例(从 02 开始)都有相同的屏幕结构:带标题的
// 顶部栏,然后是一列内容,如果内容超出屏幕高度,则可以滚动。
// 与其重写 25 次,不如
// 只写一次,写成一个以内容作为
// 参数的 @Composable 函数(参见示例 12):
//
//     ExamplePage("Example 02 - state") {
//         Text("...")          // 内容:一个接一个的组件
//         Button(...) { ... }
//     }
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.common

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ColumnScope
import androidx.compose.foundation.layout.RowScope
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.SnackbarHost
import androidx.compose.material3.SnackbarHostState
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

@Composable
fun ExamplePage(
    title: String,
    // 标题左侧的图标(默认没有)
    icon: @Composable () -> Unit = {},
    // 顶部栏右侧的按钮(默认没有)
    actions: @Composable RowScope.() -> Unit = {},
    // 短暂消息的区域(Snackbar,参见示例 16),可选
    messages: SnackbarHostState? = null,
    // 内容:一个 @Composable 函数,在 Column 内部调用
    content: @Composable ColumnScope.() -> Unit,
) {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(title, style = MaterialTheme.typography.titleMedium, maxLines = 2) },
                navigationIcon = icon,
                actions = actions,
            )
        },
        snackbarHost = { if (messages != null) SnackbarHost(messages) },
    ) { insets ->
        Column(
            modifier = Modifier
                // Scaffold 的内边距:位于顶部栏下方、手机导航栏
                // 上方
                .padding(insets)
                .consumeWindowInsets(insets)
                // 手机的键盘不会遮住屏幕的底部
                .imePadding()
                .fillMaxSize()
                // 如果列比屏幕高,则列可以滚动
                .verticalScroll(rememberScrollState())
                .padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(4.dp),
            content = content,
        )
    }
}
  • [content: @Composable ColumnScope.() -> Unit]:内容是在 [Column] 内部调用的 [@Composable] 函数(因此可以使用列专属的修饰符,例如 [weight]);
  • [verticalScroll(rememberScrollState())]:当列超出屏幕高度时可以滚动;[imePadding()]:手机键盘不会遮住屏幕底部;
  • 调用时使用尾随 lambda:[ExamplePage("title") [ Text(...) ; Button(...) ]]。

示例的代码:

// =========================================================================
// ex02/Ex02Activity.kt - 状态与计算值
// -------------------------------------------------------------------------
// 一个含增值税价格的小型计算器:
//   - 状态:mutableStateOf 变量;修改它们会重新执行
//     (重组)读取它们的函数,该函数用
//     新的值构建屏幕;
//   - 由状态计算得出的值不是状态:它是一个
//     简单的局部变量,在函数每次执行时重新计算。
//     它始终是最新的,无需同步;
//   - 依赖于状态的连续值的数据(总价的
//     历史记录)在状态变化的地方更新;
//   - 最近使用的应用列表中的应用标题
//     与屏幕的其余部分一样,跟随状态变化(TaskTitle)。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex02

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.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.material.icons.filled.KeyboardArrowDown
import androidx.compose.material3.Card
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.SegmentedButton
import androidx.compose.material3.SegmentedButtonDefaults
import androidx.compose.material3.SingleChoiceSegmentedButtonRow
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableDoubleStateOf
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.common.TaskTitle
import java.text.NumberFormat
import java.util.Locale

// 以欧元表示金额的格式化器,采用英语的写法(€1,234.50),参见示例 09
val euros: NumberFormat = NumberFormat.getCurrencyInstance(Locale.US).apply { currency = java.util.Currency.getInstance("EUR") }

// 提供的增值税率
val rates = listOf(5.5, 10.0, 20.0)

// “2,5”或“2.5” -> 2.5;不是数字的文本 -> 0
fun price(text: String): Double = text.replace(',', '.').toDoubleOrNull() ?: 0.0

// 含增值税的总价:一个纯函数(其结果只取决于它的参数)
fun totalInclVat(priceExclVat: Double, quantity: Int, vatRate: Double): Double = quantity * priceExclVat * (1 + vatRate / 100)

class Ex02Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { CalculatorPage() } }
    }
}

@Composable
fun CalculatorPage() {
    // 状态:用户输入或选择的内容
    var label by rememberSaveable { mutableStateOf("Pen") }
    var priceText by rememberSaveable { mutableStateOf("2.5") } // 字段的文本,保持输入时的样子
    var quantity by rememberSaveable { mutableIntStateOf(1) }
    var vatRate by rememberSaveable { mutableDoubleStateOf(20.0) }
    // 含增值税总价最近 5 次变化的历史记录:一个不可修改的
    // 列表,每次变化时都用新列表替换
    var history by rememberSaveable { mutableStateOf(listOf<String>()) }

    // 计算值:简单的局部变量,在函数每次
    // 执行时重新计算
    val priceExclVat = price(priceText)
    val totalExclVat = quantity * priceExclVat
    val vatAmount = totalExclVat * vatRate / 100
    val inclVat = totalExclVat + vatAmount

    // 状态的所有变化都经过这个局部函数:它
    // 记下变化前含增值税的总价,应用变化,
    // 并在总价改变时补充历史记录
    fun change(update: () -> Unit) {
        val old = inclVat
        update()
        // 状态变量已经有了它们的新值
        val newTotal = totalInclVat(price(priceText), quantity, vatRate)
        if (newTotal != old) {
            history = (listOf("${euros.format(old)} -> ${euros.format(newTotal)}") + history).take(5)
        }
    }

    // 应用的标题跟随状态变化,和其他一切一样
    TaskTitle("Incl. VAT: ${euros.format(inclVat)}")
    val totalStyle = MaterialTheme.typography.titleMedium.copy(fontWeight = FontWeight.Bold)

    ExamplePage("Example 02 - state") {
        Card {
            Column(Modifier.padding(16.dp)) {
                // 一个受控字段:它显示 value,并在每次按键时
                // 以新文本调用 onValueChange
                OutlinedTextField(
                    value = label,
                    // 更换商品会把数量重置为 1:这在
                    // 我们知道状态为何变化的地方完成
                    onValueChange = { newValue ->
                        change {
                            label = newValue
                            quantity = 1
                        }
                    },
                    label = { Text("Item") },
                    modifier = Modifier.fillMaxWidth(),
                )
                OutlinedTextField(
                    value = priceText,
                    onValueChange = { text -> change { priceText = text } },
                    label = { Text("Unit price excl. VAT") },
                    // 手机的数字键盘
                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Decimal),
                    modifier = Modifier.fillMaxWidth(),
                )
                Spacer(Modifier.height(12.dp))
                Row(verticalAlignment = Alignment.CenterVertically) {
                    // weight(1f):文本占据所有剩余的宽度
                    Text("Quantity (back to 1 if the item changes)", Modifier.weight(1f))
                    // enabled = false:按钮被禁用
                    IconButton(onClick = { change { quantity-- } }, enabled = quantity > 0) {
                        Icon(Icons.Default.KeyboardArrowDown, contentDescription = "minus")
                    }
                    Text("$quantity", style = totalStyle)
                    IconButton(onClick = { change { quantity++ } }) {
                        Icon(Icons.Default.Add, contentDescription = "plus")
                    }
                }
                Spacer(Modifier.height(8.dp))
                // 只有一个被选中的按钮:增值税率
                SingleChoiceSegmentedButtonRow(Modifier.fillMaxWidth()) {
                    rates.forEachIndexed { i, t ->
                        SegmentedButton(
                            selected = t == vatRate,
                            onClick = { change { vatRate = t } },
                            shape = SegmentedButtonDefaults.itemShape(index = i, count = rates.size),
                        ) {
                            Text("${t.toString().removeSuffix(".0")} %")
                        }
                    }
                }
                Spacer(Modifier.height(12.dp))
                OutlinedButton(onClick = {
                    change {
                        label = "Pen"
                        priceText = "2.5"
                        quantity = 1
                        vatRate = 20.0
                    }
                }) {
                    Text("Reset")
                }
            }
        }
        Card {
            Column(Modifier.padding(16.dp)) {
                Text("$quantity x $label", style = MaterialTheme.typography.titleLarge)
                HorizontalDivider(Modifier.padding(vertical = 8.dp))
                Line("Total excl. VAT", euros.format(totalExclVat))
                Line("VAT ($vatRate %)", euros.format(vatAmount))
                Line("Total incl. VAT", euros.format(inclVat), totalStyle)
            }
        }
        Card {
            Column(Modifier.padding(16.dp).fillMaxWidth()) {
                Text("History of the total incl. VAT", style = MaterialTheme.typography.titleSmall)
                // 历史记录中的每个元素对应一行文本(参见示例 03)
                for (line in history) {
                    Text("• $line")
                }
            }
        }
    }
}

// 一行“标签 ....... 金额”:一个构建
// 其他组件的 @Composable 函数。style:一个可选参数,带有默认值
@Composable
fun Line(label: String, amount: String, style: TextStyle = MaterialTheme.typography.bodyLarge) {
    Row(Modifier.padding(vertical = 4.dp)) {
        Text(label, Modifier.weight(1f), style = style)
        Text(amount, style = style)
    }
}
  • 第 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],有默认值)。

Image

Image

左图:点按 [+] 两次、选择 10% 并输入 3.2 之后;右图:该项已发生变化,数量已恢复为 1,历史记录记下了总价的每一次变化。

3.3. 示例 03:编写组件树

[Compose] 没有模板语言:对于条件和循环,我们直接在 [@Composable] 函数中使用 [Kotlin] 的语句。一个按输入内容过滤的医生列表:

// =========================================================================
// ex03/Ex03Activity.kt - 编写组件树
// -------------------------------------------------------------------------
// Compose 没有模板语言(没有 HTML,没有 XML):
// 屏幕用 Kotlin 编写,通过嵌套调用 @Composable
// 函数。而对于条件和循环,我们使用……
// 普通的 Kotlin 语句,直接写在函数中:
//   - if (condition) { Component() }     :只有当条件为真时
//                                          组件才存在;
//   - if (c) { A() } else { B() }        :二选一;
//   - for (x in list) { Component(x) }   :每个元素对应一个组件;
//   - when (value) { case -> ... }       :在多个值中取其一。
// @Composable 函数与其他函数没有区别:整个
// 语言都可以用来描述屏幕。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex03

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.Image
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.AddCircle
import androidx.compose.material.icons.filled.Face
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Search
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.SuggestionChipDefaults
import androidx.compose.material3.Switch
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.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.draw.alpha
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.R
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

// 一个“枚举”:专业的唯一可能取值
enum class Specialty { GENERAL_PRACTITIONER, PEDIATRICIAN, CARDIOLOGIST }

// 一个数据类:它的属性是 val,Doctor 对象永远不会
// 改变。Kotlin 会为它添加 equals、hashCode、toString 和 copy
data class Doctor(
    val id: Int,
    val title: String,
    val firstName: String,
    val lastName: String,
    val specialty: Specialty,
    val available: Boolean,
)

val doctors = listOf(
    Doctor(1, "Mme", "Marie", "PELISSIER", Specialty.GENERAL_PRACTITIONER, true),
    Doctor(2, "Mr", "Paul", "TATOU", Specialty.PEDIATRICIAN, false),
    Doctor(3, "Melle", "Sophie", "DUPONT", Specialty.CARDIOLOGIST, true),
)

// “根据某个值在多个值中取其一”:一个 when 表达式。
// 编译器会检查枚举中的所有情形是否都已处理
fun label(s: Specialty): String = when (s) {
    Specialty.GENERAL_PRACTITIONER -> "general practitioner"
    Specialty.PEDIATRICIAN -> "pediatrician"
    Specialty.CARDIOLOGIST -> "cardiologist"
}

// 一个图标及其颜色:一个值的“对”(Pair),用“to”书写
fun icon(s: Specialty): Pair<ImageVector, Color> = when (s) {
    Specialty.PEDIATRICIAN -> Icons.Default.Face to Color(0xFFFF9800)
    Specialty.CARDIOLOGIST -> Icons.Default.Favorite to Color.Red
    else -> Icons.Default.AddCircle to Color(0xFF009688) // else:所有其他情形
}

class Ex03Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { DoctorsPage() } }
    }
}

@Composable
fun DoctorsPage() {
    var filter by rememberSaveable { mutableStateOf("") } // 被搜索的文本
    var onlyAvailable by rememberSaveable { mutableStateOf(false) }
    var showHelp by rememberSaveable { mutableStateOf(true) }

    // 显示的列表:一个普通变量,每次执行时重新计算
    val text = filter.trim().lowercase()
    val displayed = doctors.filter { d ->
        (!onlyAvailable || d.available) &&
            "${d.firstName} ${d.lastName} ${label(d.specialty)}".lowercase().contains(text)
    }

    ExamplePage(
        title = "Example 03 - components",
        // 随应用一起发布的矢量图像(res/drawable/doctor.xml)
        icon = {
            Image(
                painter = painterResource(R.drawable.doctor),
                contentDescription = null,
                modifier = Modifier.padding(12.dp).size(28.dp),
            )
        },
    ) {
        OutlinedTextField(
            value = filter,
            onValueChange = { filter = it }, // it:lambda 唯一的参数
            placeholder = { Text("search...") },
            leadingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
            modifier = Modifier.fillMaxWidth(),
        )
        // 一个开关,带有它的标签
        ListItem(
            headlineContent = { Text("available only") },
            trailingContent = { Switch(checked = onlyAvailable, onCheckedChange = { onlyAvailable = it }) },
        )
        TextButton(onClick = { showHelp = !showHelp }) {
            Text(if (showHelp) "Hide help" else "Show help")
        }
        // 一个 if:只有当 showHelp 为 true 时,这个组件才存在
        if (showHelp) {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFE1F5FE))) {
                Text(
                    "Type a name or a specialty. Unavailable doctors are greyed out.",
                    Modifier.padding(12.dp),
                )
            }
        }
        // “三个代码块之一”:不带参数的 when,就像一连串的 if
        when {
            doctors.isEmpty() -> Text("No doctor.")
            displayed.isEmpty() -> Text("No doctor matches \"$filter\".", color = Color(0xFFFF5722))
            else -> Column {
                // 每位医生一个组件,带有他的序号:withIndex()
                for ((i, d) in displayed.withIndex()) {
                    DoctorRow(i + 1, d)
                }
            }
        }
        Spacer(Modifier.height(12.dp))
        // 一个计算得出的样式:文字大小取决于显示的医生数量
        Text(
            "${displayed.size} doctor(s) displayed - the size of this text depends on it.",
            fontSize = (12 + displayed.size * 2).sp,
        )
    }
}

// 列表的一行:一个带参数的 @Composable 函数
@Composable
fun DoctorRow(rank: Int, d: Doctor) {
    val (image, color) = icon(d.specialty) // 对这个“对”进行“解构”
    ListItem(
        // alpha:不可预约的医生会被置灰
        modifier = Modifier.alpha(if (d.available) 1f else 0.5f),
        leadingContent = { Text("$rank", style = MaterialTheme.typography.titleMedium) },
        headlineContent = { Text("${d.title} ${d.firstName} ${d.lastName}") },
        // FlowRow:类似 Row,但空间不足时会换到下一行
        supportingContent = {
            FlowRow(horizontalArrangement = Arrangement.spacedBy(6.dp)) {
                Icon(image, contentDescription = null, tint = color, modifier = Modifier.size(18.dp))
                Text(label(d.specialty))
            }
        },
        trailingContent = {
            SuggestionChip(
                onClick = {},
                label = { Text(if (d.available) "available" else "unavailable") },
                // 由条件表达式选择的颜色
                colors = SuggestionChipDefaults.suggestionChipColors(
                    containerColor = if (d.available) Color(0xFFC8E6C9) else Color(0xFFE0E0E0),
                ),
            )
        },
    )
}
  • 第 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]),其颜色取决于医生。

Image

Image

Image

3.4. 示例 04:事件

一个待办事项列表:可以添加事项、勾选事项并删除事项(使用按钮,或滑动该行,这是移动设备上典型的手势),此外还有一个对触摸敏感的区域。交互式组件接收函数作为参数,在发生某件事时调用:这些就是 [Compose] 的“事件”。

// =========================================================================
// ex04/Ex04Activity.kt - 响应用户的操作
// -------------------------------------------------------------------------
// 交互式组件接收在发生某件事时要调用的函数作为参数
// (“回调”,即 Kotlin 的 lambda):
//   - onClick = { ... }              :按下时调用(按钮);
//   - onClick = { remove(t) }        :lambda 传入它自己的参数;
//   - onValueChange、onCheckedChange :函数接收一个值(
//                                      文本、被勾选的复选框等);
//   - Modifier.pointerInput          :为任何组件
//                                      添加手势(单击、双击、
//                                      长按等);
//   - SwipeToDismissBox              :滑动一行
//                                      将其移除,这是典型的移动端手势。
// 要通过代码把焦点交给某个字段,我们为它关联一个
// FocusRequester。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex04

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Delete
import androidx.compose.material.icons.outlined.Delete
import androidx.compose.material3.Button
import androidx.compose.material3.Checkbox
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.SwipeToDismissBox
import androidx.compose.material3.Text
import androidx.compose.material3.rememberSwipeToDismissBoxState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.key
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
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.input.key.Key
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onPreviewKeyEvent
import androidx.compose.ui.input.pointer.pointerInput
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.text.style.TextDecoration
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 java.time.LocalTime
import java.time.format.DateTimeFormatter
import kotlin.math.roundToInt

// 一个任务:一个不可修改的数据类;要“勾选”它,我们
// 创建它的一个副本:task.copy(done = true)
data class Task(val id: Int, val label: String, val done: Boolean = false)

class Ex04Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { TasksPage() } }
    }
}

@Composable
fun TasksPage() {
    // 被 Compose 观察的列表:添加、删除或替换
    // 元素都会引起重组。(用 remember,而不是 rememberSaveable:
    // 如果 Activity 被重新创建,它们就会丢失,参见示例 20)
    val tasks = remember {
        mutableStateListOf(Task(1, "Install Android Studio", done = true), Task(2, "Read the chapter on events"))
    }
    val log = remember { mutableStateListOf<String>() }
    var input by remember { mutableStateOf("") }
    var nextId by remember { mutableIntStateOf(3) }
    // FocusRequester:通过代码把焦点(光标和
    // 手机的键盘)交给字段的一种方式
    val focus = remember { FocusRequester() }

    fun trace(message: String) {
        val time = LocalTime.now().format(DateTimeFormatter.ofPattern("HH:mm"))
        log.add(0, "$time $message")
    }

    // 由按钮和键盘的“OK”键(keyboardActions)调用
    fun add() {
        val label = input.trim()
        if (label.isEmpty()) {
            return
        }
        tasks.add(Task(nextId++, label))
        trace("added \"$label\"")
        input = ""
        // 焦点回到字段:可以输入下一个任务
        focus.requestFocus()
    }

    fun toggle(task: Task, done: Boolean) {
        // 我们用修改后的副本替换这个任务
        tasks[tasks.indexOf(task)] = task.copy(done = done)
        trace("\"${task.label}\": ${if (done) "done" else "to do"}")
    }

    fun remove(task: Task, how: String) {
        tasks.remove(task)
        trace("removed \"${task.label}\" ($how)")
    }

    // 屏幕密度:用于把像素转换为 dp
    val density = LocalDensity.current.density

    ExamplePage("Example 04 - events") {
        Row(verticalAlignment = Alignment.CenterVertically) {
            OutlinedTextField(
                value = input,
                onValueChange = { input = it },
                placeholder = { Text("new task (Escape to clear)") },
                singleLine = true,
                // 手机键盘的“OK”键会添加任务
                keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
                keyboardActions = KeyboardActions(onDone = { add() }),
                modifier = Modifier
                    .weight(1f)
                    .focusRequester(focus)
                    // 物理键盘(模拟器、平板):Escape 会清空字段
                    .onPreviewKeyEvent { event ->
                        if (event.key == Key.Escape) {
                            input = ""
                            true // 事件已被处理
                        } else {
                            false // 事件继续传递
                        }
                    },
            )
            Spacer(Modifier.width(8.dp))
            Button(onClick = { add() }) { Text("Add") }
        }
        Spacer(Modifier.height(12.dp))
        for (t in tasks) {
            // key(t.id):这一行的标识。每一行的状态(它的
            // 滑动)跟随它的任务,即使列表发生变化(参见课程)
            key(t.id) {
                TaskRow(
                    task = t,
                    onToggle = { done -> toggle(t, done) },
                    onRemove = { how -> remove(t, how) },
                )
            }
        }
        Spacer(Modifier.height(12.dp))
        // pointerInput:任何组件都可以变得对手势敏感
        Box(
            contentAlignment = Alignment.Center,
            modifier = Modifier
                .fillMaxWidth()
                .height(80.dp)
                .background(Color(0xFFE7F5FF), RoundedCornerShape(8.dp))
                .pointerInput(Unit) {
                    detectTapGestures(
                        // 按下的位置,相对于组件(以像素为单位)
                        onPress = { p -> trace("press at (${(p.x / density).roundToInt()}, ${(p.y / density).roundToInt()})") },
                        onDoubleTap = { trace("double tap") },
                        onLongPress = { trace("long press") },
                    )
                },
        ) {
            Text("Touch this area (tap, double tap, long press)")
        }
        Spacer(Modifier.height(16.dp))
        Text("Log", style = MaterialTheme.typography.titleSmall)
        for (line in log) {
            Text(line, fontSize = 12.sp)
        }
    }
}

// 列表的一行:任务,以及两个用于通知调用者的函数
@Composable
fun TaskRow(task: Task, onToggle: (Boolean) -> Unit, onRemove: (String) -> Unit) {
    // 该行的滑动状态(它在哪里?)
    val swipe = rememberSwipeToDismissBoxState()
    // SwipeToDismissBox:把该行向左滑动会将其移除
    SwipeToDismissBox(
        state = swipe,
        enableDismissFromStartToEnd = false,
        // onDismiss:当该行被完全滑到底时调用
        onDismiss = { onRemove("swipe") },
        // 该行被滑动时显示在它下方的内容
        backgroundContent = {
            Box(
                contentAlignment = Alignment.CenterEnd,
                modifier = Modifier.fillMaxSize().background(Color(0xFFFFCDD2)).padding(end = 16.dp),
            ) {
                Icon(Icons.Default.Delete, contentDescription = null)
            }
        },
    ) {
        ListItem(
            // 该框位于左侧,就像在任务列表中那样;它
            // 传递它的新值(一个 Boolean)
            leadingContent = { Checkbox(checked = task.done, onCheckedChange = onToggle) },
            headlineContent = {
                Text(
                    task.label,
                    style = if (task.done) {
                        TextStyle(textDecoration = TextDecoration.LineThrough, color = Color.Gray)
                    } else {
                        TextStyle.Default
                    },
                )
            },
            trailingContent = {
                IconButton(onClick = { onRemove("button") }) {
                    Icon(Icons.Outlined.Delete, contentDescription = "remove", tint = Color.Red)
                }
            },
        )
    }
}
  • 第 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] 被直接传给它。

Image

Image

Image

左图:已添加一个任务,勾选了另一个任务,并点按了该区域;中图:第一行向左滑动;右图:它已被删除,日志对此予以确认。

3.5. 示例 05:所有类型的字段

在 [Compose] 中,所有字段都是受控的:字段显示来自状态的值,并通过一个更新状态的函数通知每一次变化。这个函数传递什么取决于字段:

  • [OutlinedTextField]:新的文本([String]);
  • [Checkbox]、[Switch]:一个 [Boolean];
  • [RadioButton]、[FilterChip]:什么也不传,该项就是被选中的;
  • [Slider]:一个 [Float];
  • [DatePickerDialog]:一个日期,在确认时传递。

对于下拉列表,[Material 3] 并没有提供单一的、自成一体的组件:它在 [common/DropdownList.kt] 中一次性组装好:

// =========================================================================
// common/DropdownList.kt - 一个开箱即用的下拉列表
// -------------------------------------------------------------------------
// 用于 Compose 的 Material 3 没有单一整体的“下拉列表”
// 组件:它由三个元素组装而成:ExposedDropdownMenuBox、
// 一个只读文本字段,以及 ExposedDropdownMenu 菜单。我们
// 在这里一次性完成(示例 05 到 08、24、25):
//
//     DropdownList("Country", value = country, choices = listOf("fr", "be", "ch"),
//                  text = { countryNames[it] }, onChange = { country = it })
//
// 这个函数是泛型的(<T>):选项可以是字符串、
// 数字、医生等等。text 说明如何显示一个选项。如果 T 是“可空”类型(Int?),
// 则选项可以是 null(“请选择”)。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.common

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.ExposedDropdownMenuAnchorType
import androidx.compose.material3.ExposedDropdownMenuBox
import androidx.compose.material3.ExposedDropdownMenuDefaults
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
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

@Composable
fun <T> DropdownList(
    label: String,
    value: T,
    choices: List<T>,
    onChange: (T) -> Unit,
    modifier: Modifier = Modifier,
    text: (T) -> String = { it.toString() },
    // 字段下方的错误消息(参见示例 07 和 25)
    error: String? = null,
) {
    // 菜单是否展开?每个下拉列表特有的状态
    var open by remember { mutableStateOf(false) }
    ExposedDropdownMenuBox(expanded = open, onExpandedChange = { open = it }, modifier = modifier) {
        // 显示当前选项的字段;menuAnchor 使它成为菜单的
        // 锚点(触摸它即可打开菜单)
        OutlinedTextField(
            value = text(value),
            onValueChange = {},
            readOnly = true,
            singleLine = true,
            label = { Text(label) },
            trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = open) },
            isError = error != null,
            supportingText = if (error == null) null else { { Text(error) } },
            modifier = Modifier.menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable).fillMaxWidth(),
        )
        // 菜单:每个选项一行
        ExposedDropdownMenu(expanded = open, onDismissRequest = { open = false }) {
            for (c in choices) {
                DropdownMenuItem(
                    text = { Text(text(c)) },
                    onClick = {
                        onChange(c)
                        open = false
                    },
                )
            }
        }
    }
}
  • 第 36–44 行:[fun <T> DropdownList]:一个泛型函数:选项可以是字符串、数字、医生等等。[text] 指定如何显示一个选项(默认为其 [toString()]);
  • 第 47 行:每个列表特有的状态:菜单是否展开?
  • 第 48–49 行:[ExposedDropdownMenuBox] 将一个只读字段([readOnly = true],显示当前选项)与一个菜单关联起来;[menuAnchor] 使该字段成为菜单的锚点;
  • 第 63–68 行:每个选项对应一行菜单;按下它会通知调用者([onChange(c)])并关闭菜单。

示例的代码:

// =========================================================================
// ex05/Ex05Activity.kt - 所有类型的字段
// -------------------------------------------------------------------------
// 在 Compose 中,所有字段都是受控的:字段显示状态中的
// 值(value、checked、selected 等),并通过一个函数(onValueChange、onCheckedChange、onClick 等)
// 通知每一次变化,由该函数
// 更新状态。状态是唯一的数据来源:(通过代码)修改
// 状态就会修改字段。该函数传递什么
// 取决于字段:
//   - OutlinedTextField               -> 新的文本(String);
//   - Checkbox、Switch                -> Boolean;
//   - RadioButton                     -> 什么也不传:onClick 即是选择;
//   - DropdownList(common/)          -> 所选元素的值;
//   - FilterChip                      -> 什么也不传:onClick 切换小标签;
//   - Slider                          -> Float;
//   - DatePickerDialog(一个对话框)     -> 一个日期,在确认时传递。
// 一切都在手机上完成,无需服务器。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex05

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.selection.selectable
import androidx.compose.foundation.selection.selectableGroup
import androidx.compose.foundation.selection.toggleable
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Button
import androidx.compose.material3.Checkbox
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDialog
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FilterChip
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.RadioButton
import androidx.compose.material3.Slider
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableFloatStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import java.time.Instant
import java.time.LocalDate
import java.time.ZoneOffset

val titles = listOf("Mr", "Mme", "Melle")
val hobbies = listOf("sport", "music", "reading", "cinema")
val countries = mapOf("fr" to "France", "be" to "Belgium", "ch" to "Switzerland")
val languages = mapOf("fr" to "French", "en" to "English", "es" to "Spanish")

// 所有的值,汇集在一个对象中(即将发送给服务器的内容)。
// @Serializable:kotlinx.serialization 插件可以把它转换为 JSON
@Serializable
data class Model(
    val title: String,
    val name: String,
    val age: Int?,
    val presentation: String,
    val newsletter: Boolean,
    val hobbies: List<String>,
    val country: String,
    val languages: List<String>,
    val birthDate: String?,
    val satisfaction: Int,
)

// JSON 转换器:prettyPrint,带缩进的 JSON
val indentedJson = Json { prettyPrint = true }

class Ex05Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { FormPage() } }
    }
}

@Composable
fun FormPage() {
    // 表单的每个字段一个状态
    var title by rememberSaveable { mutableStateOf("Mme") }
    var name by rememberSaveable { mutableStateOf("") }
    var age by rememberSaveable { mutableStateOf("30") }
    var presentation by rememberSaveable { mutableStateOf("") } // 已验证的值
    var draft by rememberSaveable { mutableStateOf("") } // 正在输入的文本
    var newsletter by rememberSaveable { mutableStateOf(false) }
    var myHobbies by rememberSaveable { mutableStateOf(setOf("reading")) } // 一个集合:没有重复项
    var myCountry by rememberSaveable { mutableStateOf("fr") }
    var myLanguages by rememberSaveable { mutableStateOf(setOf<String>()) }
    var birthDate by rememberSaveable { mutableStateOf<LocalDate?>(null) } // null:尚未选择
    var satisfaction by rememberSaveable { mutableFloatStateOf(3f) }
    var sent by rememberSaveable { mutableStateOf<String?>(null) }
    var calendarOpen by rememberSaveable { mutableStateOf(false) }

    // 模型:由状态计算得出的值
    val model = Model(
        title = title,
        name = name.trim(),
        age = age.toIntOrNull(), // 如果字段为空则为 null
        presentation = presentation,
        newsletter = newsletter,
        hobbies = myHobbies.toList(),
        country = myCountry,
        languages = myLanguages.toList(),
        birthDate = birthDate?.toString(), // “2026-10-05”:RdvMedecins API 的日期格式
        satisfaction = satisfaction.toInt(),
    )
    val titleStyle = MaterialTheme.typography.titleSmall

    ExamplePage("Example 05 - controlled fields") {
        Text("Title", style = titleStyle)
        // selectableGroup:一组单选按钮(为了无障碍)
        Row(Modifier.selectableGroup(), verticalAlignment = Alignment.CenterVertically) {
            for (t in titles) {
                // selectable:整行(按钮 + 文本)都会对按下作出反应
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    modifier = Modifier.selectable(selected = title == t, onClick = { title = t }, role = Role.RadioButton),
                ) {
                    RadioButton(selected = title == t, onClick = null)
                    Text(t)
                    Spacer(Modifier.width(12.dp))
                }
            }
        }
        Row {
            OutlinedTextField(value = name, onValueChange = { name = it }, label = { Text("Name") }, modifier = Modifier.weight(2f))
            Spacer(Modifier.width(12.dp))
            OutlinedTextField(
                value = age,
                onValueChange = { age = it },
                label = { Text("Age") },
                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
                modifier = Modifier.weight(1f),
            )
        }
        // onFocusChanged:在字段获得或失去焦点时通知。
        // 只有在离开字段时,才会把展示内容复制到状态中
        OutlinedTextField(
            value = draft,
            onValueChange = { draft = it },
            label = { Text("Presentation (updated when leaving the field)") },
            minLines = 2,
            modifier = Modifier.fillMaxWidth().onFocusChanged { state ->
                if (!state.isFocused) presentation = draft
            },
        )
        // 单个复选框:true / false。toggleable:整行都会作出反应
        ListItem(
            modifier = Modifier.toggleable(value = newsletter, onValueChange = { newsletter = it }, role = Role.Checkbox),
            leadingContent = { Checkbox(checked = newsletter, onCheckedChange = null) },
            headlineContent = { Text("Receive the newsletter") },
        )
        Text("Hobbies", style = titleStyle)
        // 同一个集合对应多个小标签:值被添加或移除
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            for (h in hobbies) {
                FilterChip(
                    selected = h in myHobbies,
                    onClick = { myHobbies = if (h in myHobbies) myHobbies - h else myHobbies + h },
                    label = { Text(h) },
                )
            }
        }
        // 一个下拉列表:value 说明选中了哪个元素
        DropdownList(
            label = "Country",
            value = myCountry,
            choices = countries.keys.toList(),
            text = { code -> countries.getValue(code) },
            onChange = { myCountry = it },
            modifier = Modifier.width(220.dp),
        )
        Text("Spoken languages", style = titleStyle)
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            for ((code, label) in languages) {
                FilterChip(
                    selected = code in myLanguages,
                    onClick = { myLanguages = if (code in myLanguages) myLanguages - code else myLanguages + code },
                    label = { Text(label) },
                )
            }
        }
        Row(verticalAlignment = Alignment.CenterVertically) {
            Text("Satisfaction: ${satisfaction.toInt()} / 5", style = titleStyle)
            // 一个从 1 到 5 的滑块:3 个中间档位(2、3、4)
            Slider(
                value = satisfaction,
                onValueChange = { satisfaction = it },
                valueRange = 1f..5f,
                steps = 3,
                modifier = Modifier.weight(1f).padding(start = 8.dp),
            )
        }
        ListItem(
            leadingContent = { Icon(Icons.Default.DateRange, contentDescription = null) },
            headlineContent = { Text("Date of birth") },
            supportingContent = { Text(birthDate?.toString() ?: "not chosen") },
            trailingContent = { OutlinedButton(onClick = { calendarOpen = true }) { Text("Choose") } },
        )
        // FlowRow:在窄屏上,按钮会换到下一行
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            Button(onClick = { sent = Json.encodeToString(Model.serializer(), model) }) { Text("Send") }
            // 由代码修改的状态:字段随之变化
            OutlinedButton(onClick = {
                title = "Mr"
                name = "MARTIN"
                age = "42"
                myHobbies = setOf("sport", "cinema")
                myCountry = "be"
            }) { Text("Fill in by code") }
        }
        Spacer(Modifier.height(8.dp))
        Text("The model, live", style = titleStyle)
        Text(
            indentedJson.encodeToString(Model.serializer(), model),
            fontFamily = FontFamily.Monospace,
            fontSize = 12.sp,
            modifier = Modifier.fillMaxWidth().background(Color(0xFFF5F5F5)).padding(8.dp),
        )
        // 只有在提交之后才存在的代码块;?.let:只有当 sent 不为 null 时
        sent?.let { json ->
            Text("Last submission", style = titleStyle)
            Text(
                json,
                fontFamily = FontFamily.Monospace,
                fontSize = 12.sp,
                modifier = Modifier.fillMaxWidth().background(Color(0xFFE8F5E9)).padding(8.dp),
            )
        }
    }

    // 日历对话框:只有当 calendarOpen 为 true 时才存在
    if (calendarOpen) {
        // 日历的状态:选中的日期,以毫秒表示(UTC)
        val calendarState = rememberDatePickerState(
            initialSelectedDateMillis = (birthDate ?: LocalDate.of(2000, 1, 1)).atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli(),
        )
        DatePickerDialog(
            onDismissRequest = { calendarOpen = false },
            confirmButton = {
                TextButton(onClick = {
                    calendarState.selectedDateMillis?.let { ms ->
                        birthDate = Instant.ofEpochMilli(ms).atZone(ZoneOffset.UTC).toLocalDate()
                    }
                    calendarOpen = false
                }) { Text("OK") }
            },
            dismissButton = { TextButton(onClick = { calendarOpen = false }) { Text("Cancel") } },
        ) {
            DatePicker(state = calendarState)
        }
    }
}
  • 第 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])可以双向转换。

Image

Image

Image

日历([DatePickerDialog])是英文的:[Material 3] 会遵循应用的语言(见示例 21)。

3.6. 示例 06:表单、对象、reducer

示例 05 中每个字段有一个状态变量。对于真正的表单,我们更倾向于用一个包含所有值的对象,并在一个纯函数,即 REDUCER 中描述它的各种变化:[reducer(currentState, action) -> newState]。屏幕不再修改状态:它只报告发生了什么(“LASTNAME 字段现在的值为‘Dupont’”“LASTNAME 字段已被离开”),由 reducer 据此推导出新的状态。

// =========================================================================
// ex06/Ex06Activity.kt - 表单、对象、reducer
// -------------------------------------------------------------------------
// 示例 05 为表单的每个字段使用一个状态变量。对于
// 真正的表单,我们更倾向于使用一个包含所有值的对象,即
// 模型(这里是一个 Profile 对象,不可修改),并在
// 一个函数,即 REDUCER 中描述它的各种变化:
//
//     reducer(currentState, action) -> newState
//
// 屏幕不再修改状态:它用一个
// ProfileAction 对象(Update(Field.LASTNAME, "Dupont")、Leave(Field.LASTNAME) 等)描述发生了什么,
// 由 reducer 据此推导出新的状态。所有逻辑都集中在
// 一处,位于一个纯函数中(相同的输入,相同的输出,没有副
// 作用),易于测试。
// Kotlin 非常适合这样做:一个“sealed”接口列出所有可能的
// 动作,而对动作使用的 when 会由编译器检查(遗漏
// 某个情形就是错误)。
//
// 状态还为每个字段记录它是否被“触碰”过(至少
// 离开过一次);由此我们推导出它是否“已修改”(其值与
// 初始值不同)以及它是否被禁用。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex06

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.selection.selectable
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.RadioButton
import androidx.compose.material3.Slider
import androidx.compose.material3.Switch
import androidx.compose.material3.Text
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.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.JsonObject

// 表单中每个字段的名称
enum class Field { TITLE, FIRSTNAME, LASTNAME, AGE, NEWSLETTER, EMAIL, COUNTRY, PRESENTATION }

// 表单的数据:一个不可修改的对象(所有属性都是 val)。要
// “修改”它,我们创建它的一个副本:profile.copy(lastName = "DUPONT")。
// copy 函数由 Kotlin 为任何“data”类自动生成
data class Profile(
    val title: String,
    val firstName: String,
    val lastName: String,
    val age: Int,
    val newsletter: Boolean,
    val email: String,
    val country: String,
    val presentation: String,
) {
    // 某个字段的值,由其名称指定
    fun value(f: Field): Any = when (f) {
        Field.TITLE -> title
        Field.FIRSTNAME -> firstName
        Field.LASTNAME -> lastName
        Field.AGE -> age
        Field.NEWSLETTER -> newsletter
        Field.EMAIL -> email
        Field.COUNTRY -> country
        Field.PRESENTATION -> presentation
    }

    // 一个副本,其中由名称指定的一个字段有了新的值
    fun withValue(f: Field, v: Any): Profile = when (f) {
        Field.TITLE -> copy(title = v as String)
        Field.FIRSTNAME -> copy(firstName = v as String)
        Field.LASTNAME -> copy(lastName = v as String)
        Field.AGE -> copy(age = v as Int)
        Field.NEWSLETTER -> copy(newsletter = v as Boolean)
        Field.EMAIL -> copy(email = v as String)
        Field.COUNTRY -> copy(country = v as String)
        Field.PRESENTATION -> copy(presentation = v as String)
    }

    // profile 的 JSON 对象:表单的每个字段对应一个 JSON 字段
    fun toJson(): JsonObject = JsonObject(
        Field.entries.associate { f ->
            val v = value(f)
            f.name.lowercase() to when (v) {
                is Int -> JsonPrimitive(v) // “is”:类型测试;此后 v 就是一个 Int
                is Boolean -> JsonPrimitive(v)
                else -> JsonPrimitive(v.toString())
            }
        },
    )
}

val initial = Profile(
    title = "Mme",
    firstName = "Marie",
    lastName = "PELISSIER",
    age = 30,
    newsletter = false,
    email = "",
    country = "fr",
    presentation = "",
)

// 完整的状态:各个值,以及已经被离开的字段
data class State(val values: Profile, val touched: Set<Field>)

// 可能的动作。“sealed”:除了这里
// 声明的以外没有其他动作,编译器知道这一点
sealed interface ProfileAction {
    data class Update(val field: Field, val value: Any) : ProfileAction
    data class Leave(val field: Field) : ProfileAction
    data object Uppercase : ProfileAction // 一个唯一的对象:该动作不带数据
    data object Reset : ProfileAction
}

// reducer:它绝不修改收到的状态,而是返回一个新状态。
// 在 when 的每个分支中,action 具有该分支的类型(“智能转换”):
// 对于 Update,可以访问 action.field
fun reducer(state: State, action: ProfileAction): State = when (action) {
    is ProfileAction.Update -> state.copy(values = state.values.withValue(action.field, action.value))
    is ProfileAction.Leave -> state.copy(touched = state.touched + action.field)
    ProfileAction.Uppercase -> state.copy(
        values = state.values.copy(firstName = state.values.firstName.uppercase(), lastName = state.values.lastName.uppercase()),
    )
    ProfileAction.Reset -> State(initial, emptySet())
}

val titles = listOf("Mr", "Mme", "Melle")
val trackedFields = listOf(Field.FIRSTNAME, Field.LASTNAME, Field.AGE, Field.EMAIL)
val countryNames = mapOf("fr" to "France", "be" to "Belgium", "ch" to "Switzerland")
val indentedJson = Json { prettyPrint = true }

class Ex06Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { ProfilePage() } }
    }
}

@Composable
fun ProfilePage() {
    var state by remember { mutableStateOf(State(initial, emptySet())) }

    // 修改状态的唯一方式:描述发生了什么
    fun dispatch(action: ProfileAction) {
        state = reducer(state, action)
    }

    val v = state.values
    // 由状态推导出的值
    fun modified(f: Field) = v.value(f) != initial.value(f)
    fun disabled(f: Field) = f == Field.EMAIL && !v.newsletter // 电子邮件需要订阅新闻通讯
    val formModified = Field.entries.any { modified(it) }
    val titleStyle = MaterialTheme.typography.titleSmall

    // 一个绑定到模型的文本字段:一个局部的 @Composable 函数
    @Composable
    fun TextField(field: Field, label: String, modifier: Modifier = Modifier, lines: Int = 1) {
        // 该字段是否已经获得过焦点?(每个字段各自的状态)
        var hadFocus by remember { mutableStateOf(false) }
        OutlinedTextField(
            value = v.value(field) as String,
            onValueChange = { text -> dispatch(ProfileAction.Update(field, text)) },
            label = { Text(label) },
            enabled = !disabled(field),
            minLines = lines,
            // 当字段在获得焦点之后又失去焦点时,即被视为已离开
            modifier = modifier.onFocusChanged { f ->
                if (f.isFocused) {
                    hadFocus = true
                } else if (hadFocus) {
                    dispatch(ProfileAction.Leave(field))
                }
            },
        )
    }

    ExamplePage("Example 06 - a reducer") {
        Row(verticalAlignment = Alignment.CenterVertically) {
            for (t in titles) {
                Row(
                    verticalAlignment = Alignment.CenterVertically,
                    modifier = Modifier.selectable(selected = v.title == t, onClick = { dispatch(ProfileAction.Update(Field.TITLE, t)) }),
                ) {
                    RadioButton(selected = v.title == t, onClick = null)
                    Text(t)
                    Spacer(Modifier.width(12.dp))
                }
            }
        }
        Row {
            TextField(Field.FIRSTNAME, "First name", Modifier.weight(1f))
            Spacer(Modifier.width(12.dp))
            TextField(Field.LASTNAME, "Last name", Modifier.weight(1f))
        }
        Row(verticalAlignment = Alignment.CenterVertically) {
            Text("Age: ${v.age}", style = titleStyle)
            Slider(
                value = v.age.toFloat(),
                onValueChange = { a -> dispatch(ProfileAction.Update(Field.AGE, a.toInt())) },
                valueRange = 0f..120f,
                steps = 119,
                // 滑块被松开:该字段已被“离开”
                onValueChangeFinished = { dispatch(ProfileAction.Leave(Field.AGE)) },
                modifier = Modifier.weight(1f).padding(start = 8.dp),
            )
        }
        ListItem(
            headlineContent = { Text("Receive the newsletter") },
            trailingContent = {
                Switch(checked = v.newsletter, onCheckedChange = { yes -> dispatch(ProfileAction.Update(Field.NEWSLETTER, yes)) })
            },
        )
        TextField(Field.EMAIL, "E-mail (if newsletter)", Modifier.fillMaxWidth())
        DropdownList(
            label = "Country",
            value = v.country,
            choices = countryNames.keys.toList(),
            text = { countryNames.getValue(it) },
            onChange = { c -> dispatch(ProfileAction.Update(Field.COUNTRY, c)) },
            modifier = Modifier.width(220.dp),
        )
        TextField(Field.PRESENTATION, "About you", Modifier.fillMaxWidth(), lines = 2)
        Spacer(Modifier.height(8.dp))
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            OutlinedButton(onClick = { dispatch(ProfileAction.Uppercase) }) { Text("Name in uppercase") }
            OutlinedButton(onClick = { dispatch(ProfileAction.Reset) }) { Text("Reset") }
        }
        Spacer(Modifier.height(8.dp))
        Text("The model, live", style = titleStyle)
        Text(
            indentedJson.encodeToString(JsonObject.serializer(), v.toJson()),
            fontFamily = FontFamily.Monospace,
            fontSize = 12.sp,
            modifier = Modifier.fillMaxWidth().background(Color(0xFFF5F5F5)).padding(8.dp),
        )
        Spacer(Modifier.height(8.dp))
        Text("The state of the fields", style = titleStyle)
        // 一个小表格:每行一个 Row,各列宽度相同(weight)
        val headers = listOf("field", "touched", "modified", "disabled")
        Row { for (h in headers) Text(h, Modifier.weight(1f), fontWeight = FontWeight.Bold) }
        HorizontalDivider()
        for (f in trackedFields) {
            Row {
                Text(f.name.lowercase(), Modifier.weight(1f))
                Text("${f in state.touched}", Modifier.weight(1f))
                Text("${modified(f)}", Modifier.weight(1f))
                Text("${disabled(f)}", Modifier.weight(1f))
            }
        }
        Spacer(Modifier.height(8.dp))
        // 带有多种样式的文本:buildAnnotatedString
        Text(
            buildAnnotatedString {
                append("form modified: ")
                withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append("$formModified") }
            },
        )
    }
}
  • 第 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]。

Image

Image

reducer 是一个普通函数:无需屏幕,用一个简单的单元测试就可以测试它([assertEquals(expected, reducer(state, action))])。

3.7. 示例 07:手动验证表单

RdvMedecins 应用的“创建账户”表单,规则与服务器相同。一个纯函数 [validate(account)] 返回错误;这些错误只对已经被离开的字段显示,或者在尝试提交表单之后显示。

// =========================================================================
// ex07/Ex07Activity.kt - 手动验证表单
// -------------------------------------------------------------------------
// 一个纯函数 validate(account) 返回各字段的错误;我们
// 在 @Composable 函数每次执行时调用它:因此错误
// 始终是最新的。
// 我们不会立即显示它们(一个满是红色的空表单
// 令人不快):只对已经离开(“触碰”过)的字段显示。提交
// 会把所有字段标记为已触碰,然后只有在表单
// 有效时才会执行操作。当给 OutlinedTextField 传入 isError = true 和一个 supportingText 时,
// 它会在字段下方显示错误。
//
// 规则与 RdvMedecins 服务器相同(“创建账户”表单)。
// 警告:这种验证只是为用户提供的一种便利(
// 即时响应,无需往返服务器)。它不保护
// 任何东西:任何人都可以向服务器发送一个手工构造的
// 请求(curl 等)。因此服务器总是会重新验证一切(参见示例 25)。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex07

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.CheckCircle
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
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.focus.onFocusChanged
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme

enum class Field { TITLE, FIRSTNAME, LASTNAME, LOGIN, PASSWORD, CONFIRMATION }

// 用户输入的账户,保持输入时的样子
data class Account(
    val title: String,
    val firstName: String,
    val lastName: String,
    val login: String,
    val password: String,
    val confirmation: String,
)

val titles = listOf("Mr", "Mme", "Melle")
val loginFormat = Regex("^[a-z0-9._-]{1,30}$")
const val PASSWORD_MIN = 6

// 规则:一个纯函数,只依赖于它的参数。它
// 为每个出错的字段返回其消息。buildMap:我们填充
// 一个可修改的 Map,函数返回一个不可修改的 Map
fun validate(a: Account): Map<Field, String> = buildMap {
    if (a.title !in titles) put(Field.TITLE, "Choose a title from the list.")
    when {
        a.firstName.isBlank() -> put(Field.FIRSTNAME, "The first name is required.")
        a.firstName.length > 20 -> put(Field.FIRSTNAME, "The first name must not exceed 20 characters.")
    }
    when {
        a.lastName.isBlank() -> put(Field.LASTNAME, "The last name is required.")
        a.lastName.length > 20 -> put(Field.LASTNAME, "The last name must not exceed 20 characters.")
    }
    when {
        a.login.isEmpty() -> put(Field.LOGIN, "The login is required.")
        !loginFormat.matches(a.login) -> put(Field.LOGIN, "Unaccented lower-case letters, digits, dot, hyphen, underscore.")
    }
    when {
        a.password.isEmpty() -> put(Field.PASSWORD, "The password is required.")
        a.password.length < PASSWORD_MIN -> put(Field.PASSWORD, "At least $PASSWORD_MIN characters.")
    }
    // 一条比较两个字段的规则
    if (a.confirmation != a.password) put(Field.CONFIRMATION, "The confirmation does not match the password.")
}

class Ex07Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { AccountPage() } }
    }
}

@Composable
fun AccountPage() {
    var account by remember { mutableStateOf(Account("Mr", "", "", "", "", "")) }
    var touched by remember { mutableStateOf(setOf<Field>()) }
    var submitAttempted by remember { mutableStateOf(false) }
    var success by remember { mutableStateOf(false) }

    // 错误:每次执行时重新计算,绝不存放在状态中
    val errors = validate(account)

    // 字段要显示的错误:只有在它被触碰过时才显示
    fun error(f: Field): String? = if (f in touched) errors[f] else null

    fun send() {
        submitAttempted = true
        touched = Field.entries.toSet() // 所有错误都会出现在
        // 这里,账户会被发送给服务器(参见示例 25)
        success = errors.isEmpty()
    }

    // 一个文本字段:标签、错误,以及在字段被触碰且有效时显示的绿色对勾。
    // value:字段的值;update:构建
    // 修改后账户的函数
    @Composable
    fun AccountField(f: Field, label: String, value: String, update: (String) -> Account, secret: Boolean = false) {
        var hadFocus by remember { mutableStateOf(false) }
        val message = error(f)
        OutlinedTextField(
            value = value,
            onValueChange = { text ->
                account = update(text)
                success = false
            },
            label = { Text(label) },
            singleLine = true,
            isError = message != null,
            supportingText = message?.let { m -> { Text(m) } },
            // 密码的字符被隐藏
            visualTransformation = if (secret) PasswordVisualTransformation() else VisualTransformation.None,
            trailingIcon = if (f in touched && message == null) {
                { Icon(Icons.Default.CheckCircle, contentDescription = null, tint = Color(0xFF2E7D32)) }
            } else {
                null
            },
            // 被离开的字段(在获得过焦点之后)变为“已触碰”
            modifier = Modifier.fillMaxWidth().onFocusChanged { fs ->
                if (fs.isFocused) hadFocus = true else if (hadFocus) touched = touched + f
            },
        )
    }

    ExamplePage("Example 07 - validation") {
        DropdownList(
            label = "Title",
            value = account.title,
            choices = titles,
            onChange = { t -> account = account.copy(title = t) },
            modifier = Modifier.width(200.dp),
        )
        AccountField(Field.FIRSTNAME, "First name", account.firstName, { account.copy(firstName = it) })
        AccountField(Field.LASTNAME, "Last name", account.lastName, { account.copy(lastName = it) })
        AccountField(Field.LOGIN, "Login", account.login, { account.copy(login = it) })
        AccountField(Field.PASSWORD, "Password", account.password, { account.copy(password = it) }, secret = true)
        AccountField(Field.CONFIRMATION, "Confirmation", account.confirmation, { account.copy(confirmation = it) }, secret = true)
        Spacer(Modifier.height(16.dp))
        Button(onClick = { send() }) { Text("Create the account") }
        Spacer(Modifier.height(12.dp))
        if (submitAttempted && errors.isNotEmpty()) {
            Message("The form contains ${errors.size} error(s).", Color(0xFFFFEBEE))
        }
        if (success) {
            Message("Valid form: it could be sent to the server.", Color(0xFFE8F5E9))
        }
    }
}

// 一个此文件私有的小组件:彩色背景上的一条消息
@Composable
private fun Message(text: String, color: Color) {
    Text(text, Modifier.fillMaxWidth().background(color, RoundedCornerShape(8.dp)).padding(12.dp))
}
  • 第 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]:只在这个文件中可见的组件。

Image

Image

注意:这种验证只是为用户提供的一种便利(即时响应,无需往返服务器)。它不保护任何东西:任何人都可以向服务器发送手工构造的请求(使用 [curl];见关于服务器的章节)。因此服务器总是会重新验证一切(见示例 25)。

3.8. 示例 08:能够自我验证的字段

[Flutter] 有自己的表单([Form]、[FormField]);[Compose] 则没有。所以我们自己用几行代码编写这个工具,使用持有 [Compose] 所观察状态的普通类(“状态持有者”):这是 [Compose] 中的标准做法。

// =========================================================================
// ex08/Form.kt - 能够自我验证的字段
// -------------------------------------------------------------------------
// Compose 不提供表单工具(没有相当于 Flutter 的 Form
// 或 Angular 表单的东西):我们自己用
// 几行代码来编写,使用持有 Compose 所观察的
// 状态的普通类(“状态持有者”):
//   - 规则是一个函数:(value) -> 如果值没问题则返回 null,
//     否则返回错误消息;
//   - FormField 保存它的值和错误,并能自我验证:
//     先是按需验证(validate()),然后在用户
//     修改过它之后,每次按键时都验证;
//   - Form 把字段归并在一起:validate() 验证所有字段,
//     显示它们的错误,如果一切正常则返回 true。
// =========================================================================
package fr.stahe.examples.ex08

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue

// typealias:为函数类型起一个更有意义的名称
typealias Rule = (String) -> String?

// 规则工厂:每个工厂返回一个验证函数
fun required(message: String): Rule = { v -> if (v.isBlank()) message else null }

// 一条补全另一条规则的规则:“?:”(Elvis 运算符)在 other 的结果
// 不为 null 时返回它,否则返回其余部分的结果
fun maximum(max: Int, other: Rule): Rule = { v -> other(v) ?: if (v.length > max) "$max characters at most." else null }

class FormField(initialValue: String = "", private val rule: Rule = { null }) {
    // 字段的状态:被 Compose 观察,只能在这里修改(private set)
    var value by mutableStateOf(initialValue)
        private set
    var error by mutableStateOf<String?>(null)
        private set

    // 用户是否已经修改过该字段?
    private var modified = false

    // 一次按键:用户一旦修改过字段,它就会自我验证
    fun change(newValue: String) {
        value = newValue
        modified = true
        error = rule(value)
    }

    fun validate(): Boolean {
        error = rule(value)
        return error == null
    }

    // 重新验证,仅当用户已经修改过该字段时
    fun revalidate() {
        if (modified) validate()
    }
}

// vararg:任意数量的字段,Form(firstName, lastName, login...)
class Form(private vararg val fields: FormField) {
    // 先 map(验证所有字段并显示它们的错误),
    // 再 all(它们是否都没问题?)
    fun validate(): Boolean = fields.map { it.validate() }.all { it }
}
  • 第 23 行:[typealias]:函数类型的一个名称:规则接收值,如果值有效则返回 [null],否则返回错误消息;
  • 第 26–30 行:规则工厂(返回函数的函数)。[?:] 即“Elvis”运算符:如果左边的值不为 [null] 则取左边的值,否则取右边的值;
  • 第 32–56 行:一个字段:它的值和错误是 [Compose] 状态([mutableStateOf]),只能在类内部修改([private set])。字段会按需验证([validate()]),并且在用户修改过它之后,每次按键时都会验证;
  • 第 61–64 行:表单将字段归并在一起([vararg]:任意数量的参数)。首先是 [map]:验证所有字段并显示所有错误;然后是 [all]:它们是否全部有效?

使用这些类重写的示例 07:

// =========================================================================
// ex08/Ex08Activity.kt - 一个可复用的表单
// -------------------------------------------------------------------------
// 示例 07 的表单,使用 Form.kt 的类编写:
// 规则附加在字段上,屏幕只需显示
// 每个字段,并在提交时调用 form.validate()。
// 这些字段存放在一个类 AccountForm 中,该类只创建一次
// (remember):它在重组之后依然存在。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex08

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
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.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.input.VisualTransformation
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.DropdownList
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive

val titles = listOf("Mr", "Mme", "Melle")

// 表单的字段及其规则
class AccountForm {
    var title by mutableStateOf("Mr")
    val firstName = FormField(rule = maximum(20, required("The first name is required.")))
    val lastName = FormField(rule = maximum(20, required("The last name is required.")))

    // 直接写出的规则:一个 lambda
    val login = FormField(
        rule = { v ->
            when {
                v.isEmpty() -> "The login is required."
                !Regex("^[a-z0-9._-]{1,30}$").matches(v) -> "Unaccented lower-case letters, digits, dot, hyphen, underscore."
                else -> null
            }
        },
    )
    val password = FormField(
        rule = { v ->
            when {
                v.isEmpty() -> "The password is required."
                v.length < 6 -> "At least 6 characters."
                else -> null
            }
        },
    )

    // 一条读取另一个字段的规则
    val confirmation = FormField(
        rule = { v -> if (v == password.value) null else "The confirmation does not match the password." },
    )
    val form = Form(firstName, lastName, login, password, confirmation)

    // JSON 形式的值(即将发送给服务器的内容)
    fun toJson(): String = JsonObject(
        mapOf(
            "title" to JsonPrimitive(title),
            "firstName" to JsonPrimitive(firstName.value.trim()),
            "lastName" to JsonPrimitive(lastName.value.trim()),
            "login" to JsonPrimitive(login.value),
            "password" to JsonPrimitive(password.value),
        ),
    ).toString()
}

class Ex08Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { AccountPage() } }
    }
}

@Composable
fun AccountPage() {
    val account = remember { AccountForm() }
    // null:尚未提交;"":提交被拒绝;否则为已发送的 JSON
    var sent by remember { mutableStateOf<String?>(null) }

    ExamplePage("Example 08 - a reusable form") {
        DropdownList(
            label = "Title",
            value = account.title,
            choices = titles,
            onChange = { account.title = it },
            modifier = Modifier.width(200.dp),
        )
        TextField(account.firstName, "First name")
        TextField(account.lastName, "Last name")
        TextField(account.login, "Login")
        // 密码变化:确认字段会重新验证(如果它已经输入过)
        TextField(account.password, "Password", secret = true, after = { account.confirmation.revalidate() })
        TextField(account.confirmation, "Confirmation", secret = true)
        Spacer(Modifier.height(16.dp))
        Button(onClick = { sent = if (account.form.validate()) account.toJson() else "" }) {
            Text("Create the account")
        }
        Spacer(Modifier.height(12.dp))
        // ?.let:只有当 sent 不为 null 时,这个代码块才存在
        sent?.let { s ->
            Text(
                if (s.isEmpty()) "Invalid form." else "Valid form: $s",
                Modifier
                    .fillMaxWidth()
                    .background(if (s.isEmpty()) Color(0xFFFFEBEE) else Color(0xFFE8F5E9), RoundedCornerShape(8.dp))
                    .padding(12.dp),
            )
        }
    }
}

// FormField 的显示:它的值、它的错误。after:每次按键之后
// 要做什么(默认什么都不做)
@Composable
fun TextField(field: FormField, label: String, secret: Boolean = false, after: () -> Unit = {}) {
    OutlinedTextField(
        value = field.value,
        onValueChange = {
            field.change(it)
            after()
        },
        label = { Text(label) },
        singleLine = true,
        isError = field.error != null,
        supportingText = field.error?.let { m -> { Text(m) } },
        visualTransformation = if (secret) PasswordVisualTransformation() else VisualTransformation.None,
        modifier = Modifier.fillMaxWidth(),
    )
}
  • 第 48–77 行:表单字段及其规则,归并在一个类中;确认字段的规则会读取另一个字段([password.value]);
  • 第 101 行:[remember [ AccountForm() ]]:该对象只创建一次,并在重组之后依然存在;
  • 第 120 行:提交:[account.form.validate()] 验证所有内容,并判断是否可以提交;
  • 第 140–152 行:显示一个字段:它的值、它的错误,以及 [after],它指定每次按键之后要做什么:当密码变化时,重新验证确认字段。

Image

Image

3.9. 示例 09:格式化值

在 [@Composable] 函数中,使用标准函数来格式化值。应用中使用的函数汇集在同一个文件中:

// =========================================================================
// ex09/Formatting.kt - “自制”的格式化函数
// -------------------------------------------------------------------------
// Compose 没有自己的格式化机制(Angular 有它的
// “管道”):在 @Composable 函数中,我们调用普通的
// 函数,这些函数存放在一个文件中,并且可以单独测试:
//     timeRange(slot)                -> "8:00 - 8:20"
//     timeRange(slot, Part.START)    -> "8:00"
// Kotlin 还允许通过扩展为现有类型添加函数
// 和属性:"marie pelissier".capitalized ->
// "Marie Pelissier"。
// 对于日期、数字和金额,Java 的类
// (java.time、java.text)了解每种语言的惯例
// (参见 Ex09Activity.kt)。
// =========================================================================
package fr.stahe.examples.ex09

// 一个时间段,按 RdvMedecins API 的描述
data class Slot(val startHour: Int, val startMinute: Int, val endHour: Int, val endMinute: Int)

enum class Part { ALL, START, END }

// “8:05”而不是“8:5”;private:在此文件之外不可见
private fun time(h: Int, m: Int) = "$h:${m.toString().padStart(2, '0')}"

// 一个可选参数,带有默认值:part = Part.ALL
fun timeRange(s: Slot, part: Part = Part.ALL): String = when (part) {
    Part.START -> time(s.startHour, s.startMinute)
    Part.END -> time(s.endHour, s.endMinute)
    Part.ALL -> "${time(s.startHour, s.startMinute)} - ${time(s.endHour, s.endMinute)}"
}

// String 类型的扩展:为所有
// 字符串新增的属性。在函数体中,this 指代字符串
// “marie pelissier” -> “Marie Pelissier”;\p{L}:一个字母,带不带重音均可
val String.capitalized: String
    get() = Regex("\\p{L}+").replace(this) { m ->
        m.value.lowercase().replaceFirstChar { it.uppercase() }
    }

// “Marie PELISSIER” -> “MP”
val String.initials: String
    get() = split(Regex("\\s+")).filter { it.isNotEmpty() }.joinToString("") { it.first().uppercase() }
  • 第 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])遵循每种语言的惯例:

// =========================================================================
// ex09/Ex09Activity.kt - 格式化值
// -------------------------------------------------------------------------
// 表格的每一行显示一段代码及其显示的内容。
// 格式化器(DateTimeFormatter、NumberFormat)在 @Composable 函数之外
// 一次性创建:
// 构建它们比使用它们更耗费资源。
// Java 一开始就知道每种语言中星期和月份的名称:
// 使用之前无需加载任何东西。
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex09

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.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
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.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.text.font.FontFamily
import androidx.compose.ui.text.font.FontWeight
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 kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import java.text.NumberFormat
import java.time.LocalDate
import java.time.LocalDateTime
import java.time.format.DateTimeFormatter
import java.time.format.FormatStyle
import java.util.Locale

// 日期:“现成的”格式(SHORT、MEDIUM、LONG、FULL),或一种模式
val shortDate: DateTimeFormatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(Locale.US)
val fullDate: DateTimeFormatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(Locale.US)
val timeOnly: DateTimeFormatter = DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM).withLocale(Locale.US)
val frenchDay: DateTimeFormatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).withLocale(Locale.FRANCE)
val pattern: DateTimeFormatter = DateTimeFormatter.ofPattern("MM/dd/yyyy HH:mm", Locale.US)

// 数字和金额
val euros: NumberFormat = NumberFormat.getCurrencyInstance(Locale.US).apply { currency = java.util.Currency.getInstance("EUR") }
val integer: NumberFormat = NumberFormat.getNumberInstance(Locale.US)

// apply:配置刚创建的对象,并返回它
val percent: NumberFormat = NumberFormat.getPercentInstance(Locale.US).apply { minimumFractionDigits = 1 }

const val DAY = "2026-10-05" // RdvMedecins API 格式的日期
const val PRICE = 1234.5
const val RATE = 0.055
const val NAME = "marie pelissier"
val doctor = mapOf("title" to "Mme", "firstName" to "Marie", "lastName" to "PELISSIER")
val languages = listOf("Kotlin", "Compose", "Dart", "Swift", "SQL")
val slots = listOf(Slot(8, 0, 8, 20), Slot(8, 20, 8, 40), Slot(14, 5, 14, 25))

class Ex09Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { FormattingPage() } }
    }
}

@Composable
fun FormattingPage() {
    var now by remember { mutableStateOf(LocalDateTime.now()) }

    // (显示的代码,值):表格的一行,表示为一个对
    val rows = listOf(
        "shortDate.format(now)" to shortDate.format(now),
        "fullDate.format(now)" to fullDate.format(now),
        "timeOnly.format(now)" to timeOnly.format(now),
        "pattern.format(now)" to pattern.format(now),
        "fullDate.format(LocalDate.parse(DAY))" to fullDate.format(LocalDate.parse(DAY)),
        "frenchDay.format(LocalDate.parse(DAY))" to frenchDay.format(LocalDate.parse(DAY)),
        "now.toString()" to now.toString(),
        "euros.format(PRICE)" to euros.format(PRICE),
        "integer.format(PRICE)" to integer.format(PRICE),
        "\"%.1f\".format(Locale.ROOT, PRICE)" to "%.1f".format(Locale.ROOT, PRICE),
        "percent.format(RATE)" to percent.format(RATE),
        "NAME.uppercase()" to NAME.uppercase(),
        "NAME.capitalized" to NAME.capitalized,
        "\"RDV\".lowercase()" to "RDV".lowercase(),
        "languages.take(3).joinToString(\", \")" to languages.take(3).joinToString(", "),
        "JsonObject(...).toString()" to JsonObject(doctor.mapValues { JsonPrimitive(it.value) }).toString(),
        // 连续两次转换:第一次的结果传给第二次
        "NAME.capitalized.initials" to NAME.capitalized.initials,
    )

    ExamplePage("Example 09 - formatting") {
        // 一个表格:第一列占宽度的 55 %(weight)
        Row(Modifier.padding(4.dp)) {
            Text("In the code", Modifier.weight(0.55f), fontWeight = FontWeight.Bold)
            Text("Displayed", Modifier.weight(0.45f), fontWeight = FontWeight.Bold)
        }
        // 一个对可以被“解构”:(code, value)
        for ((code, value) in rows) {
            HorizontalDivider()
            Row(Modifier.padding(4.dp)) {
                Text(code, Modifier.weight(0.55f), fontFamily = FontFamily.Monospace, fontSize = 11.sp, color = Color(0xFFC7254E))
                Text(value, Modifier.weight(0.45f))
            }
        }
        Spacer(Modifier.height(16.dp))
        Text("Going through the entries of a Map", style = MaterialTheme.typography.titleSmall)
        for ((key, value) in doctor) {
            Text("$key = $value")
        }
        Spacer(Modifier.height(16.dp))
        Text("A home-made function: timeRange", style = MaterialTheme.typography.titleSmall)
        for (s in slots) {
            Text("${timeRange(s)} (start: ${timeRange(s, Part.START)})")
        }
        Spacer(Modifier.height(16.dp))
        OutlinedButton(onClick = { now = LocalDateTime.now() }) { Text("Refresh the time") }
    }
}
  • 第 51–62 行:格式化器,在 [@Composable] 函数之外一次性创建(创建它们的开销比使用它们更大)。[FormatStyle.MEDIUM]、[FULL]……:“现成的”格式;[ofPattern]:一种模式;[apply [ ... ]] 配置刚刚创建的对象并返回它;
  • 第 85–103 行:数组中的每一行都是一个(显示的代码,值)对,由 [to] 生成;
  • 第 113 行:一个键值对,如同 [Map] 的一个条目,被“解包”:[for ((code, value) in rows)]。

Image

Image

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