Label 标签

默认标签可选标签(optional)带工具提示的标签翻译后的标签（可选）带工具提示的标签

import { Label, LarkLocaleProvider } from "@lark-ui/core";

export function LabelBasicDemo() {
  return (
    <div className="flex flex-col gap-4">
      <Label>默认标签</Label>
      <Label showOptional>可选标签</Label>
      <Label tooltip="关于此字段的更多信息">带工具提示的标签</Label>
      <LarkLocaleProvider
        translations={{
          label: {
            optional: "（可选）",
            tooltip: "更多信息",
          },
        }}
      >
        <Label showOptional>翻译后的标签</Label>
        <Label tooltip="关于此字段的更多信息">带工具提示的标签</Label>
      </LarkLocaleProvider>
    </div>
  );
}

安装

统一导出

import { Label } from "@lark-ui/core";

按需导出

import { Label } from "@lark-ui/core/components/label";

用法

与表单组件搭配使用（推荐）

通过 Input、Select、Checkbox、Switch 等表单组件的 required 和 labelTooltip 属性，可以直接使用标签（Label）的各项能力。

import { Input } from "@lark-ui/core";

export default function Example() {
  return (
    <>
      {/* Optional field with "(optional)" text */}
      <Input label="Phone" required={false} placeholder="+1 555-0000" />

      {/* With tooltip */}
      <Input
        label="API Key"
        labelTooltip="Find this in your dashboard settings"
      />
    </>
  );
}

独立使用 Label

在自定义表单布局中，请直接使用 Label 组件。

import { Label } from "@lark-ui/core";

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

示例

可选字段

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

手机号码(optional)

import { Input } from "@lark-ui/core";

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

带工具提示

显示一个带工具提示的信息图标，用于提供补充说明。

API 密钥

import { Input } from "@lark-ui/core";

export function LabelWithTooltipDemo() {
  return (
    <Input
      label="API 密钥"
      labelTooltip="可在仪表盘设置的 API > 密钥中找到"
      placeholder="sk_live_..."
    />
  );
}

ReactNode 标签内容

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

我同意 服务条款

import { Checkbox } from "@lark-ui/core";

export function LabelReactNodeDemo() {
  return (
    <Checkbox
      label={
        <span>
          我同意 <strong>服务条款</strong>
        </span>
      }
    />
  );
}

混合必填与可选的表单

展示必填字段与可选字段并存的真实示例。

姓名

邮箱

公司(optional)

国家/地区

import { Input, Select } from "@lark-ui/core";

export function LabelFormMixedDemo() {
  return (
    <div className="flex max-w-md flex-col gap-4">
      <Input label="姓名" placeholder="John Doe" />
      <Input
        label="邮箱"
        labelTooltip="收据会发送到这个邮箱"
        placeholder="john@example.com"
        type="email"
      />
      <Input label="公司" required={false} placeholder="Acme Inc." />
      <Select label="国家/地区" placeholder="请选择国家/地区">
        <Select.Option value="us">美国</Select.Option>
        <Select.Option value="uk">英国</Select.Option>
        <Select.Option value="ca">加拿大</Select.Option>
      </Select>
    </div>
  );
}

独立使用 Label

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

默认可选(optional)带工具提示

import { Label } from "@lark-ui/core";

export function LabelStandaloneDemo() {
  return (
    <div className="flex flex-col gap-3">
      <Label>默认</Label>
      <Label showOptional>可选</Label>
      <Label tooltip="重要字段">带工具提示</Label>
    </div>
  );
}

API 参考

Label 属性

独立使用 Label 组件时的属性：

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

表单组件的标签属性

以下属性适用于 Input、InputArea、Select、Checkbox、Switch、SensitiveInput 和 Combobox：

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

设计规范

何时使用可选标识

当大多数字段都是必填时，为可选字段标注”(optional)“
同一个表单内保持一致
默认字段（无标识）会被用户理解为必填

何时使用工具提示

提供无法放进标签里的补充说明
说明格式要求或校验规则
为复杂字段提供帮助文档链接
工具提示内容要简洁——最多 1-2 句话

无障碍

可选标识仅用于视觉提示——校验请使用 required 属性
工具提示可通过键盘聚焦信息图标来访问
聚焦时，屏幕阅读器会播报工具提示内容