syncfusion-wpf-text-input-layout

实现 WPF TextInputLayout

WPF 的 TextInputLayout 控件通过在 TextBox 和其他输入视图上添加浮动标签、图标、辅助标签和各种容器样式等装饰元素，提升输入控件的用户体验。

何时使用此技能

在以下情况下使用此技能：

• 为 TextBox 或其他输入控件添加浮动标签
• 实现带错误消息和视觉反馈的输入验证 UI
• 使用轮廓、填充或简约样式自定义输入容器
• 为输入字段添加帮助文本和字符计数器
• 在输入布局中添加图标（前置/后置）
• 配置提示的位置和浮动行为
• 支持多种输入类型（TextBox、PasswordBox、ComboBox 等）
• 在 WPF 中实现 Material Design 风格的输入字段
• 添加辅助标签以提升无障碍性和易用性
• 自定义焦点、非焦点和错误状态下的颜色与样式

组件概述

SfTextInputLayout 控件通过在标准 WPF 输入控件外层添加装饰元素，增强其功能：

主要功能

• 浮动标签：获得焦点时会浮动到输入框上方的动画提示标签
• 容器类型：轮廓（默认）、填充和无样式
• 辅助标签：帮助文本、错误消息和字符计数器
• 自定义图标：可设置内部或外部位置的前置和后置视图
• 多种输入视图：TextBox、PasswordBox、ComboBox、ComboBoxAdv、SfTextBoxExt、DatePicker、SfDatePicker、SfTimePicker、UpDown、SfMaskedEdit、IntegerTextBox、DoubleTextBox、PercentTextBox、CurrencyTextBox
• 基于状态的样式：为焦点、非焦点和错误状态设置不同颜色
• RTL 支持：支持从右到左的文本流，适用于国际化
• 丰富的自定义选项：边框粗细、圆角半径、内边距等

典型用例

• 带验证的表单输入字段
• Material Design 风格的界面
• 用户注册和登录表单
• 数据录入应用程序
• 带图标的搜索框
• 带可见性切换功能的密码字段
• 带装饰容器的下拉输入框

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集引用
• 命名空间导入和初始化
• TextInputLayout 基本设置
• 添加提示标签
• HintVisibility 配置
• 使用 SfSkinManager 支持主题

容器类型和布局

📄 阅读： references/container-types.md

• ContainerType 属性概述
• 轮廓容器（默认带圆角边框）
• 填充容器（带背景和底线）
• 无容器（简约样式）
• ContainerBackground 自定义
• OutlineCornerRadius 配置

辅助标签和验证

📄 阅读： references/assistive-labels.md

• 使用 HelperText 属性设置帮助文本
• HelperTextVisibility 配置
• 使用 ErrorText 属性设置错误消息
• 使用 HasError 属性设置验证状态
• 使用 CharMaxLength 设置字符计数器
• CharCountVisibility 配置
• 验证模式和最佳实践

自定义和样式

📄 阅读： references/customization.md

• 使用 FocusedForeground 设置焦点状态颜色
• 使用 Foreground 设置非焦点状态颜色
• 使用 ErrorForeground 设置错误状态颜色
• ActiveForeground 属性
• ContainerBackground 自定义
• 使用 FocusedBorderBrush 独立设置边框颜色
• StrokeThickness 和 FocusedStrokeThickness
• InputViewPadding 配置
• 颜色模式和样式设置方法

图标和输入视图

📄 阅读： references/icons-and-views.md

• LeadingView 和 LeadingViewPosition 配置
• TrailingView 和 TrailingViewPosition 配置
• 使用字体图标实现图标
• 支持的输入视图：TextBox、PasswordBox、ComboBox、ComboBoxAdv、SfTextBoxExt、DatePicker、SfDatePicker、SfTimePicker、UpDown、SfMaskedEdit、IntegerTextBox、DoubleTextBox、PercentTextBox、CurrencyTextBox
• ComboBoxAdv 集成
• 支持 SfTextBoxExt（自动完成）
• 自定义 DropDownBorder
• InputView 属性的用法

