单选组 radio-group

数据录入组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

collection 是条目的事实源，交一组数据即铺开整组；组内只有一个 Tab 停靠点，进组后四个方向键都能切换

套餐

免费版

标准版

专业版

<script setup lang="ts">
import { XhRadioGroupRoot } from "@xihan-ui/vue";

const plans = [
  { value: "free", label: "免费版" },
  { value: "standard", label: "标准版" },
  { value: "pro", label: "专业版" },
];
</script>

<template>
  <XhRadioGroupRoot
    :collection="plans"
    default-value="standard"
    label="套餐"
    name="plan"
  />
</template>

受控

传了 value 就由宿主说了算；值可以是 null，表示一项都没选中

套餐

免费版

标准版

当前：free

<script setup lang="ts">
import { ref } from "vue";
import {
  XhRadioGroupItem,
  XhRadioGroupItemText,
  XhRadioGroupLabel,
  XhRadioGroupRoot,
} from "@xihan-ui/vue";

const plan = ref<string | null>("free");
</script>

<template>
  <XhRadioGroupRoot v-model:value="plan">
    <XhRadioGroupLabel>套餐</XhRadioGroupLabel>
    <XhRadioGroupItem value="free">
      <XhRadioGroupItemText>免费版</XhRadioGroupItemText>
    </XhRadioGroupItem>
    <XhRadioGroupItem value="standard">
      <XhRadioGroupItemText>标准版</XhRadioGroupItemText>
    </XhRadioGroupItem>
  </XhRadioGroupRoot>
  <span>当前：{{ plan ?? "（未选）" }}</span>
  <button type="button" @click="plan = null">清空</button>
</template>

横向排布

orientation 只影响排版与 aria-orientation，方向键四个方向照样都能切换

尺寸

小

中

大

<script setup lang="ts">
import { XhRadioGroupRoot } from "@xihan-ui/vue";

const sizes = [
  { value: "sm", label: "小" },
  { value: "md", label: "中" },
  { value: "lg", label: "大" },
];
</script>

<template>
  <XhRadioGroupRoot
    :collection="sizes"
    default-value="md"
    label="尺寸"
    orientation="horizontal"
  />
</template>

禁用

单项禁用后点不动，方向键也跳过它；整组禁用则每一项都跟着禁用

单项禁用

免费版

专业版

整组禁用

免费版

专业版

<script setup lang="ts">
import { XhRadioGroupRoot } from "@xihan-ui/vue";

const plans = [
  { value: "free", label: "免费版" },
  { value: "pro", label: "专业版", disabled: true },
];
const openPlans = [
  { value: "free", label: "免费版" },
  { value: "pro", label: "专业版" },
];
</script>

<template>
  <XhRadioGroupRoot :collection="plans" default-value="free" label="单项禁用" />

  <XhRadioGroupRoot
    :collection="openPlans"
    default-value="free"
    disabled
    label="整组禁用"
  />
</template>

语气

tone 决定选中圆点用哪族颜色，六种语气各一组

brand

选中

未选

neutral

选中

未选

success

选中

未选

warning

选中

未选

danger

选中

未选

info

选中

未选

<script setup lang="ts">
import { XhRadioGroupRoot } from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
const answers = [
  { value: "yes", label: "选中" },
  { value: "no", label: "未选" },
];
</script>

<template>
  <div style="display: flex; gap: 32px; flex-wrap: wrap">
    <XhRadioGroupRoot
      v-for="t in tones"
      :key="t"
      :collection="answers"
      :label="t"
      :tone="t"
      default-value="yes"
    />
  </div>
</template>

尺寸

size 改条目间距与字号，不写即缺省中档

sm

免费版

标准版

缺省

免费版

标准版

lg

免费版

标准版

<script setup lang="ts">
import { XhRadioGroupRoot } from "@xihan-ui/vue";

const plans = [
  { value: "free", label: "免费版" },
  { value: "standard", label: "标准版" },
];
</script>

<template>
  <div style="display: flex; gap: 32px; flex-wrap: wrap; align-items: flex-start">
    <XhRadioGroupRoot
      :collection="plans"
      default-value="standard"
      label="sm"
      size="sm"
    />

    <XhRadioGroupRoot :collection="plans" default-value="standard" label="缺省" />

    <XhRadioGroupRoot
      :collection="plans"
      default-value="standard"
      label="lg"
      size="lg"
    />
  </div>
</template>

数据驱动

自家字段叫什么由数据定，映射成 collection 的 value / label / disabled 即可

优先级

紧急

高

普通

低

当前：p1

<script setup lang="ts">
import { computed, ref } from "vue";
import { XhRadioGroupRoot } from "@xihan-ui/vue";

const level = ref<string | null>("p1");
const levels = [
  { code: "p0", text: "紧急", locked: false },
  { code: "p1", text: "高", locked: false },
  { code: "p2", text: "普通", locked: false },
  { code: "p3", text: "低", locked: true },
];
const collection = computed(() =>
  levels.map((lv) => ({ value: lv.code, label: lv.text, disabled: lv.locked }))
);
</script>

<template>
  <XhRadioGroupRoot
    v-model:value="level"
    :collection="collection"
    label="优先级"
    name="level"
    orientation="horizontal"
  />
  <span>当前：{{ level ?? "（未选）" }}</span>
</template>

产物

层	值
自定义元素	<xh-radio-group>
Vue 组件	XhRadioGroupItem XhRadioGroupItemText XhRadioGroupLabel XhRadioGroupRoot
组合式函数	useRadioGroup
状态机	radioGroupMachine
皮肤	@xihan-ui/styles/radio-group.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="radio-group"：root · label · item · item-text · indicator · hidden-input

Props

属性	类型	必填	说明
collection	RadioGroupNode[]		条目数据，显示文本与禁用的事实源。给了它，条目部件只需报 value。 缺省即回到「文本与禁用都写在条目部件上」的老路。
value	string | null
defaultValue	string | null
disabled	boolean
orientation	Orientation
dir	Direction		文字方向，缺省 'ltr'。
name	string		表单字段名。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色。
size	Size		尺寸：sm / md / lg。
onValueChange	(details: RadioGroupValueChangeDetails) => void		value 变化回调。

状态机

状态：idle

事件：VALUE.SET · ITEM.SELECT · ITEM.FOCUS · GROUP.BLUR · FORM.RESET

connect API

useRadioGroup 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
value	string | null
collection	readonly RadioGroupNodeMeta[]	collection 推出的条目元信息，按数据顺序排列；没给 collection 即空数组。
focusedValue	string | null	焦点在组外时为 null。
setValue	(next: string) => void
getRootProps	() => T['element']
getLabelProps	() => T['element']
getItemProps	(props: RadioGroupItemProps) => T['element']
getItemTextProps	(props: RadioGroupItemProps) => T['element']
getIndicatorProps	(props: RadioGroupItemProps) => T['element']
getHiddenInputProps	(props: RadioGroupItemProps) => T['input']	条目对应的隐藏原生 radio 输入，用于表单提交。

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab / Shift+Tab	focus outside the group	整组只占一个 Tab 位：焦点进入锚点条目（即选中项）；落到容器上时由容器转投锚点条目，锚点缺席或被禁用才落首个可停留项
ArrowDown / ArrowRight	focus in group, group not disabled	焦点移到下一个可停留条目并选中，末项回绕到首项；dir=rtl 时改由 ArrowLeft 承担
ArrowUp / ArrowLeft	focus in group, group not disabled	焦点移到上一个可停留条目并选中，首项回绕到末项；dir=rtl 时改由 ArrowRight 承担
Space	focus on item, item not disabled	选中当前条目