Back to Details

syncfusion-wpf-text-input-layout

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing WPF TextInputLayout

实现WPF TextInputLayout

The TextInputLayout control for WPF adds decorative elements and enhanced user experience to input controls by providing floating labels, icons, assistive labels, and various container styles on top of TextBox and other input views.
WPF的TextInputLayout控件通过在TextBox及其他输入视图之上提供浮动标签、图标、辅助标签和多种容器样式，为输入控件增添装饰元素并提升用户体验。

When to Use This Skill

适用场景

Use this skill when user need to:
  • Add floating labels to TextBox or other input controls in WPF
  • Implement input validation UI with error messages and visual feedback
  • Customize input containers with outlined, filled, or minimal styles
  • Add helper text and character counters to input fields
  • Include icons (leading/trailing) in input layouts
  • Configure hint positioning and float behaviors
  • Support multiple input types (TextBox, PasswordBox, ComboBox, etc.)
  • Implement Material Design-style input fields in WPF
  • Add assistive labels for accessibility and usability
  • Customize colors and styling for focused/unfocused/error states
当你需要以下操作时，可使用该技能：
  • 为WPF的TextBox或其他输入控件添加浮动标签
  • 实现带有错误提示和视觉反馈的输入验证UI
  • 自定义输入容器为轮廓、填充或极简样式
  • 为输入字段添加辅助文本和字符计数器
  • 在输入布局中添加图标（前置/后置）
  • 配置提示文本位置和浮动行为
  • 支持多种输入类型（TextBox、PasswordBox、ComboBox等）
  • 在WPF中实现Material Design风格的输入字段
  • 添加辅助标签以提升可访问性和易用性
  • 自定义聚焦/失焦/错误状态的颜色和样式

Component Overview

组件概述

The SfTextInputLayout control enhances standard WPF input controls by wrapping them with decorative elements:
SfTextInputLayout控件通过包装装饰元素，增强标准WPF输入控件的功能：

Key Features

核心功能

  • Floating Labels: Animated hint labels that float above input when focused
  • Container Types: Outlined (default), Filled, and None styles
  • Assistive Labels: Helper text, error messages, and character counters
  • Custom Icons: Leading and trailing views with inside/outside positioning
  • Multiple Input Views: TextBox, PasswordBox, ComboBox, ComboBoxAdv, SfTextBoxExt
  • State-Based Styling: Different colors for focused, unfocused, and error states
  • RTL Support: Right-to-left text flow for internationalization
  • Extensive Customization: Border thickness, corner radius, padding, and more
  • 浮动标签：获得焦点时会浮动到输入框上方的动画提示标签
  • 容器类型：轮廓（默认）、填充和无样式三种类型
  • 辅助标签：辅助文本、错误提示和字符计数器
  • 自定义图标：支持前置/后置视图及内部/外部位置配置
  • 多输入视图支持：TextBox、PasswordBox、ComboBox、ComboBoxAdv、SfTextBoxExt
  • 状态化样式：聚焦、失焦和错误状态对应不同颜色
  • RTL支持：支持从右到左的文本流向，适配国际化需求
  • 高度可定制：可自定义边框厚度、圆角半径、内边距等

Typical Use Cases

典型应用场景

  • Form input fields with validation
  • Material Design-style interfaces
  • User registration and login forms
  • Data entry applications
  • Search boxes with icons
  • Password fields with visibility toggles
  • Dropdown inputs with decorative containers
  • 带验证的表单输入字段
  • Material Design风格界面
  • 用户注册和登录表单
  • 数据录入应用
  • 带图标的搜索框
  • 带可见性切换的密码字段
  • 带装饰容器的下拉输入框

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
  • Installation and assembly references
  • Namespace imports and initialization
  • Basic TextInputLayout setup
  • Adding hint labels
  • HintVisibility configuration
  • Theme support with SfSkinManager
📄 文档链接： references/getting-started.md
  • 安装和程序集引用
  • 命名空间导入与初始化
  • 基础TextInputLayout设置
  • 添加提示标签
  • HintVisibility配置
  • 配合SfSkinManager实现主题支持

Container Types and Layout

容器类型与布局