提示配置

📄 阅读： references/hint-configuration.md

• HintFloatMode 属性选项
• Float 模式（默认行为）
• AlwaysFloat 模式（始终位于顶部）
• None 模式（获得焦点时隐藏）
• 提示动画和位置
• 提示标签最佳实践

高级功能

📄 阅读： references/advanced-features.md

• 使用 FlowDirection 属性支持 RTL
• 从右向左的文本流配置
• 自定义下拉边框
• 完整 API 参考摘要
• 性能注意事项
• 最佳实践和模式
• 常见问题排查

快速入门示例

带提示的基本 TextInputLayout

XAML：

<Window xmlns:inputLayout="clr-namespace:Syncfusion.UI.Xaml.TextInputLayout;assembly=Syncfusion.SfTextInputLayout.WPF">
    
    <inputLayout:SfTextInputLayout 
        Hint="Name" 
        HelperText="Enter your full name">
        <TextBox />
    </inputLayout:SfTextInputLayout>
    
</Window>

C#：

using Syncfusion.UI.Xaml.TextInputLayout;

var inputLayout = new SfTextInputLayout();
inputLayout.Hint = "Name";
inputLayout.HelperText = "Enter your full name";
inputLayout.InputView = new TextBox();

带验证和错误状态

XAML：

<inputLayout:SfTextInputLayout 
    Hint="Email" 
    HelperText="Enter a valid email address"
    ErrorText="Invalid email format"
    HasError="True"
    ErrorForeground="Red">
    <TextBox Text="invalid@"/>
</inputLayout:SfTextInputLayout>

带图标的轮廓容器

XAML：

<inputLayout:SfTextInputLayout 
    Hint="Search" 
    ContainerType="Outlined"
    FocusedForeground="Blue">
    <TextBox />
    <inputLayout:SfTextInputLayout.LeadingView>
        <Label Content="🔍" FontSize="16"/>
    </inputLayout:SfTextInputLayout.LeadingView>
</inputLayout:SfTextInputLayout>

常见模式

带验证的表单字段模式

对经过验证的表单输入使用此模式：

<StackPanel>
    
    <inputLayout:SfTextInputLayout 
        Hint="Username" 
        HelperText="At least 5 characters"
        CharMaxLength="20"
        CharCountVisibility="Visible">
        <TextBox TextChanged="ValidateUsername"/>
    </inputLayout:SfTextInputLayout>
    
    
    <inputLayout:SfTextInputLayout 
        Hint="Password" 
        HelperText="Must contain letters and numbers">
        <PasswordBox PasswordChanged="ValidatePassword"/>
    </inputLayout:SfTextInputLayout>
</StackPanel>

private void ValidateUsername(object sender, TextChangedEventArgs e)
{
    var textBox = sender as TextBox;
    var layout = FindParent<SfTextInputLayout>(textBox);
    
    if (textBox.Text.Length < 5)
    {
        layout.HasError = true;
        layout.ErrorText = "Username too short";
    }
    else
    {
        layout.HasError = false;
    }
}

Material Design 风格模式

创建 Material Design 风格的输入控件：

<inputLayout:SfTextInputLayout 
    Hint="Email Address" 
    ContainerType="Filled"
    FocusedForeground="#6200EE"
    ContainerBackground="#F5F5F5"
    HelperText="We'll never share your email">
    <TextBox />
</inputLayout:SfTextInputLayout>

带图标的搜索框模式

使用前置／后置图标实现搜索输入框：

