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 的别名导出，方便从其他库迁移时更容易找到。

用法

使用内置字段 (推荐)

使用 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}
    />
  );
}

ReactNode 标签

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 属性，以及以下属性：

属性类型默认值说明
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 属性自动与文本框关联， 以便屏幕阅读器播报。