文本输入 · TextInput

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

文本输入 · 综合展示 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

{
  "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.

完整示例的额外依赖

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

npm install @heroicons/react@2.2.0