多行输入 · TextArea

输入多行内容，适合备注、描述和消息。

安装与前置条件

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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

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

Text Area

TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.

使用建议

• Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.
• Set maxLength with a character counter when there is a defined limit; it helps users stay within bounds before they submit.
• Use the status prop to surface validation feedback inline: show success when input is valid, warning for soft limits, and error for hard failures.
• Add a description or placeholder to clarify expected content, like "Describe the issue in detail," but never rely on placeholder alone as the only label.
• 避免：Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.
• 避免：Don't rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.
• 避免：Don't show a status message without also setting the status type; the colored border and icon are what draw the user's attention to the message.
• 避免：Don't wrap a disabled TextArea 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-area",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled",
        "readonly"
      ]
    },
    {
      "className": "astryx-text-area-control"
    },
    {
      "className": "astryx-text-area-counter"
    }
  ],
  "vars": [
    {
      "name": "--_textarea-inline-padding",
      "description": "文本域文本的行内内边距。外层容器保持无内边距（padding: 0），使原生缩放手柄位于真正的角落；该变量在内部 <textarea> 上承载内边距，起始图标、状态/加载指示器和字符计数器都与之对齐。",
      "default": "var(--spacing-2)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "paddingInline",
      "vars": [
        "--_textarea-inline-padding"
      ],
      "replaces": true
    }
  ]
}

组件结构

• Label: Text identifying the multi-line field.
• Description: Helper text between the label and the input.
• Input container: Painted boundary containing the text area and its overlays.
• Text area: Multi-line control that displays and edits the value.
• Placeholder: Hint text shown inside the empty text area.
• Start icon: Astryx Icon rendered at the start when startIcon is a semantic name or icon component.
• Custom start content: Caller-provided ReactNode rendered at the start instead of an Astryx Icon.
• Spinner: Loading indicator shown at the end of the input container.
• Status icon: Error, warning, or success icon shown inside the input.
• Character counter: Current and maximum character counts shown inside the input container.
• Field status message: Attached or detached error, warning, or success message associated with the field.
• Tooltip status message: Tooltip surface presenting the status message for the tooltip variant.

完整示例的额外依赖

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

npm install @heroicons/react@2.2.0