syncfusion-angular-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular TextBox

实现Syncfusion Angular TextBox

The Syncfusion Angular TextBox component is a feature-rich input element that enhances the native HTML input with floating labels, validation states, adornments (prepended/appended elements), accessibility support, and comprehensive styling options. This skill guides you through implementation patterns, configuration, and best practices.

Syncfusion Angular TextBox组件是功能丰富的输入元素，在原生HTML输入的基础上增强了浮动标签、验证状态、装饰元素（前置/后置元素）、无障碍支持以及全面的样式选项。本指南将带你了解实现模式、配置方法与最佳实践。

Component Overview

组件概览

The TextBox component provides:

Feature	Purpose
Floating Labels	Animated labels that float above input when focused or filled
Validation States	Visual feedback (error, warning, success) with CSS classes
Adornments	Prepend/append custom HTML elements (icons, buttons, units)
Clear Button	Built-in clear functionality to reset input value
Disabled/Read-only States	Control user interaction and editability
HTML Attributes	Support for standard input attributes (type, maxlength, etc.)
Multiline Support	Textarea configuration with row/column sizing
Accessibility	WCAG 2.2 compliance, keyboard navigation, ARIA attributes
RTL Support	Right-to-left language support
Styling Options	CSS classes, validation colors, responsive sizing

TextBox组件提供以下功能：

功能	用途
浮动标签	输入框聚焦或已填写时，标签会动画浮动到输入框上方
验证状态	通过CSS类提供错误、警告、成功的视觉反馈
装饰元素	可前置/后置自定义HTML元素（图标、按钮、单位等）
清除按钮	内置清除功能，可一键重置输入值
禁用/只读状态	控制用户交互能力与可编辑性
HTML属性支持	支持标准输入属性（类型、最大长度等）
多行文本支持	可配置为Textarea，支持设置行列尺寸
无障碍支持	符合WCAG 2.2标准，支持键盘导航、ARIA属性
RTL支持	支持从右到左的书写语言
样式选项	支持CSS类、验证颜色、响应式尺寸调整

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup
Create your first TextBox component
CSS imports and theme selection
Floating label implementation
Basic event binding and data binding
Common setup issues and solutions

📄 阅读： references/getting-started.md

安装与包配置
创建你的第一个TextBox组件
CSS导入与主题选择
浮动标签实现
基础事件绑定与数据绑定
常见环境搭建问题与解决方案

Input Features and State Management

输入功能与状态管理

📄 Read: references/input-features.md

Clear button implementation (showClearButton)
Disabled state (enabled property)
Read-only state (readonly property)
HTML attributes configuration (htmlAttributes)
Supporting input types and attributes
State management patterns for forms

📄 阅读： references/input-features.md

清除按钮实现（showClearButton）
禁用状态（enabled属性）
只读状态（readonly属性）
HTML属性配置（htmlAttributes）
支持的输入类型与属性
表单状态管理模式

Adornments and Customization

装饰元素与自定义配置

📄 Read: references/adornments-customization.md

Prepend and append template usage
Icon adornments for visual context
Button adornments (password toggle, clear)
Validation status indicators
Unit indicators (currency, temperature, etc.)
Performance and accessibility considerations

📄 阅读： references/adornments-customization.md

前置与后置模板使用
用于提供视觉上下文的图标装饰
按钮装饰（密码可见切换、清除按钮）
验证状态指示器
单位指示器（货币、温度等）
性能与无障碍注意事项

Validation States and Error Handling

验证状态与错误处理

📄 Read: references/validation-states.md

Error, warning, and success validation states
CSS class approach (e-error, e-warning, e-success)
Visual feedback patterns
Adding asterisk for required fields
Form integration with validation
Custom error message display

📄 阅读： references/validation-states.md

错误、警告、成功验证状态
CSS类实现方式（e-error、e-warning、e-success）
视觉反馈模式
为必填字段添加星号标记
表单验证集成
自定义错误消息展示

Styling and Appearance Customization

样式与外观自定义

📄 Read: references/styling-appearance.md

CSS structure and class hierarchy
Basic sizing (height, font, padding)
Floating label color customization
Validation state color changes
Borders, rounded corners, and advanced styling
Dynamic styling based on input value
Theme integration and customization

📄 阅读： references/styling-appearance.md

CSS结构与类层级
基础尺寸设置（高度、字体、内边距）
浮动标签颜色自定义
验证状态颜色修改
边框、圆角与高级样式设置
基于输入值的动态样式
主题集成与自定义

Multiline and Sizing Features

