syncfusion-maui-text-input-layout

实现 .NET MAUI 文本输入布局

一份全面的指南，介绍如何实现和自定义 Syncfusion .NET MAUI Text Input Layout 控件。该控件可在输入视图上添加浮动标签、图标和辅助标签等装饰元素。

何时使用本指南

在以下情况下使用本指南：

• 为输入字段添加浮动提示标签
• 显示辅助文本、错误消息或字符计数器
• 为输入字段实现容器类型（Filled、Outlined、None）
• 为输入视图添加前置或后置图标
• 切换 Entry 控件中的密码可见性
• 为输入应用视觉状态（Normal、Focused、Error）
• 自定义标签样式、颜色和字体
• 支持多种输入视图（Entry、Editor、Autocomplete、ComboBox、Picker）
• 通过错误状态实现表单验证
• 添加辅助标签以提升无障碍性
• 创建 Material Design 风格的输入字段

组件概述

SfTextInputLayout 可包装输入控件，并提供：

• 浮动标签 — 聚焦时会动画移动到顶部的提示
• 容器类型 — Filled（背景）、Outlined（边框）、None
• 辅助标签 — 辅助文本、错误消息、字符计数器
• 自定义图标 — 可定位的前置/后置视图
• 视觉状态 — Normal、Focused、Error、Disabled
• 密码切换 — 显示/隐藏密码字符
• RTL 支持 — 从右到左的文本流向
• 多种输入视图 — Entry、Editor、Autocomplete、ComboBox、Picker、DatePicker、TimePicker、Masked Entry、Numeric Entry

主要功能：

• Material Design 风格的输入装饰
• 浮动提示标签动画
• 显示辅助文本和错误文本
• 字符计数及最大长度限制
• 前置/后置图标定位（Inside/Outside）
• 切换密码可见性
• 集成 Visual State Manager
• 可自定义字体、颜色和笔画
• 为辅助标签预留空间

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装 NuGet 包（Syncfusion.Maui.Core）
• 注册处理程序（ConfigureSyncfusionCore）
• 设置命名空间（XAML 和 C#）
• 使用 Entry 进行基本实现
• 添加提示标签
• 密码可见性切换基础
• 第一个可运行示例

容器类型与样式

📄 阅读： references/container-types.md

• ContainerType 属性（Filled、Outlined、None）
• 带背景的 Filled 容器
• 带边框的 Outlined 容器
• 自定义 ContainerBackground
• 使用 OutlineCornerRadius 设置圆角
• 使用 InputViewPadding 设置间距
• 各类型的视觉示例

提示与辅助标签

📄 阅读： references/hints-and-labels.md

• 提示/浮动标签（Hint、ShowHint）
• 固定提示位置（IsHintAlwaysFloated）
• 辅助文本（HelperText、ShowHelperText）
• 错误文本（ErrorText、HasError）
• 字符计数器（CharMaxLength、ShowCharCount）
• 预留空间（ReserveSpaceForAssistiveLabels）
• 标签样式（HintLabelStyle、HelperLabelStyle、ErrorLabelStyle）
• 字体自定义（FontFamily、FontSize、FontAttributes）

自定义图标与视图

📄 阅读： references/custom-icons.md

• 前置视图（LeadingView、LeadingViewPosition）
• 后置视图（TrailingView、TrailingViewPosition）
• Inside 与 Outside 定位
• 字体图标和 Unicode
• 集成自定义视图
• 图标操作的事件处理
• 常见图标模式（日历、搜索、清除）

状态、颜色与主题

📄 阅读： references/states-and-colors.md

• 视觉状态（Normal、Focused、Error、Disabled）
• 用于边框的 Stroke 属性
• CurrentActiveColor 属性
• 集成 Visual State Manager
• 笔画粗细（FocusedStrokeThickness、UnfocusedStrokeThickness）
• 容器背景颜色
• 标签文本颜色
• 主题集成

高级功能和事件

📄 阅读： references/advanced-features.md

• 密码可见性切换（EnablePasswordVisibilityToggle）
• PasswordVisibilityToggled 事件
• 从右到左支持（FlowDirection）
• 支持的输入视图（Entry、Editor、Autocomplete、ComboBox 等）
• 特定平台的限制
• 操作场景
• 故障排除