📄 Read: references/container-types.md
  • ContainerType property overview
  • Outlined container (default with rounded border)
  • Filled container (with background and base line)
  • None container (minimal styling)
  • ContainerBackground customization
  • OutlineCornerRadius configuration
📄 文档链接： references/container-types.md
  • ContainerType属性概述
  • 轮廓容器（默认带圆角边框）
  • 填充容器（带背景和基线）
  • 无样式容器（极简风格）
  • ContainerBackground自定义
  • OutlineCornerRadius配置

Assistive Labels and Validation

辅助标签与验证

📄 Read: references/assistive-labels.md
  • Helper text with HelperText property
  • HelperTextVisibility configuration
  • Error messages with ErrorText property
  • HasError property for validation state
  • Character counter with CharMaxLength
  • CharCountVisibility configuration
  • Validation patterns and best practices
📄 文档链接： references/assistive-labels.md
  • 使用HelperText属性添加辅助文本
  • HelperTextVisibility配置
  • 使用ErrorText属性设置错误提示
  • 通过HasError属性控制验证状态
  • 用CharMaxLength设置字符限制
  • CharCountVisibility配置
  • 验证模式与最佳实践

Customization and Styling

自定义与样式设置

📄 Read: references/customization.md
  • FocusedForeground for focused state colors
  • Foreground for unfocused state colors
  • ErrorForeground for error state colors
  • ActiveForeground property
  • ContainerBackground customization
  • FocusedBorderBrush for independent border colors
  • StrokeThickness and FocusedStrokeThickness
  • InputViewPadding configuration
  • Color patterns and styling approaches
📄 文档链接： references/customization.md
  • 聚焦状态颜色：FocusedForeground
  • 失焦状态颜色：Foreground
  • 错误状态颜色：ErrorForeground
  • ActiveForeground属性
  • ContainerBackground自定义
  • 独立边框颜色：FocusedBorderBrush
  • StrokeThickness与FocusedStrokeThickness
  • InputViewPadding配置
  • 颜色模式与样式设计方法

Icons and Input Views

图标与输入视图

📄 Read: references/icons-and-views.md
  • LeadingView and LeadingViewPosition configuration
  • TrailingView and TrailingViewPosition configuration
  • Icon implementation with font icons
  • Supported input views: TextBox, PasswordBox, ComboBox
  • ComboBoxAdv integration
  • SfTextBoxExt (Autocomplete) support
  • DropDownBorder customization
  • InputView property usage
📄 文档链接： references/icons-and-views.md
  • LeadingView与LeadingViewPosition配置
  • TrailingView与TrailingViewPosition配置
  • 使用字体图标实现图标功能
  • 支持的输入视图：TextBox、PasswordBox、ComboBox
  • ComboBoxAdv集成
  • SfTextBoxExt（自动完成）支持
  • DropDownBorder自定义
  • InputView属性使用方法

Hint Configuration

提示文本配置

📄 Read: references/hint-configuration.md
  • HintFloatMode property options
  • Float mode (default behavior)
  • AlwaysFloat mode (always at top)
  • None mode (hidden when focused)
  • Hint animation and positioning
  • Best practices for hint labels
📄 文档链接： references/hint-configuration.md
  • HintFloatMode属性选项
  • 浮动模式（默认行为）
  • 始终浮动模式（固定在顶部）
  • 无浮动模式（聚焦时隐藏）
  • 提示文本动画与位置
  • 提示标签最佳实践

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • RTL support with FlowDirection property
  • Right-to-left text flow configuration
  • Dropdown border customization
  • Complete API reference summary
  • Performance considerations
  • Best practices and patterns
  • Troubleshooting common issues
📄 文档链接： references/advanced-features.md
  • 通过FlowDirection属性实现RTL支持
  • 从右到左文本流向配置
  • 下拉边框自定义
  • 完整API参考汇总
  • 性能考量
  • 最佳实践与模式
  • 常见问题排查

Quick Start Example

快速入门示例

Basic TextInputLayout with Hint

带提示文本的基础TextInputLayout

XAML:
xml
<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#:
csharp
using Syncfusion.UI.Xaml.TextInputLayout;