多行文本与尺寸功能

📄 Read: references/multiline-sizing.md

Multiline textarea configuration
Row and column sizing
Responsive sizing patterns
Height adjustments and constraints
Character counting implementation
Text wrapping and overflow handling

📄 阅读： references/multiline-sizing.md

多行Textarea配置
行列尺寸设置
响应式尺寸适配模式
高度调整与限制
字符计数实现
文本换行与溢出处理

Accessibility and Migration

无障碍支持与迁移指南

📄 Read: references/accessibility-migration.md

WCAG 2.2 and Section 508 compliance
Keyboard navigation support
ARIA attributes (aria-labelledby, aria-invalid, aria-disabled)
Screen reader compatibility
Migration from CSS TextBox to Angular component
RTL and mobile accessibility

📄 阅读： references/accessibility-migration.md

WCAG 2.2与第508节合规性
键盘导航支持
ARIA属性（aria-labelledby、aria-invalid、aria-disabled）
屏幕阅读器兼容性
从CSS TextBox迁移到Angular组件
RTL与移动端无障碍支持

Quick Start Example

快速入门示例

Create a floating label TextBox:

typescript

import { Component } from '@angular/core';
import { TextBoxModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [TextBoxModule],
  template: `
    <div style="margin: 50px;">
      <h2>Angular TextBox Example</h2>
      <ejs-textbox 
        #textbox
        [floatLabelType]="'Auto'"
        placeholder="Enter your name"
        (input)="onInput($event)"
      ></ejs-textbox>
      <p>Value: {{ textValue }}</p>
    </div>
  `
})
export class AppComponent {
  textValue = '';

  onInput(event: any) {
    this.textValue = event.target.value;
  }
}

Key Points:

Use
```
floatLabelType="'Auto'"
```
for automatic floating labels

Import

TextBoxModule

from

@syncfusion/ej2-angular-inputs

Use standard Angular
```
(input)
```
event binding
Set
```
placeholder
```
for the floating label text

创建带浮动标签的TextBox：

typescript

import { Component } from '@angular/core';
import { TextBoxModule } from '@syncfusion/ej2-angular-inputs';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [TextBoxModule],
  template: `
    <div style="margin: 50px;">
      <h2>Angular TextBox Example</h2>
      <ejs-textbox 
        #textbox
        [floatLabelType]="'Auto'"
        placeholder="Enter your name"
        (input)="onInput($event)"
      ></ejs-textbox>
      <p>Value: {{ textValue }}</p>
    </div>
  `
})
export class AppComponent {
  textValue = '';

  onInput(event: any) {
    this.textValue = event.target.value;
  }
}

核心要点：

使用
```
floatLabelType="'Auto'"
```
实现自动浮动标签

从

@syncfusion/ej2-angular-inputs

导入

TextBoxModule

使用标准Angular
```
(input)
```
事件绑定
设置
```
placeholder
```
作为浮动标签的文本内容

Common Patterns

常用模式

Pattern 1: Email Input with Icon Adornment

模式1：带图标的邮箱输入框

typescript

<ejs-textbox
  placeholder="Email"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'appendTemplate'"
></ejs-textbox>
<ng-template #appendTemplate>
  <span class="e-input-group-icon">✉</span>
</ng-template>

When to Use: Email, username, or other fields with visual context

typescript

<ejs-textbox
  placeholder="Email"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'appendTemplate'"
></ejs-textbox>
<ng-template #appendTemplate>
  <span class="e-input-group-icon">✉</span>
</ng-template>

适用场景： 邮箱、用户名或其他需要视觉上下文的字段

Pattern 2: Password Toggle

模式2：密码可见切换

typescript

<ejs-textbox
  [type]="passwordVisible ? 'text' : 'password'"
  placeholder="Password"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'toggleTemplate'"
></ejs-textbox>
<ng-template #toggleTemplate>
  <button (click)="togglePassword()">👁</button>
</ng-template>

// Component
togglePassword() {
  this.passwordVisible = !this.passwordVisible;
}

When to Use: Password fields requiring visibility toggle

typescript

<ejs-textbox
  [type]="passwordVisible ? 'text' : 'password'"
  placeholder="Password"
  [floatLabelType]="'Auto'"
  [appendTemplate]="'toggleTemplate'"
></ejs-textbox>
<ng-template #toggleTemplate>
  <button (click)="togglePassword()">👁</button>
</ng-template>

// 组件逻辑
togglePassword() {
  this.passwordVisible = !this.passwordVisible;
}

