u

code/g3soft-libs/docs/content/ui/3.form/radio.md

@@ -0,0 +1,106 @@
+---
+title: Radio 单选框
+description: 与 RadioGroup 组合使用，在一组选项里选中一个
+---
+
+# Radio 单选框
+
+`G3Radio` 必须放在 `G3RadioGroup` 里才能互斥。组负责值、禁用与 `name`，单选项只声明自己的 `value` 和内容。
+
+## 何时使用
+
+- 选项少（2-5 个）且需要**一次看全**时，比 [Select](/ui/form/select) 更快；
+- 选项是互斥的、必须选一个时使用；可以不选时用 Select 更合适；
+- 选项超过 5 个、或需要展示更多信息时，用 Select；
+- 只是控制某个功能的开与关，用 [Switch](/ui/form/switch)。
+
+## 基础用法
+
+:::demo{name="radio/basic"}
+:::
+
+组会自动生成唯一的原生 `name`（`useId`），因此同页多组之间不会互相干扰，键盘方向键也能在组内来回切换。
+
+## 纵向排列与整组禁用
+
+组默认是水平换行的 `inline-flex`；纵向排列用外部 `style` 改 `flex-direction`，或给组包一层纵向容器。
+
+:::demo{name="radio/vertical"}
+:::
+
+## 卡片式选择
+
+默认插槽可以放任意内容，配合 `style` 就能做成卡片选择器（常见于套餐、模板选择）。
+
+:::demo{name="radio/cards"}
+:::
+
+## API
+
+### Props（Radio）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `value` | `string \| number \| boolean` | **必填** | 选项值。与组 `modelValue` 做 `Object.is` 比较决定是否选中 |
+| `disabled` | `boolean` | `false` | 单独禁用该项（组禁用时以组为准） |
+
+### Props（RadioGroup）
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `string \| number \| boolean` | — | 双向绑定的选中值 |
+| `disabled` | `boolean` | `false` | 禁用整组 |
+| `name` | `string` | 自动生成 | 原生 radio 组名，不传时用 `useId` 生成 |
+
+### Events（RadioGroup）
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| `update:modelValue` | `(value: string \| number \| boolean)` | 选中项变化 |
+| `change` | `(value: string \| number \| boolean)` | 同上，便于只监听变化 |
+
+### Slots
+
+| 组件 | 插槽 | 说明 |
+| --- | --- | --- |
+| Radio | `default` | 选项文案，可放富内容 |
+| RadioGroup | `default` | 组内的 `G3Radio` 列表 |
+
+### 类型定义
+
+```ts
+export type RadioValue = string | number | boolean
+
+export interface RadioProps {
+  value: RadioValue
+  disabled?: boolean
+}
+
+export interface RadioGroupProps {
+  modelValue?: RadioValue
+  disabled?: boolean
+  name?: string
+}
+
+export interface RadioGroupContext {
+  name: ComputedRef<string | undefined>
+  modelValue: ComputedRef<RadioValue | undefined>
+  disabled: ComputedRef<boolean>
+  select: (value: RadioValue) => void
+}
+```
+
+### 样式变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--g3-radio-size` | `16px` | 圆圈直径 |
+| `--g3-color-primary` | `#18181b` | 选中态边框与内点 |
+| `--g3-bg-disabled` / `--g3-text-disabled` | `rgba(0,0,0,.04 / .25)` | 禁用态 |
+
+## 实现说明
+
+- 底层同样是原生 `input[type=radio]`：组用 `<div>` 包裹、每项用 `<label>` 包裹，浏览器原生提供「组内互斥 + 方向键切换」；
+- 选中判断用 `Object.is`（而不是 `===`），这样 `NaN` 之类的值也能正确比较；
+- 组上下文通过 `provide` 下发：`{ name, modelValue, disabled, select }`，单选项目通过 `inject` 读取；**脱离组单独使用时**会退化为「永不选中」的原生 radio（不会报错，但也不会有选中态），因此务必成对使用；
+- 未显式传 `name` 时用 `useId` 生成组名，避免同页多个 radio 组因为浏览器按 `name` 分组而互相影响。