组件导航

Radio

radio

单选 · RadioGroup 单选组 + 键盘方向键

用法

基础用法

RadioGroup 包裹多个 Radio，单选互斥，默认纵向排列。

选项一选项二选项三

tsx

<RadioGroup defaultValue="b" aria-label="选项">
  <Radio value="a" label="选项一" />
  <Radio value="b" label="选项二" />
  <Radio value="c" label="选项三" />
</RadioGroup>

横向排列

设置 orientation="horizontal" 让选项横向排布。

男女

tsx

<RadioGroup orientation="horizontal" defaultValue="m" aria-label="性别">
  <Radio value="m" label="男" />
  <Radio value="f" label="女" />
</RadioGroup>

禁用

单个 Radio 加 disabled 禁用某项；整组 disabled 禁用全部。

标准专业（暂不可选）旗舰

tsx

<RadioGroup defaultValue="a" aria-label="套餐">
  <Radio value="a" label="标准" />
  <Radio value="b" label="专业（暂不可选）" disabled />
  <Radio value="c" label="旗舰" />
</RadioGroup>

搭配 Field 校验

包进 Field 获得标签与错误提示，校验态会传导到圈描边。

套餐

基础版增强版

请选择一个套餐

tsx

<Field label="套餐" error="请选择一个套餐" className="w-72">
  <RadioGroup defaultValue="">
    <Radio value="basic" label="基础版" />
    <Radio value="plus" label="增强版" />
  </RadioGroup>
</Field>

何时用

一组互斥选项里选且只选一个、且选项数少（约 2–6 个）需全部直接可见时用。选项多需收起或搜索改用 Select；多选共存改用 CheckboxGroup；横向二三段且要滑块视觉用 Segmented。

导入

import { RadioGroup, Radio } from "@hulianui/ui"

Props

RadioGroup

名称	类型	默认	说明
value	`string`	—	受控选中值
defaultValue	`string`	—	非受控初始选中值
disabled	`boolean`	`false`	整组禁用
required	`boolean`	—	表单必选
name	`string`	—	原生表单 name
orientation	`"vertical"｜"horizontal"`	`"vertical"`	仅控布局
className	`string`	—	—
aria-label	`string`	—	无可见标题时提供

Radio

名称	类型	默认	说明
value *	`string`	—	必填，标识该选项
disabled	`boolean`	`false`	单项禁用
id	`string`	—	—
className	`string`	—	落在 Radio.Root
aria-label	`string`	—	无障碍名。不给 `label`、或 `label` 是图标/纯视觉内容时必须给
aria-labelledby	`string`	—	用页面上已有元素充当名字（填其 id），与 `aria-label` 二选一
aria-describedby	`string`	—	补充描述（填元素 id），如该选项的说明文字

Events

RadioGroup

事件	类型	说明
onValueChange	`(value: string) => void`	选中变化回调

Slots

RadioGroup

插槽	类型	说明
children	`ReactNode`	内放 `Radio` 项

Radio

插槽	类型	说明
label	`ReactNode`	可选 inline label（点右，原生 `<label>` 关联）

禁忌 / 坑

选中值统一由 RadioGroup 管，Radio 不自带选中态——别在 Radio 上找 checked。
用 value/onValueChange 即受控，须自管 state；只给初值用 defaultValue，二者不要混用。
无可见标题的单选组要给 aria-label，否则无障碍读屏无名。
不给 `label` 的 `Radio`（图标卡片、自定义排版）必须自带 `aria-label` 或 `aria-labelledby`，否则读屏只报「单选按钮」，用户不知道自己在选哪一项——这不只是测试不好写，是真实的可访问性缺陷。label 传的是图标之类的非文本 ReactNode 时同理。

Playground

排列disabled

标准专业旗舰

<RadioGroup orientation="vertical" defaultValue="standard">
  <Radio value="standard" label="标准" />
  <Radio value="pro" label="专业" />