var inputLayout = new SfTextInputLayout();
inputLayout.Hint = "Name";
inputLayout.HelperText = "Enter your full name";
inputLayout.InputView = new TextBox();
XAML：
xml
<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#：
csharp
using Syncfusion.UI.Xaml.TextInputLayout;

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

With Validation and Error State

带验证与错误状态的示例

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

Outlined Container with Icon

带图标的轮廓容器示例

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

Common Patterns

常见模式

Form Field with Validation Pattern

带验证模式的表单字段

Use this pattern for validated form inputs:
xml
<StackPanel>
    <!-- Text Input with Helper -->
    <inputLayout:SfTextInputLayout 
        Hint="Username" 
        HelperText="At least 5 characters"
        CharMaxLength="20"
        CharCountVisibility="Visible">
        <TextBox TextChanged="ValidateUsername"/>
    </inputLayout:SfTextInputLayout>
    
    <!-- Password Input -->
    <inputLayout:SfTextInputLayout 
        Hint="Password" 
        HelperText="Must contain letters and numbers">
        <PasswordBox PasswordChanged="ValidatePassword"/>
    </inputLayout:SfTextInputLayout>
</StackPanel>
csharp
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;
    }
}
以下模式适用于带验证的表单输入：
xml
<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>
csharp
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 Style Pattern

Material Design风格模式

Create Material Design-style inputs:
xml
<inputLayout:SfTextInputLayout 
    Hint="Email Address" 
    ContainerType="Filled"
    FocusedForeground="#6200EE"
    ContainerBackground="#F5F5F5"
    HelperText="We'll never share your email">
    <TextBox />
</inputLayout:SfTextInputLayout>
创建Material Design风格的输入控件：
xml
<inputLayout:SfTextInputLayout 
    Hint="Email Address" 
    ContainerType="Filled"
    FocusedForeground="#6200EE"
    ContainerBackground="#F5F5F5"
    HelperText="We'll never share your email">
    <TextBox />
</inputLayout:SfTextInputLayout>

Search Box with Icons Pattern

带图标的搜索框模式

Implement search inputs with leading/trailing icons:
xml
<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>
实现带前置/后置图标的搜索输入：
xml
<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>

Dropdown with Outlined Container Pattern

带轮廓容器的下拉框模式

Enhance ComboBox with TextInputLayout:
xml
<inputLayout:SfTextInputLayout 
    Hint="Country" 
    ContainerType="Outlined"
    FocusedBorderBrush="Blue">
    <ComboBox ItemsSource="{Binding Countries}" 
              SelectedItem="{Binding SelectedCountry}"/>
</inputLayout:SfTextInputLayout>
用TextInputLayout增强ComboBox：
xml
<inputLayout:SfTextInputLayout 
    Hint="Country" 
    ContainerType="Outlined"
    FocusedBorderBrush="Blue">
    <ComboBox ItemsSource="{Binding Countries}" 
              SelectedItem="{Binding SelectedCountry}"/>
</inputLayout:SfTextInputLayout>

Key Properties

关键属性

Core Configuration

核心配置

  • InputView: The input control (TextBox, PasswordBox, etc.)
  • Hint: Floating label text
  • HintVisibility: Control hint label visibility
  • HintFloatMode: Float, AlwaysFloat, or None
  • ContainerType: Outlined, Filled, or None
  • InputView：输入控件（TextBox、PasswordBox等）
  • Hint：浮动标签文本
  • HintVisibility：控制提示标签的可见性
  • HintFloatMode：浮动、始终浮动或无浮动三种模式
  • ContainerType：轮廓、填充或无样式三种类型

Assistive Labels

辅助标签

  • HelperText: Additional guidance text
  • ErrorText: Error message text
  • HasError: Boolean to show error state
  • CharMaxLength: Maximum character limit
  • CharCountVisibility: Show/hide character counter
  • HelperText：附加指导文本
  • ErrorText：错误提示文本
  • HasError：布尔值，控制是否显示错误状态
  • CharMaxLength：最大字符限制
  • CharCountVisibility：显示/隐藏字符计数器

Styling Properties

