输入类

单选框

用户使用单选框来从少量的选项集合中选择单个选项

使用场景

单选框(Radio)也叫单选按钮,它允许用户在一组选项中选择其中一个。
当选项很多时,单选下拉菜单(Select)可能比较适合,因为它所占用的画面空间比单选按钮来得要少。

代码演示

如何引入

<script lang="ts">
    import { Radio, RadioGroup } from '@fibrae/semi-ui-svelte';
</script>

基本用法

代码
<script lang="ts">
    import { Radio } from '@fibrae/semi-ui-svelte';
</script>

<Radio aria-label="单选示例" name="demo-radio">Radio</Radio>

带辅助文本

通过 extra snippet 设置辅助文本:在 Radio 标签内用 {#snippet extra()}...{/snippet} 定义,其余内容是文本内容,可以放入任意内容

代码
<script lang="ts">
    import { Radio } from '@fibrae/semi-ui-svelte';
</script>

<Radio aria-label="单选示例" name="demo-radio-extra">
    Semi Design
    {#snippet extra()}Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统{/snippet}
</Radio>

禁用

Radio 不可用


代码
<script lang="ts">
    import { Button, Radio } from '@fibrae/semi-ui-svelte';

    let disabled = $state(true);
</script>

<div>
    <Radio aria-label="单选示例" checked={false} {disabled} name="demo-radio-disabled">Disabled</Radio>
    <br />
    <Radio aria-label="单选示例" checked {disabled} name="demo-radio-defaultChecked-disabled">Disabled</Radio>
    <div style="margin-top: 20px">
        <Button type="primary" onclick={() => (disabled = !disabled)}>Toggle disabled</Button>
    </div>
</div>

高级模式

高级模式(mode='advanced')checked 可以通过点击转换为 unchecked。

代码
<script lang="ts">
    import { Radio, type RadioChangeEvent } from '@fibrae/semi-ui-svelte';

    let checked = $state(true);
    const onChange = (e: RadioChangeEvent) => console.log('radio checked', e.target.checked);
</script>

<Radio aria-label="单选示例" bind:checked mode="advanced" name="demo-radio-advanced" {onChange}>允许取消选择</Radio>

单选组合

一组互斥的 Radio 配合使用

代码
<script lang="ts">
    import { Radio, RadioGroup, type RadioChangeEvent, type RadioValue } from '@fibrae/semi-ui-svelte';

    let value = $state<RadioValue | undefined>(1);
    const onChange = (e: RadioChangeEvent) => console.log('radio checked', e.target.value);
</script>

<RadioGroup aria-label="单选组合示例" bind:value name="demo-radio-group" {onChange}>
    <Radio value={1}>A</Radio>
    <Radio value={2}>B</Radio>
    <Radio value={3}>C</Radio>
    <Radio value={4}>D</Radio>
</RadioGroup>

垂直排列

可通过给 RadioGroup 设置 direction属性来决定 组内的 radio 元素水平排列或者垂直排列

代码
<script lang="ts">
    import { Radio, RadioGroup } from '@fibrae/semi-ui-svelte';
</script>

<RadioGroup aria-label="单选组合示例" direction="vertical" name="demo-radio-group-vertical">
    <Radio value={1}>A</Radio>
    <Radio value={2}>B</Radio>
    <Radio value={3}>C</Radio>
    <Radio value={4}>D</Radio>
</RadioGroup>

按钮样式

可以利用 type='button' 来设置 button 样式类型的单选器,并且,button 类型单选器支持三种尺寸大小。

需要注意的是: button 类型的单选器暂不支持辅助文本(extra)和垂直排列(direction='vertical')。

代码
<script lang="ts">
    import { Radio, RadioGroup, Space } from '@fibrae/semi-ui-svelte';

    const sizes = ['small', 'middle', 'large'] as const;
</script>

<Space align="start" spacing="loose" vertical>
    {#each sizes as size (size)}
        <RadioGroup aria-label="单选组合示例" buttonSize={size} name={`demo-radio-${size}`} type="button" value={1}>
            <Radio value={1}>即时推送</Radio>
            <Radio value={2}>定时推送</Radio>
            <Radio value={3}>动态推送</Radio>
        </RadioGroup>
    {/each}
</Space>

卡片样式

可以给 RadioGroup 设置 type='card' 实现带有背景的卡片样式。

代码
<script lang="ts">
    import { Radio, RadioGroup } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
    const items = [
        { value: 1, disabled: true },
        { value: 2, disabled: false },
        { value: 3, disabled: false },
    ];
</script>

<RadioGroup aria-label="单选组合示例" direction="vertical" name="demo-radio-group-card" type="card" value={2}>
    {#each items as item (item.value)}
        <Radio disabled={item.disabled} style="width: 280px" value={item.value}>
            单选框标题
            {#snippet extra()}{extraText}{/snippet}
        </Radio>
    {/each}
</RadioGroup>

无 radio 的纯卡片样式

可以给 RadioGroup 设置 type='pureCard' 实现带有背景且无 radio 的纯卡片样式。

代码
<script lang="ts">
    import { Radio, RadioGroup } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
    const items = [
        { value: 1, disabled: true },
        { value: 2, disabled: false },
        { value: 3, disabled: false },
    ];
</script>

<RadioGroup aria-label="单选组合示例" direction="vertical" name="demo-radio-group-pureCard" type="pureCard" value={2}>
    {#each items as item (item.value)}
        <Radio disabled={item.disabled} style="width: 280px" value={item.value}>
            单选框标题
            {#snippet extra()}{extraText}{/snippet}
        </Radio>
    {/each}
</RadioGroup>

配置 options

通过配置 options 参数来渲染单选框

代码
<script lang="ts">
    import { RadioGroup, Space, type RadioChangeEvent, type RadioValue } from '@fibrae/semi-ui-svelte';

    let value1 = $state<RadioValue | undefined>('Guest');
    let value2 = $state<RadioValue | undefined>('Developer');
    let value3 = $state<RadioValue | undefined>('Maintainer');
    const plainOptions = ['Guest', 'Developer', 'Maintainer'];
    const options = [
        { label: 'Guest', value: 'Guest', extra: 'Semi Design', style: 'width: 120px' },
        { label: 'Developer', value: 'Developer', extra: 'Semi Design', style: 'width: 120px' },
        { label: 'Maintainer', value: 'Maintainer', extra: 'Semi Design', style: 'width: 120px' },
    ];
    const optionsWithDisabled = [
        { label: 'Guest', value: 'Guest' },
        { label: 'Developer', value: 'Developer' },
        { label: 'Maintainer', value: 'Maintainer', disabled: true },
    ];

    const log = (name: string, e: RadioChangeEvent) => console.log(`${name} checked`, e.target.value);
</script>

<Space align="start" spacing="loose" vertical>
    <RadioGroup aria-label="单选组合示例" bind:value={value1} name="demo-radio-group-1" onChange={(e) => log('radio1', e)} options={plainOptions} />
    <RadioGroup aria-label="单选组合示例" bind:value={value2} name="demo-radio-group-2" onChange={(e) => log('radio2', e)} options={optionsWithDisabled} />
    <RadioGroup aria-label="单选组合示例" bind:value={value3} name="demo-radio-group-3" onChange={(e) => log('radio3', e)} {options} />
</Space>

API 参考

Radio

Props

属性说明类型默认值
addonClassName包裹内容容器的类名。string-
addonIdaddon 节点的 id,aria-labelledby 指向这个 id;未设置时随机生成。string-
addonStyle包裹内容容器的内联样式,只接受字符串。string-
checked是否选中,可用 bind:checked 双向绑定;在 RadioGroup 中使用时无效。bind:checked={get, set} 时完全受控;只传 checked 时作为初值,点击在组件内覆盖,父级再传新值时以父级为准。boolean-
childrenRadio 的文本内容 snippet,写在标签内的其余内容就是它。Snippet-
disabled是否禁用。boolean-
displayMode设为 vertical 时 Radio 以块级元素独占一行。RadioDisplayMode-
extra辅助文本的 snippet,aria-describedby 指向它;type 为 button 时不渲染。Snippet-
extraIdextra 节点的 id,aria-describedby 指向这个 id;未设置时随机生成。string-
mode设为 advanced 时,已选中的 Radio 可以通过点击或空格取消选中;在 RadioGroup 中以组的 mode 为准。RadioMode""
onChange选中状态变化时的回调,参数的 target 为 { checked, value, name, disabled }。Type(event: RadioChangeEvent) => void-
prefixClsCSS 类名前缀,未设置时依次取所在 RadioGroup 的值与全局默认值。string-
preventScroll聚焦时是否阻止浏览器滚动到该元素,作用于 focus 方法。boolean-
type样式类型,可选 default、button、card、pureCard;在 RadioGroup 中以组的 type 为准。RadioType"default"
valueRadio 的值,RadioGroup 据此判断是否选中;同时作为原生 input 的 value 参与表单提交。RadioValue-

Methods

方法说明类型
blur使原生 input 失去焦点。Type() => void
focus使原生 input 获得焦点。Type() => void

class、style(字符串)落在根元素 label 上。id、name、tabindex、autofocus、aria-* 与 onfocus、onblur 落在内部的原生 input 上,其余原生属性与事件(如 onmouseenter、onmouseleave)落在根元素上;onclick 也在根元素上,但只在点击落在 input 上时调用一次。checked 支持 bind:、函数绑定、单向传值、不传四种写法,不提供 defaultChecked。extra 在 button 类型下不渲染。

RadioGroup

单选框组合,用于包裹一组 Radio。

Props

属性说明类型默认值
buttonSizetype 为 button 时按钮的尺寸,可选 small、middle、large。RadioGroupButtonSize"middle"
children组内的 Radio;设置 options 时忽略。Snippet-
direction组内 Radio 的排列方向,可选 horizontal 或 vertical;type 为 button 时不支持。RadioDirection"horizontal"
disabled是否禁用整组。booleanfalse
extra自定义 options 中每一项辅助文本的 snippet,参数为 { option, index }。TypeSnippet<[RadioGroupOptionSnippetParams]>-
label自定义 options 中每一项文本的 snippet,参数为 { option, index }。TypeSnippet<[RadioGroupOptionSnippetParams]>-
mode设为 advanced 时,已选中的 Radio 可以通过点击或空格取消选中,此时选中值变为 undefined。RadioMode""
name组内所有原生 input 的 name;未设置时每组生成唯一值。string-
onBlur焦点离开整个分组时的回调,在组内 Radio 之间移动焦点不触发。Type(event: FocusEvent) => void-
onChange选中的值变化时的回调,参数的 target.value 为新的选中值;mode 为 advanced 且取消选中时为 undefined。Type(event: RadioChangeEvent) => void-
options以配置形式声明选项,元素为字符串或 { label, value, disabled, extra, class, style, addonId, addonStyle, addonClass, extraId },其中 style、addonStyle 为字符串。TypeArray<string | RadioOptionItem>-
prefixClsCSS 类名前缀。string-
type组内所有 Radio 的样式类型,可选 default、button、card、pureCard。RadioType"default"
value选中的值,可用 bind:value 双向绑定,与 Radio 的 value 匹配。bind:value={get, set} 时完全受控;只传 value 时作为初值。RadioValue-

options 项的字段为 label、value、disabled、extra(string | number)、class、style(字符串)、addonId、addonStyle(字符串)、addonClass、extraId,没有 onChange;需要自定义内容时使用 label、extra snippet,参数为 { option, index },按钮型不渲染 extra。class、style(字符串)、onBlur 与原生属性落在 role="radiogroup" 的根元素上,aria-required、aria-invalid、aria-errormessage 也落在它上面;onBlur 只在焦点离开整个分组时触发。Tooltip 注入的 aria-expanded、aria-haspopup、aria-controls 与 tabindex 不输出。value 支持 bind:、函数绑定、单向传值、不传四种写法,不提供 defaultValue。

Methods

Radio

通过 bind:this 取得 Radio 实例后调用 focus()、blur(),作用于内部的原生 input;preventScroll 作用于 focus(),说明见上方 Methods。

Accessibility

ARIA

  • aria-label:用于解释 Radio 或 RadioGroup 的作用
  • aria-labelledby 默认指向 addon 节点,用于解释 Radio 的内容
  • aria-describedby 默认指向 extra 节点,用于补充解释 Radio 的内容
  • aria-required、aria-invalid、aria-errormessage 只对 RadioGroup 生效,设置在 role="radiogroup" 的元素上;单个 Radio 的 ARIA 不支持这些属性,同时传入 aria-invalid 与 aria-errormessage 时,错误信息通过 aria-describedby 关联到 input

键盘和焦点

WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton/

  • RadioGroup 可以被获取焦点,初始焦点设置:
    • 当 RadioGroup 中没有被选择项时,初始焦点为第一个 Radio 项上
    • 当 RadioGroup 中有选中项时,初始焦点为选中的 Radio 项上
  • 在同一个 radiogroup 内
    • 可以通过 右箭头 或 下箭头 将焦点移动到下一个 Radio 项上,同时取消先前的 Radio 项的选中状态,并选中当前聚焦的 Radio 项
    • 可以通过 左箭头 或 上箭头 将焦点移动到上一个 Radio 项上,同时取消先前的 Radio 项的选中状态,并选中当前聚焦的 Radio 项
  • 若 RadioGroup 中没有选中项,可以 Space 键选中初始焦点
  • mode="advanced" 仍然是 radio:方向键照常移动选中项,对已选中的项点击或按 Space 可取消选中。

文案规范

  • 首字母大写
  • 不使用标点符号

设计变量

下表是组件内部的 Sass 变量,不能覆写。定制样式请覆写 --semi-* CSS 变量(见 Design Token 页),或写不分层的 CSS 规则。
Sass 变量值用法
$transition_duration-radio-bgvar(--semi-transition_duration-none)单选框-背景色-动画持续时间
$transition_function-radio-bgvar(--semi-transition_function-easeIn)单选框-背景色-过渡曲线
$transition_delay-radio-bgvar(--semi-transition_delay-none)单选框-背景色-延迟时间
$transition_duration-radio-bordervar(--semi-transition_duration-none)单选框-边框-动画持续时间
$transition_function-radio-bordervar(--semi-transition_function-easeIn)单选框-边框-过渡曲线
$transition_delay-radio-bordervar(--semi-transition_delay-none)单选框-边框-延迟时间
$color-radio_default-border-defaultvar(--semi-color-text-3)单选圆圈描边颜色 - 默认态
$color-radio_default-bg-defaulttransparent单选圆圈背景颜色 - 默认态
$color-radio_default-bg-hovervar(--semi-color-fill-0)单选圆圈背景颜色 - 悬浮态
$color-radio_default-bg-activevar(--semi-color-fill-1)单选圆圈背景颜色 - 按下态
$color-radio_default-border-hovervar(--semi-color-focus-border)单选圆圈描边颜色 - 悬浮态
$color-radio_checked-border-hovervar(--semi-color-primary-hover)选中状态单选圆圈描边颜色 - 悬浮态
$color-radio_checked-border-activevar(--semi-color-primary-active)选中状态单选圆圈描边颜色 - 按下态
$color-radio_default-text-defaultvar(--semi-color-text-0)选项文本颜色
$color-radio_extra-text-defaultvar(--semi-color-text-2)辅助文本颜色
$color-radio_primary-bg-hovervar(--semi-color-primary-hover)选中状态单选圆圈背景颜色 - 悬浮态
$color-radio_primary-bg-activevar(--semi-color-primary-active)选中状态单选圆圈背景颜色 - 按下态
$color-radio_primary-border-defaultvar(--semi-color-primary)选中状态单选圆圈描边颜色 - 默认态
$color-radio_primary-bg-defaultvar(--semi-color-primary)选中状态单选圆圈背景颜色 - 默认态
$color-radio_primary-text-defaultvar(--semi-white)选中状态单选圆圈中心圆点颜色
$color-radio_checked-bg-disabledvar(--semi-color-primary-disabled)选中状态单选圆圈背景颜色 - 禁用态
$color-radio_default-border-disabledvar(--semi-color-border)单选圆圈描边颜色 - 禁用态
$color-radio_checked-border-disabledvar(--semi-color-primary-disabled)选中状态单选圆圈描边颜色 - 禁用态
$color-radio_disabled-bg-defaultvar(--semi-color-disabled-fill)单选圆圈背景颜色 - 禁用态
$color-radio_disabled-bg-hovertransparent
$color-radio_disabled-text-defaultvar(--semi-color-disabled-text)禁用态文本颜色
$color-radio_disabled-border-defaultvar(--semi-color-border)单选圆圈描边颜色 - 禁用态
$color-radio_checked-icon-disabledvar(--semi-white)选中且禁用状态下中心圆点颜色
$color-radio_buttonRadio-text-defaultvar(--semi-color-text-1)按钮样式单选文本颜色
$color-radio_buttonRadio-bg-defaultvar(--semi-color-fill-0)按钮样式单选背景颜色
$color-radio_buttonRadio-text-disabledvar(--semi-color-disabled-text)按钮样式单选禁用态文本颜色
$color-radio_addon_buttonRadio-bg-hovervar(--semi-color-fill-1)按钮样式单选悬浮态背景色
$color-radio_addon_buttonRadio-text-checkedvar(--semi-color-primary)按钮样式单选选中项文字颜色
$color-radio_addon_buttonRadio-bg-checkedvar(--semi-color-bg-3)按钮样式单选选中项背景颜色
$color-radio_cardRadioGroup-bg-defaulttransparent卡片样式单选默认背景色
$color-radio_cardRadioGroup-bg-checkedvar(--semi-color-primary-light-default)卡片样式单选选中态背景色
$color-radio_cardRadioGroup_disabled-bg-checkedvar(--semi-color-primary-light-default)卡片样式单选选中且禁用时的背景色
$color-radio_cardRadioGroup_disabled-bg-activetransparent卡片样式单选禁用时的背景色 - 按下态
$color-radio_cardRadioGroup-bg-hovervar(--semi-color-fill-0)卡片样式单选悬浮态背景色
$color-radio_cardRadioGroup-bg-activevar(--semi-color-fill-1)卡片样式单选按下态背景色
$color-radio_cardRadioGroup_border-defaulttransparent卡片样式单选默认描边颜色
$color-radio_cardRadioGroup_border-activevar(--semi-color-primary)卡片样式单选选中态描边颜色
$color-radio_cardRadioGroup_checked_border-activevar(--semi-color-primary-active)卡片样式单选选中态描边颜色 - 按下态
$color-radio_cardRadioGroup_checked_border-hovervar(--semi-color-primary-hover)卡片样式单选选中态描边颜色 - 悬浮态
$color-radio_cardRadioGroup_border_disabled-activevar(--semi-color-primary-disabled)卡片样式单选选中且禁用时的描边颜色
$color-radio_cardRadioGroup_addon-text-defaultvar(--semi-color-text-0)卡片样式单选标题文字颜色
$color-radio_cardRadioGroup_extra-text-defaultvar(--semi-color-text-2)卡片样式单选辅助文字颜色
$color-radio_cardRadioGroup_checked_disabled-border-defaultvar(--semi-color-primary-disabled)卡片样式选中项禁用态描边颜色 - 默认态
$color-radio_cardRadioGroup_checked_disabled-border-hovervar(--semi-color-primary-disabled)卡片样式选中项禁用态描边颜色 - 悬浮态
$color-radio_card-bg-hovervar(--semi-color-white)卡片模式下单选圆圈背景颜色 - 悬浮态
$color-radio_card-bg-activevar(--semi-color-white)卡片模式下单选圆圈背景颜色 - 按下态
$color-radio_card-bg-defaultvar(--semi-color-white)卡片模式下单选圆圈背景颜色 - 默认态
$color-radio_primary-outline-focus$color-focus-ring轮廓颜色 - 按键聚焦
$radius-radio_cardRadioGroupvar(--semi-border-radius-small)卡片式单选圆角大小
$radius-radio_addon_buttonRadiovar(--semi-border-radius-small)按钮式单选圆点圆角大小
$radius-radio_buttonRadiovar(--semi-border-radius-small)按钮式单选圆角大小
$width-radio_cardRadioGroup_checked-border1px卡片式单选描边宽度
$width-radio_cardRadioGroup_checked_disabled-border1px卡片式单选选中且禁用时的描边宽度
$width-radio_hover-border$border-thickness-control描边宽度 - 悬浮态
$width-radio_disabled-border$border-thickness-control描边宽度 - 禁用态
$width-radio_innder-border$border-thickness-control描边宽度 - 禁用态
$width-radio-outline$width-focus-ring单选框轮廓宽度
$height-radio_inner_min20px单选按钮高度
$width-radio_inner$width-icon-medium单选按钮宽度
$spacing-radio_addon-paddingLeft$spacing-tight单选标题到单选按钮左侧边距
$spacing-radio_addon_buttonRadio_large-paddingX$spacing-loose大尺寸按钮式单选按钮水平内边距
$spacing-radio_addon_buttonRadio_large-paddingY$spacing-base-tight * 0.5大尺寸按钮式单选按钮垂直内边距
$spacing-radio_addon_buttonRadio_small-paddingX$spacing-base小尺寸按钮式单选按钮水平内边距
$spacing-radio_addon_buttonRadio_small-paddingY$spacing-super-tight中尺寸按钮式单选按钮垂直内边距
$spacing-radio_addon_buttonRadio_middle-paddingX$spacing-base中尺寸按钮式单选按钮水平内边距
$spacing-radio_addon_buttonRadio_middle-paddingY$spacing-extra-tight中尺寸按钮式单选按钮垂直内边距
$spacing-radio_content-rowGap4px内容行间距
$spacing-radio_group_vertical-marginBottom$spacing-base-tight垂直布局单选框组底部外边距
$spacing-radio_group_horizontal-marginRight$spacing-base水平单选框组右侧外边距
$spacing-radio_buttonRadio-padding$spacing-extra-tight按钮式单选内边距
$spacing-radio_buttonRadioGroup_small-paddingX$spacing-super-tight小尺寸按钮式单选组水平内边距
$spacing-radio_buttonRadioGroup_small-paddingY$spacing-extra-tight小尺寸按钮式单选组垂直内边距
$spacing-radio_buttonRadioGroup_middle-padding$spacing-extra-tight中尺寸按钮式单选组内边距
$spacing-radio_buttonRadioGroup_large-padding$spacing-extra-tight大尺寸按钮式单选组内边距
$spacing-radio_buttonRadioGroup-paddingRight$spacing-none中尺寸按钮式单选组右侧内边距
$spacing-radio_cardRadioGroup-paddingX$spacing-base卡片式单选组水平内边距
$spacing-radio_cardRadioGroup-paddingY$spacing-base-tight卡片式单选组垂直内边距
$font-radio_buttonRadio_large-default-size$font-size-regular大尺寸按钮式单选标题字体大小
$font-radio_buttonRadio_small-default-size$font-size-small中尺寸按钮式单选标题字体大小
$font-radio_buttonRadio_middle-default-size$font-size-small小尺寸按钮式单选标题字体大小
$font-radio_buttonRadio-default-fontWeight$font-weight-bold按钮式单选标题字重 - 默认态
$font-radio_buttonRadio-hover-fontWeight$font-weight-bold按钮式单选标题字重 - 悬浮态
$font-radio_buttonRadio-checked-fontWeight$font-weight-bold按钮式单选标题字重 - 选中态
$font-radio_buttonRadioGroup_small-lineHeight16px小尺寸按钮式单选标题行高
$font-radio_buttonRadioGroup_middle-lineHeight16px中尺寸按钮式单选标题行高
$font-radio_buttonRadioGroup_large-lineHeight20px大尺寸按钮式单选标题行高
$font-radio_cardRadioGroup_addon-size$font-size-regular卡片式单选组标题字体大小
$font-radio_cardRadioGroup_addon-fontWeight$font-weight-bold卡片式单选组标题字体大小
$font-radio_cardRadioGroup_addon-lineHeight20px卡片式单选组标题行高
$font-radio_cardRadioGroup_extra-size$font-size-regular卡片式单选组副标题字体大小
$font-radio_cardRadioGroup_extra-fontWeightnormal卡片式单选组副标题字重
$font-radio_cardRadioGroup_extra-lineHeight20px卡片式单选组副标题行高