syncfusion-javascript-textbox

用途

Syncfusion JavaScript TextBox 是一个轻量级输入控件，用于接受文本输入，并支持浮动标签、装饰元素、校验状态和样式定制。该技能用于在 Web 应用中实现和配置 TextBox 组件，适用于构建文本输入字段、浮动标签、装饰元素等场景。

主要能力

• 灵活的输入模式：单行、多行、只读、禁用。
• 视觉反馈：校验状态、浮动标签、样式选项。
• 可扩展设计：支持图标、按钮和自定义模板。
• 无障碍合规：WCAG 2.2、屏幕阅读器支持、键盘导航。

具体功能包括：

• 创建带占位符和初始值的基础文本输入。
• 添加在聚焦或填充时动画的浮动标签。
• 通过装饰元素（图标、按钮、前缀/后缀）增强输入。
• 实现校验状态（错误、警告、成功）。
• 构建可自动调整大小的多行文本区域。
• 应用自定义样式，包括尺寸变化和主题。
• 通过 ARIA 属性和键盘导航支持无障碍。
• 添加清除按钮或密码切换等交互功能。

使用方式

安装

TextBox 组件位于 @syncfusion/ej2-inputs 包中：

npm install @syncfusion/ej2-inputs @syncfusion/ej2-base

导入所需的 CSS 主题：

import '@syncfusion/ej2-base/styles/material.css';
import '@syncfusion/ej2-inputs/styles/material.css';

快速开始示例

基础 TextBox：

import { TextBox } from '@syncfusion/ej2-inputs';

// Create a simple text input
const textbox = new TextBox({
  placeholder: 'Enter your name'
});

textbox.appendTo('#textbox');

带浮动标签的 TextBox：

import { TextBox } from '@syncfusion/ej2-inputs';

const textbox = new TextBox({
  placeholder: 'Email Address',
  floatLabelType: 'Auto'  // Label floats on focus or when filled
});

textbox.appendTo('#email');

带图标的 TextBox：

import { TextBox } from '@syncfusion/ej2-inputs';

const textbox = new TextBox({
  placeholder: 'Search',
  floatLabelType: 'Never',
  created: () => {
    textbox.addIcon('append', 'e-icons e-search');
  }
});

textbox.appendTo('#search');

带校验状态的 TextBox：

import { TextBox } from '@syncfusion/ej2-inputs';

// Error state
const errorBox = new TextBox({
  placeholder: 'Username',
  cssClass: 'e-error',
  value: ''
});
errorBox.appendTo('#error');

// Success state
const successBox = new TextBox({
  placeholder: 'Confirmed',
  cssClass: 'e-success',
  value: 'valid input'
});
successBox.appendTo('#success');

常见模式

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

const emailBox = new TextBox({
  placeholder: 'Email Address',
  floatLabelType: 'Auto',
  created: () => {
    emailBox.addIcon('prepend', 'e-icons e-people');
  }
});
emailBox.appendTo('#email');

适用场景：在表单或联系区域收集邮箱地址。

模式 2：密码切换

const passwordBox = new TextBox({
  placeholder: 'Password',
  type: 'password',
  floatLabelType: 'Auto',
  created: () => {
    passwordBox.addIcon('append', 'e-icons e-eye');
  }
});
passwordBox.appendTo('#password');

// Toggle visibility on icon click
const eyeIcon = document.querySelector('#password .e-eye');
eyeIcon.addEventListener('click', () => {
  if (passwordBox.type === 'password') {
    passwordBox.type = 'text';
    eyeIcon.className = 'e-icons e-eye-slash';
  } else {
    passwordBox.type = 'password';
    eyeIcon.className = 'e-icons e-eye';
  }
  passwordBox.dataBind();
});

适用场景：带可见性切换选项的安全密码输入。

模式 3：多行地址输入

const addressBox = new TextBox({
  placeholder: 'Enter your address',
  floatLabelType: 'Auto',
  multiline: true,
  created: (args) => {
    addressBox.addAttributes({ rows: '4' });
  }
});
addressBox.appendTo('#address');

适用场景：收集地址、描述或评论等较长文本。

模式 4：内联校验反馈

const usernameBox = new TextBox({
  placeholder: 'Username (3+ characters)',
  floatLabelType: 'Auto'
});
usernameBox.appendTo('#username');

usernameBox.element.addEventListener('blur', (e) => {
  const value = usernameBox.value;
  if (value.length < 3) {
    usernameBox.cssClass = 'e-error';
  } else {
    usernameBox.cssClass = 'e-success';
  }
  usernameBox.dataBind();
});

适用场景：用户输入或离开字段时的实时校验反馈。

关键属性

属性	类型	描述
placeholder	string	为空时显示的提示文本
value	string	当前输入值
floatLabelType	'Never' | 'Always' | 'Auto'	标签行为（默认：'Never'）
multiline	boolean	启用多行模式（textarea）
cssClass	string	自定义 CSS 类（例如 'e-error'、'e-success'、'e-small'）
type	string	输入类型（'text'、'password'、'email' 等）
disabled	boolean	禁用输入
readonly	boolean	使输入只读
prependTemplate	string	输入前的 HTML 内容
appendTemplate	string	输入后的 HTML 内容
created	function	组件创建时触发的事件

文档与导航指南

入门：

• 阅读：references/getting-started.md
• 安装和包设置
• TypeScript 中的基础 TextBox 实现
• 导入 CSS 样式和主题
• 添加浮动标签
• 以编程方式创建带图标的 TextBox
• 基本属性：placeholder、value、floatLabelType

输入状态与样式：

• 阅读：references/input-states.md
• 校验状态（错误、警告、成功）
• 禁用和只读状态
• 清除按钮功能
• 以编程方式设置和获取值
• 何时使用每种状态进行用户反馈

装饰与图标：

• 阅读：references/adornments.md
• 使用 prependTemplate 和 appendTemplate 添加装饰
• 图标放置和样式
• 创建操作按钮（密码切换、清除）
• 输入分隔符和视觉组织
• 交互元素的事件处理

浮动标签：

• 阅读：references/floating-labels.md
• 浮动标签类型：Auto、Always、Never
• 带图标的浮动标签
• 自定义标签样式和颜色
• 标签定位和对齐

多行 TextBox：

• 阅读：references/multiline-textbox.md
• 使用 multiline: true 创建多行 TextBox
• 使用 textarea 元素
• 自动调整大小实现
• 使用 maxLength 限制文本长度
• 禁用调整大小功能

样式与尺寸：

• 阅读：references/styling-sizing.md
• 尺寸变化：normal、small（e-small）、bigger（e-bigger）
• 填充和轮廓模式（e-filled、e-outline）
• 使用 cssClass 进行 CSS 自定义
• Theme Studio 集成
• 背景和文本颜色自定义

无障碍：

• 阅读：references/accessibility.md
• WCAG 2.2 和 Section 508 合规
• ARIA 属性：aria-placeholder、aria-labelledby
• 键盘导航支持
• 屏幕阅读器兼容性
• 从右到左（RTL）支持

适用场景

• 在表单或联系区域收集邮箱地址。
• 带可见性切换选项的安全密码输入。
• 收集地址、描述或评论等较长文本。
• 用户输入或离开字段时的实时校验反馈。
• 需要浮动标签、装饰元素、校验状态或无障碍支持的文本输入场景。

限制

资料中未提供关于收费、价格、平台限制或具体性能效果的信息，暂未提供。