TextInputLayout：是什么，Material Design 及在 Android 中的配置

Android 中的 TextInputLayout 是什么

TextInputLayout — 是来自 com.google.android.material.textfield 包的 ViewGroup，它扩展了 LinearLayout 并在内部包含了一个 EditText。该组件是 Android Material Components 库的一部分，从 1.0.0 版本开始。TextInputLayout 的主要任务是以最少的开发工作量提供 Material Design 文本字段的现成实现。

与标准的 EditText 不同，TextInputLayout 管理浮动标签的动画，该标签通过内部 EditText 的 android:hint 属性设置。当字段为空时，标签作为普通提示显示在字段内部。一旦用户开始输入，标签会动画移动到字段的上部，尺寸变小。根据 Material Design Guidelines (2025)，这种动画改善了表单的感知，因为即使在输入数据后，用户也始终能看到字段名称。

在架构上，TextInputLayout 实现了装饰器模式：它拦截 EditText 事件，管理附加元素（标签、错误、图标、计数器）的显示，并协调它们的动画。内部 EditText 可通过 getEditText() 方法访问，并可以使用标准属性进行配置，包括 inputType、maxLines 和 hint。

<!-- Basic TextInputLayout markup -->
@+id/tilEmail
android:layout_width="match_parent"
android:layout_height="wrap_content">

    @+id/etEmail
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="Email"
    android:inputType="textEmailAddress" />

</com.google.android.material.textfield.TextInputLayout>

浮动标签及其配置

浮动标签（floating label）是 TextInputLayout 的关键功能。当字段为空时，android:hint 中的文本作为普通提示显示在 EditText 内部。当获得焦点或输入文本时，标签上升到 TextInputLayout 的上部，减少字体大小并改变颜色。这种行为解决了开始输入后提示不可见的问题。

浮动标签的配置通过 TextInputLayout 的属性进行：app:hintEnabled 确定浮动标签是否启用（默认为 true），app:hintAnimationEnabled 启用或禁用过渡动画，app:expandedHintEnabled 允许即使在字段为空且无焦点时也显示标签。不同状态下标签的颜色通过 colorPrimary 和 colorControlHighlight 样式管理。

根据 Google Material Components Team (2025)，浮动标签在具有大量字段的表单中特别有用，因为用户可能在开始输入后忘记字段名称。与输入时消失的简单 android:hint 不同，浮动标签始终保持可见，为每个字段提供上下文。

在 TextInputLayout 中显示错误

TextInputLayout 提供了一个内置的错误显示系统，与输入字段视觉集成。通过 error 方法设置错误时，组件会高亮字段（线条或边框的颜色变为红色）并在字段下方显示错误文本。这取代了对单独的错误消息 TextView 的需求。

错误显示的管理通过 setError(CharSequence) 和 setErrorEnabled(boolean) 方法进行。使用文本调用 setError 时，错误立即显示；调用 setError(null) 时，错误隐藏。TextInputLayout 还支持通过 app:errorIconDrawable 属性自定义错误图标，并通过 app:errorTextColor 管理错误颜色。

根据 Material Design Guidelines (2025)，错误消息应该具体且有用：不要写“无效输入“，而应写“电子邮件必须包含 @“。错误显示应在输入完成后（失去焦点或提交表单后）发生，而不是实时显示——这能减少用户填写表单时的压力。

// 程序化错误设置
textInputLayout.error = "Password min 8 chars"

// 错误隐藏
textInputLayout.error = null

// 验证错误检查与设置
if (email.isNullOrBlank()) {
    tilEmail.error = "Email is required"
} else {
    tilEmail.error = null
}

TextInputLayout 的图标和操作

TextInputLayout 支持在字段的开头（起始图标）和结尾（结束图标）显示图标。图标可以执行各种功能：切换密码可见性、清除字段、自定义操作。每种图标类型由单独的属性管理，并可以通过 app:startIconDrawable 或 app:endIconDrawable 属性替换为自定义图标。

结束图标模式通过 app:endIconMode 属性设置，可以取以下值：password_toggle — 切换密码可见性，clear_text — 清除字段，dropdown_menu — 下拉菜单箭头，custom — 自定义图标。对于 password_toggle，TextInputLayout 自动管理 inputType 在 textPassword 和 textVisiblePassword 之间的切换，并动画显示眼睛图标。

• password_toggle — 用于显示/隐藏密码的眼睛图标，内置动画。
• clear_text — 用于清除字段的叉号，有文本时出现。
• dropdown_menu — 用于 Exposed Dropdown Menu（Material Design 3）的箭头。
• custom — 通过 setEndIconOnClickListener 处理的任何自定义图标。

<!-- TextInputLayout with password toggle icon -->
@+id/tilPassword
android:layout_width="match_parent"
app:endIconMode="password_toggle"
app:passwordToggleTint="@color/primary">

    @+id/etPassword
    android:inputType="textPassword" />

</com.google.android.material.textfield.TextInputLayout>

TextInputLayout 样式：FilledBox 和 OutlinedBox

Android 的 Material Components 为 TextInputLayout 提供了两种主要样式：FilledBox（填充框）和 OutlinedBox（轮廓框）。FilledBox 样式具有彩色背景和字段下方的线条，在焦点时改变颜色。OutlinedBox 样式具有透明背景和围绕整个字段的轮廓，创建更清晰的边界，更适合有大量字段的表单。

样式的选择取决于应用程序的设计：FilledBox 推荐用于频繁使用的表单，因为它对各个字段的关注度较低。OutlinedBox 更适合短表单（登录、注册），其中每个字段应清晰标记。样式通过 XML 中的 style 属性或应用程序主题设置。

Material Design 3（M3）为 TextInputLayout 引入了更新的样式，改进了排版、新的颜色令牌和对 Material You 动态颜色的支持。在 M3 中，OutlinedBox 成为推荐的默认样式，FilledBox 调整了间距和圆角半径以适应新的规范。

TextInputLayout 的代码示例

一个完整的注册表单实现示例，使用 TextInputLayout，包括电子邮件和密码验证、错误显示和密码显示图标。点击注册按钮时，检查所有字段并显示相应的错误消息。

注册表单的 XML 标记

@+id/tilName
app:boxBackgroundMode="outlined">
    @+id/etName
    android:hint="Name" />
</...TextInputLayout>

@+id/tilRegEmail
app:boxBackgroundMode="outlined">
    @+id/etRegEmail
    android:hint="Email"
    android:inputType="textEmailAddress" />
</...TextInputLayout>

@+id/tilRegPassword
app:boxBackgroundMode="outlined"
app:endIconMode="password_toggle">
    @+id/etRegPassword
    android:hint="Password"
    android:inputType="textPassword" />
</...TextInputLayout>

Kotlin 中的表单验证

private fun validateForm(): Boolean {
    var isValid = true

    if (etName.text.isNullOrBlank()) {
        tilName.error = "Enter your name"
        isValid = false
    } else {
        tilName.error = null
    }

    val email = etRegEmail.text.toString()
    if (!Patterns.EMAIL_ADDRESS.matcher(email).matches()) {
        tilRegEmail.error = "Invalid email format"
        isValid = false
    } else {
        tilRegEmail.error = null
    }

    val password = etRegPassword.text.toString()
    if (password.length < 8) {
        tilRegPassword.error = "Password min 8 chars"
        isValid = false
    } else {
        tilRegPassword.error = null
    }

    return isValid
}