样式属性

  • FocusedForeground: Color when focused
  • Foreground: Color when unfocused
  • ErrorForeground: Color in error state
  • ContainerBackground: Background color
  • FocusedBorderBrush: Border color when focused
  • FocusedForeground：聚焦状态下的颜色
  • Foreground：失焦状态下的颜色
  • ErrorForeground：错误状态下的颜色
  • ContainerBackground：容器背景色
  • FocusedBorderBrush：聚焦状态下的边框颜色

Border and Stroke

边框与线条

  • StrokeThickness: Unfocused border thickness (default: 1)
  • FocusedStrokeThickness: Focused border thickness (default: 2)
  • OutlineCornerRadius: Corner radius for outlined borders
  • StrokeThickness：失焦状态下的边框厚度（默认：1）
  • FocusedStrokeThickness：聚焦状态下的边框厚度（默认：2）
  • OutlineCornerRadius：轮廓容器的圆角半径

Icons and Views

图标与视图

  • LeadingView: Icon/view on the left
  • LeadingViewPosition: Inside or Outside
  • TrailingView: Icon/view on the right
  • TrailingViewPosition: Inside or Outside
  • LeadingView：左侧图标/视图
  • LeadingViewPosition：内部或外部位置
  • TrailingView：右侧图标/视图
  • TrailingViewPosition：内部或外部位置

Common Use Cases

常见应用场景

User Registration Form

用户注册表单

Combine multiple TextInputLayout controls with validation for username, email, password, and other fields with real-time validation feedback.
将多个TextInputLayout控件与验证逻辑结合，实现用户名、邮箱、密码等字段的实时验证反馈。

Login Screen

登录界面

Create clean, Material Design-style login forms with email/username and password inputs with floating labels and error states.
创建简洁的Material Design风格登录表单，包含邮箱/用户名和密码输入框，支持浮动标签和错误状态显示。

Search Interfaces

搜索界面

Implement search boxes with icons, placeholder hints, and clear buttons using leading/trailing views.
利用前置/后置视图实现带图标、占位提示和清除按钮的搜索框。

Data Entry Forms

数据录入表单

Build comprehensive forms with helper text, character limits, and validation messages for improved user experience.
构建包含辅助文本、字符限制和验证提示的综合表单，提升用户体验。

Settings Panels

设置面板

Use TextInputLayout with various input types (TextBox, ComboBox, PasswordBox) for consistent styling in settings interfaces.
使用TextInputLayout搭配多种输入类型（TextBox、ComboBox、PasswordBox），为设置界面提供统一的样式。

Profile Editing

资料编辑

Create profile edit forms with validation, character counters for bio fields, and proper error handling.
创建带验证的资料编辑表单，为简介字段添加字符计数器，并实现完善的错误处理。

Related Components

相关组件

  • TextBox: Primary input view for text
  • PasswordBox: For password inputs
  • ComboBox/ComboBoxAdv: For dropdown selections
  • SfTextBoxExt: For autocomplete functionality
  • TextBox：主要的文本输入视图
  • PasswordBox：用于密码输入
  • ComboBox/ComboBoxAdv：用于下拉选择
  • SfTextBoxExt：用于自动完成功能

Notes

注意事项

  • The hint label automatically animates based on focus state
  • Error validation logic must be implemented at application level
  • Character counter shows error color when limit exceeded
  • FocusedBorderBrush overrides FocusedForeground for borders
  • DropDownBorder only applies to ComboBox/ComboBoxAdv
  • OutlineCornerRadius only applies to Outlined container type
Next Steps: Navigate to the reference documentation above based on your implementation needs. Start with 
getting-started.md
for initial setup, then explore specific features as needed.
  • 提示标签会根据焦点状态自动触发动画
  • 错误验证逻辑需要在应用层自行实现
  • 字符计数器在超出限制时会显示错误颜色
  • FocusedBorderBrush的优先级高于FocusedForeground，会覆盖边框颜色设置
  • DropDownBorder仅对ComboBox/ComboBoxAdv生效
  • OutlineCornerRadius仅对轮廓容器类型生效
下一步操作： 根据你的实现需求，参考上述文档链接。初始设置请从
getting-started.md
开始，之后可按需探索特定功能。