适用场景： 需要切换可见性的密码输入字段

Pattern 3: Validation with Error Display

模式3：带错误提示的验证输入框

typescript

<ejs-textbox
  [cssClass]="isValid ? 'e-success' : 'e-error'"
  placeholder="Phone"
  (change)="validatePhone($event)"
></ejs-textbox>
<p *ngIf="!isValid" style="color: red;">{{ errorMessage }}</p>

When to Use: Form fields with validation feedback

typescript

<ejs-textbox
  [cssClass]="isValid ? 'e-success' : 'e-error'"
  placeholder="Phone"
  (change)="validatePhone($event)"
></ejs-textbox>
<p *ngIf="!isValid" style="color: red;">{{ errorMessage }}</p>

适用场景： 需要提供验证反馈的表单字段

Pattern 4: Currency Input with Unit Indicator

模式4：带单位标记的货币输入框

typescript

<ejs-textbox
  type="number"
  placeholder="Amount"
  [prependTemplate]="'prependTemplate'"
></ejs-textbox>
<ng-template #prependTemplate>
  <span style="padding: 0 8px;">$</span>
</ng-template>

When to Use: Currency, temperature, or measurement inputs

typescript

<ejs-textbox
  type="number"
  placeholder="Amount"
  [prependTemplate]="'prependTemplate'"
></ejs-textbox>
<ng-template #prependTemplate>
  <span style="padding: 0 8px;">$</span>
</ng-template>

适用场景： 货币、温度或计量单位输入框

Key Props and Configuration

核心属性与配置

Refer to the full API summary in references/api.md.