<inputLayout:SfTextInputLayout 
    Hint="Search..." 
    ContainerType="Outlined"
    OutlineCornerRadius="20">
    <TextBox TextChanged="OnSearchTextChanged"/>
    
    <inputLayout:SfTextInputLayout.LeadingView>
        <Label Content="🔍" FontSize="18"/>
    </inputLayout:SfTextInputLayout.LeadingView>
    
    <inputLayout:SfTextInputLayout.TrailingView>
        <Button Content="✕" Click="ClearSearch" 
                Background="Transparent" BorderThickness="0"/>
    </inputLayout:SfTextInputLayout.TrailingView>
</inputLayout:SfTextInputLayout>

带轮廓容器的下拉框模式

使用 TextInputLayout 增强 ComboBox：

<inputLayout:SfTextInputLayout 
    Hint="Country" 
    ContainerType="Outlined"
    FocusedBorderBrush="Blue">
    <ComboBox ItemsSource="{Binding Countries}" 
              SelectedItem="{Binding SelectedCountry}"/>
</inputLayout:SfTextInputLayout>

关键属性

核心配置

• InputView：输入控件（TextBox、PasswordBox 等）
• Hint：浮动标签文本
• HintVisibility：控制提示标签的可见性
• HintFloatMode：Float、AlwaysFloat 或 None
• ContainerType：Outlined、Filled 或 None

辅助标签

• HelperText：补充说明文本
• ErrorText：错误消息文本
• HasError：用于显示错误状态的布尔值
• CharMaxLength：最大字符数
• CharCountVisibility：显示／隐藏字符计数器

样式属性

• FocusedForeground：获得焦点时的颜色
• Foreground：未获得焦点时的颜色
• ErrorForeground：错误状态下的颜色
• ContainerBackground：背景颜色
• FocusedBorderBrush：获得焦点时的边框颜色

边框和笔画

• StrokeThickness：未获得焦点时的边框粗细（默认值：1）
• FocusedStrokeThickness：获得焦点时的边框粗细（默认值：2）
• OutlineCornerRadius：轮廓边框的圆角半径

图标和视图

• LeadingView：左侧的图标／视图
• LeadingViewPosition：Inside 或 Outside
• TrailingView：右侧的图标／视图
• TrailingViewPosition：Inside 或 Outside

常见用例

用户注册表单

组合多个 TextInputLayout 控件，为用户名、电子邮件、密码及其他字段添加验证，并提供实时验证反馈。

登录界面

创建简洁的 Material Design 风格登录表单，包含电子邮件／用户名和密码输入框，并带有浮动标签和错误状态。

搜索界面

使用前置／后置视图实现带图标、占位提示和清除按钮的搜索框。

数据录入表单

构建包含辅助文本、字符数限制和验证消息的完整表单，以提升用户体验。

设置面板

在设置界面中使用 TextInputLayout 配合各种输入类型（TextBox、ComboBox、PasswordBox），实现统一的样式。

个人资料编辑

创建个人资料编辑表单，支持验证，为简介字段添加字符计数器，并妥善处理错误。

相关组件

• TextBox：文本的主要输入视图
• PasswordBox：用于密码输入
• ComboBox/ComboBoxAdv：用于下拉选择
• SfTextBoxExt：用于自动完成功能
• DatePicker/SfDatePicker：用于日期选择
• SfTimePicker：用于时间选择
• UpDown：用于数值步进输入
• SfMaskedEdit：用于带掩码的文本输入
• IntegerTextBox/DoubleTextBox/PercentTextBox/CurrencyTextBox：用于数值输入

注意事项

• 提示标签会根据焦点状态自动动画显示
• 错误验证逻辑必须在应用程序层实现
• 超出限制时，字符计数器会显示错误颜色
• FocusedBorderBrush 会覆盖边框的 FocusedForeground
• DropDownBorder 仅适用于 ComboBox/ComboBoxAdv
• OutlineCornerRadius 仅适用于 Outlined 容器类型

---

后续步骤： 根据实现需求，查阅上方的参考文档。先从 getting-started.md 开始进行初始设置，然后按需了解特定功能。