InputArea
@cloudflare/kumo

InputArea

支持多行文本输入的组件，内置标签、描述和错误提示支持。

Provide details about your project

import { InputArea } from "@cloudflare/kumo";

export function InputAreaBasicDemo() {
  return (
    <InputArea
      label="Description"
      placeholder="Enter a description..."
      description="Provide details about your project"
    />
  );
}

安装

桶式导入

import { InputArea } from "@cloudflare/kumo";

子路径导入

import { InputArea } from "@cloudflare/kumo/components/input";

Textarea 也作为 InputArea 的别名导出，方便从其他库迁移时查找。

用法

使用内置 Field（推荐）

使用 label 属性启用内置 Field 包装器，支持标签、描述和错误提示。

import { InputArea } from "@cloudflare/kumo";

export default function Example() {
  return (
    <InputArea
      label="Description"
      placeholder="Enter a description..."
      description="Provide details about your project"
    />
  );
}

裸 InputArea（自定义布局）

对于自定义表单布局，可在不带 label 的情况下使用 InputArea，但必须提供 aria-label 或 aria-labelledby 以保证无障碍访问。

import { InputArea } from "@cloudflare/kumo";

export default function Example() {
  return <InputArea placeholder="Add notes..." aria-label="Notes" rows={3} />;
}

示例

带标签

Max 500 characters

import { InputArea } from "@cloudflare/kumo";

export function InputAreaWithLabelDemo() {
  return (
    <InputArea
      label="Bio"
      placeholder="Tell us about yourself"
      description="Max 500 characters"
    />
  );
}

自定义行数

使用 rows 属性控制初始高度。

import { InputArea } from "@cloudflare/kumo";

export function InputAreaRowsDemo() {
  return (
    <div className="flex flex-col gap-4">
      <InputArea label="2 rows" placeholder="Small area" rows={2} />
      <InputArea label="4 rows (default)" placeholder="Medium area" rows={4} />
      <InputArea label="8 rows" placeholder="Large area" rows={8} />
    </div>
  );
}

错误状态（字符串）

当 error 属性为真时，会自动应用错误样式。

Message must be at least 10 characters
import { InputArea } from "@cloudflare/kumo";

export function InputAreaErrorStringDemo() {
  return (
    <InputArea
      label="Message"
      placeholder="Enter your message"
      value="Hi"
      error="Message must be at least 10 characters"
    />
  );
}

错误状态（对象）

可使用包含 match 的错误对象进行约束校验。

import { InputArea } from "@cloudflare/kumo";

export function InputAreaErrorObjectDemo() {
  return (
    <InputArea
      label="Feedback"
      value="Bad"
      error={{
        message: "Feedback must be at least 20 characters",
        match: "tooShort",
      }}
      minLength={20}
    />
  );
}

尺寸

四种尺寸可选：xs、sm、base（默认）、lg。

import { InputArea } from "@cloudflare/kumo";

export function InputAreaSizesDemo() {
  return (
    <div className="flex flex-col gap-4">
      <InputArea
        size="xs"
        label="Extra Small"
        placeholder="Extra small textarea"
      />
      <InputArea size="sm" label="Small" placeholder="Small textarea" />
      <InputArea label="Base" placeholder="Base textarea (default)" />
      <InputArea size="lg" label="Large" placeholder="Large textarea" />
    </div>
  );
}

禁用

import { InputArea } from "@cloudflare/kumo";

export function InputAreaDisabledDemo() {
  return (
    <InputArea label="Disabled field" placeholder="Cannot edit" disabled />
  );
}

自动调整大小

使用 autoResize 可让文本区域在用户输入或粘贴多行内容时自动垂直增高。 minRows 设置最小高度，可选的 maxRows 限制最大高度，超出上限的内容会滚动显示。

Resizes vertically with content size, up to 8 rows

import { InputArea } from "@cloudflare/kumo";

export function InputAreaAutoResizeDemo() {
  return (
    <InputArea
      label="Configuration value"
      defaultValue={
        "Review the configuration changes.\n\nAdd follow-up notes here.\n\n"
      }
      autoResize
      minRows={2}
      maxRows={8}
      description="Resizes vertically with content size, up to 8 rows"
    />
  );
}

裸 InputArea

不带 label 的 InputArea 会渲染为裸文本区域，必须提供 aria-label 以保证无障碍访问。

import { InputArea } from "@cloudflare/kumo";

export function InputAreaBareDemo() {
  return <InputArea placeholder="Add notes..." aria-label="Notes" rows={3} />;
}

可选字段

设置 required={false} 会在标签后显示“（可选）”文本。

import { InputArea } from "@cloudflare/kumo";

export function InputAreaOptionalFieldDemo() {
  return (
    <InputArea
      label="Additional Notes"
      required={false}
      placeholder="Any additional information..."
    />
  );
}

带提示的标签

使用 labelTooltip 添加一个信息图标，悬停时可显示更多上下文说明。

import { InputArea } from "@cloudflare/kumo";

export function InputAreaLabelTooltipDemo() {
  return (
    <InputArea
      label="Worker Script"
      labelTooltip="Enter your Cloudflare Worker script code here"
      placeholder="export default { async fetch(request) { ... } }"
      rows={4}
    />
  );
}

React Node 标签

label 属性接受 ReactNode，支持富文本格式。

import { InputArea } from "@cloudflare/kumo";

export function InputAreaReactNodeLabelDemo() {
  return (
    <InputArea
      label={
        <span>
          Notes for <strong>review</strong>
        </span>
      }
      required
      placeholder="Add notes for the reviewer..."
      rows={3}
    />
  );
}

API 参考

InputArea 接受所有标准 HTML textarea 属性，以及以下属性：

PropTypeDefaultDescription
size"xs" | "sm" | "base" | "lg""base"Input size. - `"xs"` — Extra small for compact UIs - `"sm"` — Small for secondary fields - `"base"` — Default size - `"lg"` — Large for prominent fields
variant"default" | "error""default"Visual variant of the textarea.
labelReactNode-Label content for the textarea (enables Field wrapper) — can be a string or any React node.
labelTooltipReactNode-Tooltip content to display next to the label via an info icon.
descriptionReactNode-Helper text displayed below the textarea.
errorstring | { message: ReactNode; match: FieldErrorMatch }-Error message or validation error object.
autoResizebooleanfalseAutomatically resize the textarea based on its content.
minRowsnumber1Minimum number of rows to display when `autoResize` is enabled.
maxRowsnumber-Maximum number of rows to grow to when `autoResize` is enabled; content beyond this scrolls.
onValueChange(value: string) => void-Callback fired with the new string value on every change.

无障碍

标签要求

InputArea 需要满足以下任一方式提供可访问名称：

  • label 属性（推荐）
  • 对于裸文本区域，使用 placeholder + aria-label
  • 使用 aria-labelledby 进行自定义标签关联

开发环境下，缺少可访问名称会触发控制台警告。

错误关联

错误信息会通过 ARIA 属性自动关联到文本区域，供屏幕阅读器播报。