Property / Method	Type	Purpose
`floatLabelType`	string	'Auto'
`placeholder`	string	Text shown when empty; used for floating labels
`value`	string	Current input value
`enabled`	boolean	Enable/disable the input (default: true)
`readonly`	boolean	Make input read-only (selectable but not editable)
`showClearButton`	boolean	Display clear button when field has content
`cssClass`	string	Custom CSS classes (e.g., 'e-error', 'e-warning', 'e-success', 'e-small', 'e-bigger', 'e-outline', 'e-corner')
`htmlAttributes`	object	Standard HTML attributes (name, maxlength, type, etc.)
`prependTemplate`	template	Template for content prepended before the input
`appendTemplate`	template	Template for content appended after the input
`multiline`	boolean	Enable textarea mode (renders a `<textarea>` )
`addIcon(position, icons)`	method	Add icon(s) programmatically ( `position` = 'append'
`addAttributes(attributes)`	method	Add HTML attributes programmatically (e.g., `maxlength` )
`removeAttributes(names[])`	method	Remove previously added attributes
`focusIn()` / `focusOut()`	method	Programmatically focus or blur the component
`destroy()`	method	Destroy the component instance and detach handlers
`getPersistData()`	method	Return persisted state string (when `enablePersistence` is used)

Notes:

Use CSS class
```
e-corner
```
together with
```
e-outline
```
to show rounded corners for box-model TextBoxes.
```
rows
```
and
```
cols
```
are not component properties. To set them on a multiline TextBox, use
```
addAttributes({rows: '5'} as any)
```
in the
```
(created)
```
event handler (see
```
references/multiline-sizing.md
```
).

For programmatic input creation (dynamic forms), use

Input.createInput

from

@syncfusion/ej2-inputs

(see

references/input-features.md

可参考 references/api.md 查看完整的API说明。

属性 / 方法	类型	用途
`floatLabelType`	string	'Auto' / 'Always' / 'Never' - 控制浮动标签的行为
`placeholder`	string	输入框为空时展示的文本；用作浮动标签内容
`value`	string	当前输入值
`enabled`	boolean	启用/禁用输入框（默认值：true）
`readonly`	boolean	设置输入框为只读状态（可选中但不可编辑）
`showClearButton`	boolean	输入框有内容时展示清除按钮
`cssClass`	string	自定义CSS类（例如 'e-error', 'e-warning', 'e-success', 'e-small', 'e-bigger', 'e-outline', 'e-corner'）
`htmlAttributes`	object	标准HTML属性（name、maxlength、type等）
`prependTemplate`	template	输入框前置内容的模板
`appendTemplate`	template	输入框后置内容的模板
`multiline`	boolean	启用Textarea模式（渲染为 `<textarea>` 元素）
`addIcon(position, icons)`	方法	编程式添加图标（ `position` = 'append'
`addAttributes(attributes)`	方法	编程式添加HTML属性（例如 `maxlength` ）
`removeAttributes(names[])`	方法	移除之前添加的属性
`focusIn()` / `focusOut()`	方法	编程式触发组件的聚焦/失焦
`destroy()`	方法	销毁组件实例并解绑事件处理函数
`getPersistData()`	方法	返回持久化状态字符串（启用 `enablePersistence` 时可用）

注意事项：

将CSS类
```
e-corner
```
与
```
e-outline
```
搭配使用，可以为盒模型TextBox设置圆角。
```
rows
```
和
```
cols
```
不是组件属性。要为多行TextBox设置这两个属性，请在
```
(created)
```
事件处理函数中调用
```
addAttributes({rows: '5'} as any)
```
（参考
```
references/multiline-sizing.md
```
）。
如果需要编程式创建输入框（动态表单），请使用
```
@syncfusion/ej2-inputs
```
提供的
```
Input.createInput
```
方法（参考
```
references/input-features.md
```
）。

Common Use Cases

常见使用场景

1. Contact Form

1. 联系表单

Multiple TextBox fields with floating labels, validation states, and required field indicators. See validation-states.md and accessibility-migration.md.

多个带浮动标签、验证状态、必填标记的TextBox字段。参考 validation-states.md 和 accessibility-migration.md。

2. Search Input with Clear Button

2. 带清除按钮的搜索输入框

TextBox with

showClearButton=true

for quick input reset. See input-features.md.

设置

showClearButton=true

的TextBox，支持快速重置输入内容。参考 input-features.md。

3. Styled Input with Icon Prefix/Suffix

3. 带前后缀图标的自定义样式输入框

TextBox with

prependTemplate

appendTemplate

for visual context. See adornments-customization.md.

使用

prependTemplate

或

appendTemplate

提供视觉上下文的TextBox。参考 adornments-customization.md。

4. Password Field with Toggle

4. 带可见切换的密码输入框

Password input with visibility toggle button via append template. See adornments-customization.md.

通过后置模板实现可见性切换按钮的密码输入框。参考 adornments-customization.md。

5. Multiline Comment Field

5. 多行评论输入框

Textarea with row sizing and character counting. See multiline-sizing.md.

支持设置行数与字符计数的Textarea组件。参考 multiline-sizing.md。

6. Accessible Form Field

6. 无障碍表单字段

TextBox with proper ARIA attributes and keyboard support for compliance. See accessibility-migration.md.

配置了正确ARIA属性与键盘支持的合规TextBox。参考 accessibility-migration.md。

Next Steps

后续步骤

Start with getting-started.md to set up your first TextBox
Explore input-features.md for state management
Use adornments-customization.md for custom UI
Reference validation-states.md for form validation
Customize styling with styling-appearance.md
Handle advanced cases in multiline-sizing.md and accessibility-migration.md

从 getting-started.md 开始，搭建你的第一个TextBox组件
阅读 input-features.md 了解状态管理方法
参考 adornments-customization.md 实现自定义UI
查阅 validation-states.md 实现表单验证
通过 styling-appearance.md 自定义样式
查看 multiline-sizing.md 和 accessibility-migration.md 处理高级场景

syncfusion-angular-textbox

Original

Translation

Implementing Syncfusion Angular TextBox

实现Syncfusion Angular TextBox

Component Overview

组件概览

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

Input Features and State Management

输入功能与状态管理

Adornments and Customization

装饰元素与自定义配置

Validation States and Error Handling

验证状态与错误处理

Styling and Appearance Customization

样式与外观自定义

Multiline and Sizing Features

多行文本与尺寸功能

Accessibility and Migration

无障碍支持与迁移指南

Quick Start Example

快速入门示例

Common Patterns

常用模式

Pattern 1: Email Input with Icon Adornment

模式1：带图标的邮箱输入框

Pattern 2: Password Toggle

模式2：密码可见切换

Pattern 3: Validation with Error Display

模式3：带错误提示的验证输入框

Pattern 4: Currency Input with Unit Indicator

模式4：带单位标记的货币输入框

Key Props and Configuration

核心属性与配置

Common Use Cases

常见使用场景

1. Contact Form

1. 联系表单

2. Search Input with Clear Button

2. 带清除按钮的搜索输入框

3. Styled Input with Icon Prefix/Suffix

3. 带前后缀图标的自定义样式输入框

4. Password Field with Toggle

4. 带可见切换的密码输入框

5. Multiline Comment Field

5. 多行评论输入框

6. Accessible Form Field

6. 无障碍表单字段

Related Documentation

相关文档

Next Steps

后续步骤