syncfusion-maui-toolkit-text-input-layout

实现 .NET MAUI 文本输入布局

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

何时使用此指南

当用户需要以下功能时，请使用此指南：

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

组件概览

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

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

主要功能：

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

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装 NuGet 包（Syncfusion.Maui.Toolkit）
• 注册处理程序（ConfigureSyncfusionToolkit）
• 设置命名空间（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 等）
• 平台特定限制
• 操作指南场景
• 故障排查