</RadioGroup>

Radio

radio

单选 · RadioGroup 单选组 + 键盘方向键

用法

基础用法

RadioGroup 包裹多个 Radio，单选互斥，默认纵向排列。

选项一选项二选项三

tsx

<RadioGroup defaultValue="b" aria-label="选项">
  <Radio value="a" label="选项一" />
  <Radio value="b" label="选项二" />
  <Radio value="c" label="选项三" />
</RadioGroup>

横向排列

设置 orientation="horizontal" 让选项横向排布。

男女

tsx

<RadioGroup orientation="horizontal" defaultValue="m" aria-label="性别">
  <Radio value="m" label="男" />
  <Radio value="f" label="女" />
</RadioGroup>

禁用

单个 Radio 加 disabled 禁用某项；整组 disabled 禁用全部。

标准专业（暂不可选）旗舰

tsx

<RadioGroup defaultValue="a" aria-label="套餐">
  <Radio value="a" label="标准" />
  <Radio value="b" label="专业（暂不可选）" disabled />
  <Radio value="c" label="旗舰" />
</RadioGroup>

搭配 Field 校验

包进 Field 获得标签与错误提示，校验态会传导到圈描边。

套餐

基础版增强版

请选择一个套餐

tsx

<Field label="套餐" error="请选择一个套餐" className="w-72">
  <RadioGroup defaultValue="">
    <Radio value="basic" label="基础版" />
    <Radio value="plus" label="增强版" />
  </RadioGroup>
</Field>

何时用

导入

import { RadioGroup, Radio } from "@hulianui/ui"

Props

RadioGroup

名称	类型	默认	说明
value	`string`	—	受控选中值
defaultValue	`string`	—	非受控初始选中值
disabled	`boolean`	`false`	整组禁用
required	`boolean`	—	表单必选
name	`string`	—	原生表单 name
orientation	`"vertical"｜"horizontal"`	`"vertical"`	仅控布局
className	`string`	—	—
aria-label	`string`	—	无可见标题时提供

Radio

名称	类型	默认	说明
value *	`string`	—	必填，标识该选项
disabled	`boolean`	`false`	单项禁用
id	`string`	—	—
className	`string`	—	落在 Radio.Root
aria-label	`string`	—	无障碍名。不给 `label`、或 `label` 是图标/纯视觉内容时必须给
aria-labelledby	`string`	—	用页面上已有元素充当名字（填其 id），与 `aria-label` 二选一
aria-describedby	`string`	—	补充描述（填元素 id），如该选项的说明文字

Events

RadioGroup

事件	类型	说明
onValueChange	`(value: string) => void`	选中变化回调

Slots

RadioGroup

插槽	类型	说明
children	`ReactNode`	内放 `Radio` 项

Radio

插槽	类型	说明
label	`ReactNode`	可选 inline label（点右，原生 `<label>` 关联）

禁忌 / 坑

选中值统一由 RadioGroup 管，Radio 不自带选中态——别在 Radio 上找 checked。
用 value/onValueChange 即受控，须自管 state；只给初值用 defaultValue，二者不要混用。
无可见标题的单选组要给 aria-label，否则无障碍读屏无名。
不给 `label` 的 `Radio`（图标卡片、自定义排版）必须自带 `aria-label` 或 `aria-labelledby`，否则读屏只报「单选按钮」，用户不知道自己在选哪一项——这不只是测试不好写，是真实的可访问性缺陷。label 传的是图标之类的非文本 ReactNode 时同理。

Playground

排列disabled

标准专业旗舰

<RadioGroup orientation="vertical" defaultValue="standard">
  <Radio value="standard" label="标准" />
  <Radio value="pro" label="专业" />
</RadioGroup>

Radio

用法

基础用法

横向排列

禁用

搭配 Field 校验

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

Radio

用法

基础用法

横向排列

禁用

搭配 Field 校验

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground