# 文本输入 · TextInput

- 页面: https://jiguang132.com/zh/resources/astryx/docs/text-input
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

输入单行文本，支持标签、辅助信息和校验状态。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **文本输入 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **文本输入 · 交互示例 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **文本输入 · 搜索 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **文本输入 · 尺寸变化 / 尺寸 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **文本输入 · 多种状态 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **文本输入 · 样式变化 / 状态 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **文本输入 · 交互示例 7**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Text Input

TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| type | 'text' \| 'password' \| 'email' | 'text' | HTML 输入框类型。 |
| label * | string |  | 输入框的标签文本：始终渲染以确保无障碍性。 |
| value * | string |  | 输入框的当前值。 |
| onChange | (value: string, e: ChangeEvent<HTMLInputElement>) => void |  | 输入框值变化时触发的回调。 |
| changeAction | (value: string, e: ChangeEvent<HTMLInputElement>) => void \| Promise<void> |  | 在 onChange 之后（如果未被阻止）触发的异步操作。触发乐观更新并在挂起时显示加载旋转器。 |
| size | 'sm' \| 'md' \| 'lg' | 'md' | 输入框的尺寸变体。 |
| isLabelHidden | boolean | false | 视觉上隐藏标签，同时保持屏幕阅读器的无障碍性。 |
| description | string |  | 显示在标签和输入框之间的描述文本。 |
| isOptional | boolean | false | 在标签旁显示"可选"指示器。与 isRequired 互斥。 |
| isRequired | boolean | false | 在标签旁显示"必填"指示器并设置 aria-required。与 isOptional 互斥。 |
| onEnter | () => void |  | Callback fired when the user presses the Enter key. IME-safe: Enter used to commit a Japanese/Chinese/Korean conversion does not fire it. |
| onKeyDown | (e: KeyboardEvent<HTMLInputElement>) => void |  | Callback fired on keydown events on the input. |
| isDisabled | boolean | false | 禁用输入框，阻止交互并使元素变暗。 |
| isReadOnly | boolean | false | 将输入框设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读输入框不会变暗，并保留在 Tab 顺序中。同时设置时 isDisabled 优先。 |
| disabledMessage | string |  | 说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持输入框可聚焦（字段变为只读）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TextInput——已禁用的控件会吞掉外部 Tooltip 所需的悬停事件。 |
| isLoading | boolean | false | 使输入框进入加载状态，显示旋转器并设置 aria-busy。 |
| placeholder | string |  | 输入框为空时显示的占位符文本。 |
| labelTooltip | string |  | 在标签末尾的信息图标中显示的工具提示文本。 |
| startIcon | IconType |  | 显示在输入框起始位置的 SVG 图标组件（例如来自 heroicons 或 lucide）。 |
| status | {type: 'error' \| 'warning' \| 'success', message?: string} |  | 验证状态：应用彩色边框和状态图标。如果提供了 message，在输入框下方显示浮动消息。错误类型还会设置 aria-invalid。 |
| statusVariant | 'attached' \| 'detached' \| 'tooltip' | 'attached' | 状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。 |
| hasClear | boolean | false | 输入有值时显示清除 (×) 按鈕。点击后清空值并将焦点返回输入框。 |
| hasAutoFocus | boolean | false | 挂载时自动聚焦输入框。 |
| htmlName | string |  | 输入框的 HTML name 属性，用于表单提交。 |
| width | SizeValue |  | Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned. Without a width the field can shrink with its row, so a filter bar never overflows; use `<HStack wrap="wrap">` when the controls should move to a second line instead. |
| autoComplete | string |  | 原生 autocomplete 属性，原样转发给输入框。不影响受控的值。 |
| containerXstyle | StyleXStyles |  | 字段容器（标签、控件和状态整体）的 StyleX 样式。在 InputGroup 内（请改为设置 InputGroup 的样式）或 `horizontal-labels` FormLayout 中无效。不接受根级 `xstyle`、`className` 和 `style`。 |
| containerClassName | string |  | 字段容器的类名，作用目标同 `containerXstyle`。 |
| containerStyle | CSSProperties |  | 字段容器的内联样式，作用目标同 `containerXstyle`。 |
| controlXstyle | StyleXStyles |  | 可视控件框的 StyleX 样式：绘制边框和背景并包含图标与尾部控件的元素，而非原生输入元素。 |
| controlClassName | string |  | 可视控件框的类名。 |
| controlStyle | CSSProperties |  | 可视控件框的内联样式。 |

### 使用建议

- Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.
- Use validation status with a message to explain what went wrong: "Email must include @" is better than just turning the border red.
- Size the input to match the expected content length so users can gauge how much to type: small for zip codes, medium for names, large for URLs.
- Add a clear button for search and filter inputs so users can quickly reset without selecting all text.
- 避免：Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers.
- 避免：Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead.
- 避免：Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors.
- 避免：Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-text-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled",
        "readonly"
      ]
    }
  ]
}
```

### 组件结构

- **Label**: Text that identifies the field. Always rendered for accessibility even when visually hidden.
- **Description**: Helper text between the label and the input that provides additional context or formatting hints.
- **Start icon**: A leading icon inside the input that hints at the expected content, like a magnifying glass for search.
- **Placeholder**: Hint text shown when the input is empty. Disappears on focus.
- **Clear button**: A trailing × button that resets the value and returns focus to the input.
- **Spinner**: Loading indicator that appears during async actions like server-side validation.
- **Status icon**: A trailing icon (error, warning, or success) that communicates validation state.


## 完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

```bash
npm install @heroicons/react@2.2.0
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt