Label - Kumo 中文文档

Default LabelOptional Label(optional)Label with TooltipRótulo traduzido(opcional)Rótulo com dica

import { Label, KumoLocaleProvider } from "@cloudflare/kumo";

export function LabelBasicDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Label>Default Label</Label>
      <Label showOptional>Optional Label</Label>
      <Label tooltip="More information about this field">
        Label with Tooltip
      </Label>
      <KumoLocaleProvider
        translations={{
          label: {
            optional: "(opcional)",
            tooltip: "Mais informações",
          },
        }}
      >
        <Label showOptional>Rótulo traduzido</Label>
        <Label tooltip="Mais informações sobre este campo">
          Rótulo com dica
        </Label>
      </KumoLocaleProvider>
    </div>
  );
}

安装

批量导入

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

细粒度导入

import { Label } from "@cloudflare/kumo/components/label";

用法

配合表单组件使用 (推荐)

通过 Input、Select、Checkbox、Switch 等表单组件的 required 和 labelTooltip 属性，可自动获得 Label 的各项功能。

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

export default function Example() {
  return (
    <>
      {/* 选填字段，显示 "(optional)" 文案 */}
      <Input label="Phone" required={false} placeholder="+1 555-0000" />

      {/* 带工具提示 */}
      <Input
        label="API Key"
        labelTooltip="Find this in your dashboard settings"
      />
    </>
  );
}

独立 Label

对于自定义表单布局，可直接使用 Label 组件。

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

export default function Example() {
  return <Label tooltip="This field is mandatory">Username</Label>;
}

示例

选填字段

当 required={false} 时，显示灰色的 “(optional)” 文案。

Phone Number(optional)

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

export function LabelOptionalFieldDemo() {
  return (
    <Input label="Phone Number" required={false} placeholder="+1 555-0000" />
  );
}

显示一个带工具提示的信息图标，用于补充上下文。

API Key

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

export function LabelWithTooltipDemo() {
  return (
    <Input
      label="API Key"
      labelTooltip="Find this in your dashboard settings under API > Keys"
      placeholder="sk_live_..."
    />
  );
}

ReactNode 标签内容

标签支持 ReactNode 内容，便于做富文本格式化。

I agree to the Terms of Service

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

export function LabelReactNodeDemo() {
  return (
    <Checkbox
      label={
        <span>
          I agree to the <strong>Terms of Service</strong>
        </span>
      }
    />
  );
}

混合字段表单

真实示例，同时展示必填与选填字段。

Full Name

Company(optional)

Country

import { Input, Select } from "@cloudflare/kumo";

export function LabelFormMixedDemo() {
  return (
    <div className="flex max-w-md flex-col gap-4">
      <Input label="Full Name" placeholder="John Doe" />
      <Input
        label="Email"
        labelTooltip="We'll send your receipt here"
        placeholder="john@example.com"
        type="email"
      />
      <Input label="Company" required={false} placeholder="Acme Inc." />
      <Select label="Country" placeholder="Select a country">
        <Select.Option value="us">United States</Select.Option>
        <Select.Option value="uk">United Kingdom</Select.Option>
        <Select.Option value="ca">Canada</Select.Option>
      </Select>
    </div>
  );
}

独立 Label

在自定义布局或非表单场景中可直接使用 Label。

DefaultOptional(optional)With Tooltip

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

export function LabelStandaloneDemo() {
  return (
    <div className="flex flex-col gap-3">
      <Label>Default</Label>
      <Label showOptional>Optional</Label>
      <Label tooltip="Important field">With Tooltip</Label>
    </div>
  );
}

API 参考

Label 属性

独立 Label 组件的属性：

属性	类型	默认值	说明
children	ReactNode	-	标签内容 (必填)
showOptional	boolean	false	显示灰色的 “(optional)” 文案 (仅在 required 为 false 时)
tooltip	ReactNode	-	通过信息图标展示的工具提示内容
className	string	-	附加的 CSS 类

表单组件的 Label 属性

以下属性可在 Input、InputArea、Select、Checkbox、Switch、 SensitiveInput 和 Combobox 上使用：

属性	类型	默认值	说明
label	ReactNode	-	标签内容 (启用 Field 包装器)
required	boolean	-	为 false 时：显示 “(optional)” 文案。同时设置 HTML 的 required 属性。
labelTooltip	ReactNode	-	通过标签旁的信息图标展示的工具提示内容

设计指南

何时使用选填指示

当大多数字段为必填时，为选填字段使用 “(optional)“
在同一表单内保持一致
默认字段 (无指示) 会被用户视为必填

何时使用工具提示

提供标签中放不下的补充上下文
解释格式要求或校验规则
为复杂字段链接到帮助文档
工具提示内容保持简洁——最多 1-2 句话

无障碍

选填指示纯属视觉——校验请使用 required 属性
聚焦到信息图标即可通过键盘访问工具提示
屏幕阅读器会在聚焦时朗读工具提示内容