Gradio Radio 前端组件深度解析BaseRadio 与 BaseExample 的 API 设计、渲染原理与事件机制【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradiogradio/radio是 Gradio 前端 UI 组件库中负责渲染单选按钮组radio group的 Svelte 包对应 Python 端的gr.Radio()组件。本文以 js/radio/README.md 公开的组件 API 为骨架结合 js/radio 目录下的真实源码、单元测试与 Storybook 用例深入讲解BaseRadio、BaseExample两个基础组件的 Props 契约、Index 层的事件分发逻辑以及它们如何与 gradio/components/radio.py 的 Python 端参数一一对应。读完本文你将掌握 Radio 组件的完整数据流从 Python 构造参数、JSON 序列化下发到 Svelte 渲染、用户交互、事件回传的整个过程并具备直接阅读和二次开发 Gradio 前端组件的能力。一、组件定位与包结构gradio/radio是 Gradio 前端组件体系中的一员。从 package.json 可以看到它的包名为gradio/radio主入口指向./Index.svelte同时通过./example子路径导出Example.svelte即BaseExample依赖gradio/atoms、gradio/statustracker、gradio/utils三个工作区包并以svelte: ^5.48.0作为 peer dependency——也就是说该组件基于 Svelte 5 的 runes 语法编写整体上是一个可独立发布、按需导入的组件单元。包内文件职责划分如下文件职责Index.svelte组件门面facade接收 Gradio 全局 Props渲染外层 Block、状态跟踪器与标题并循环渲染每个 BaseRadio同时负责事件分发shared/Radio.svelteBaseRadio的实现单个单选按钮的原生input[typeradio]封装含样式、选中态、禁用态与 RTL 支持Example.svelteBaseExample的实现用于示例表格Examples中展示单个选项值的文本块types.ts定义RadioProps与RadioEvents两个 TypeScript 接口Radio.test.tsVitest 单元测试覆盖 Props、事件、数据读写等 20 场景Radio.stories.svelteStorybook 用例提供桌面/移动端两种 chromatic 快照模式README 文档开头给出的导入方式正是面向二次开发者使用这两个基础组件的标准姿势script import { BaseRadio, BaseExample } from gradio/radio; /script二、BaseRadio单个单选按钮的 Props 契约与实现2.1 Props 定义来自 READMEREADME 中公开了BaseRadio的 5 个 Propsexport let display_value: string; export let internal_value: string | number; export let disabled false; export let elem_id ; export let selected: string | number | null null;这些 Props 的含义与使用方式如下display_value: string该选项显示给用户的文本标签。从 Index.svelte 可以看到它在渲染时还会经过gradio.live_i18n(display_value)处理支持国际化翻译。internal_value: string | number该选项的内部值。它不直接展示而是作为选中后回传给 Python 端、以及参与selected匹配判断的“真值”。因此同一选项可以做到“显示名与内部值分离”这是 Radio 支持(name, value)元组选项的基础。disabled: boolean是否禁用该单选按钮默认false。禁用态由 Index 层统一计算disabled !gradio.shared.interactive即当组件的interactive为false作为输出组件或显式禁用时所有选项一并禁用。elem_id: stringHTML DOM 中的元素 id用于 CSS 定向样式与端到端测试定位。selected: string | number | null当前选中的值受控绑定。注意它通过bind:从父组件传入BaseRadio自身不持有状态选中态完全由父级gradio.props.value决定。2.2 实现细节选中判定与原生 input 分组在 shared/Radio.svelte 中选中判定非常直观let is_selected $derived(selected internal_value);通过selected internal_value的严格相等判断天然支持了数字与字符串两种内部值测试用例numeric values are supported in choices验证了[[one, 1], [two, 2], [three, 3]]搭配value: 2时第二个选项被选中。同时由于是严格相等当selected为null或未定义、或传入一个不在choices中的值时所有选项都不会处于选中态——这正是 Radio.test.ts 中null value、undefined value、value not in choices三个用例所验证的行为。渲染层使用原生 HTML radio input并通过模块级自增计数器保证name唯一input {disabled} typeradio nameradio-{id} value{internal_value} aria-checked{is_selected} bind:group{selected} oninput{handle_input} /nameradio-{id}是关键细节id定义在script module块中模块级共享因此同一页面上多个 Radio 组件实例的 input 会拥有不同的name互不干扰。测试multiple radio instances on the same page do not conflictRadio.test.ts专门验证了这一点。handle_input在用户点击时先本地同步is_selected再通过await tick()等 Svelte 完成 DOM 更新后调用on_input()回调由父组件统一分发事件async function handle_input(e) { is_selected e.currentTarget.checked; if (is_selected) { await tick(); on_input(); } }2.3 样式体系CSS 变量驱动的主题化BaseRadio的样式全部通过 CSS 变量如--checkbox-label-*、--checkbox-*、--button-transition、--size-2实现本身不写死任何颜色值。这保证了 Radio 组件能够无缝继承 Gradio 的全局主题系统包括 soft、default 等主题。值得注意的两个视觉细节选中态通过background-image: var(--radio-circle)绘制圆形圆点input:checked::after再叠加一个居中的白色圆点label.rtl * * { margin-left: 0; margin-right: var(--size-2); }处理 RTL从右到左布局下图标与文字的间距翻转。同时外层label的data-testid{display_value}-radio-label属性为测试和自动化脚本提供了稳定的定位锚点。三、BaseExample示例表格中的选项值展示README 中公开的第二个组件是BaseExample用于 Gradio Examples示例组件中展示 Radio 的某个选项值export let value: string; export let type: gallery | table; export let selected false;在 Example.svelte 的实现中它的实际 Props 集合比 README 公开的还多一个choices用于把内部值反查回显示名value: string | null示例对应的内部值type: gallery | table当前示例容器的布局类型决定外层div应用gallery还是table样式类selected: boolean该示例是否处于选中态默认falsechoices: [string, string | number][]选项的(显示名, 内部值)列表用于反查显示名。核心逻辑是name_string这个派生值当value null时显示空字符串否则在choices中查找pair[1] value的条目并返回其显示名pair[0]let name_string $derived.by(() { if (value null) return ; const name choices.find((pair) pair[1] value); return name ? name[0] : ; });也就是说示例表格中展示给用户的是可读的显示名如cat而点击示例后提交给组件的才是内部值。这种“显示名/内部值分离”的设计贯穿 Radio 组件的整个数据链路。四、Index.svelte组件门面与事件分发中枢BaseRadio是“原子”Index.svelte才是真正与 Gradio 前端运行时对接的“分子”。它通过new GradioRadioEvents, RadioProps(props)建立与运行时的连接并在RadioProps中接收如下结构化的 props见 types.tsexport interface RadioProps { choices: [string, string | number][]; value: string; info: string; rtl: boolean; buttons: (string | CustomButton)[] | null; }渲染流程分四步外层使用gradio/atoms的Blocktypefieldset包裹透传visible、elem_id、elem_classes、container、scale、min_width、rtl等布局与样式属性渲染StatusTracker来自gradio/statustracker负责 loading / 错误状态展示若show_label且配置了自定义按钮渲染IconButtonWrapper点击后分发custom_button_click事件通过{#each gradio.props.choices as [display_value, internal_value], i (i)}循环渲染每个BaseRadio并将on_input回调绑定为事件分发逻辑。4.1 事件体系input / select / change / clear_status事件分发集中在 Index.svelte 的on_input回调中on_input{() { gradio.dispatch(input); gradio.dispatch(select, { value: internal_value, index: i }); }}input用户点击某个选项时立即触发不带负载select携带{ value: internal_value, index: i }即被选中的内部值与选项下标供.select()事件监听器消费change由$effect监听gradio.props.value变化而触发即外部数据更新如 Python 端回调返回新值时触发与用户交互触发的input/select严格区分。change的触发逻辑带有去重保护Index.svelte组件用old_value记录上一次的值只有old_value ! gradio.props.value时才更新记录并分发change。这一点被测试change deduplication: same value does not re-fire验证连续两次set_data({ value: cat })只触发一次change。完整的 TypeScript 事件契约定义在RadioEvents中export interface RadioEvents { select: SelectData; change: any; input: any; clear_status: LoadingStatus; custom_button_click: { id: number }; }测试用例Radio.test.ts对这一事件体系给出了精确的行为断言set_data改变 value 时只触发change不触发input组件挂载时不触发change用户点击选项时input与select各触发一次且select携带{ value: turtle, index: 2 }点击自定义按钮触发custom_button_click并携带{ id }。五、与 Python 端gr.Radio的映射关系前端组件不是孤立的它由 Python 端 gradio/components/radio.py 的gr.Radio(FormComponent)驱动。两者的核心映射如下Python 参数前端落点说明choices: Sequence[str \| int \| float \| tuple]RadioProps.choices[string, string \| number][]构造时统一归一化为(name, value)元组[tuple(c) if isinstance(c, (tuple, list)) else (str(c), c) for c in choices]纯字符串选项的显示名与内部值相同valueRadioProps.value默认选中项为None时无默认选中type: value \| index影响preprocess返回值value返回选中项的字符串/数值index返回其在 choices 中的下标非法值在构造时即抛ValueErrorinfoRadioProps.info显示在标签下方的说明文字支持 Markdown/HTMLrtl: boolRadioProps.rtl控制选项是否从右到左排列默认Falseinteractiveshared.interactive→BaseRadio.disabled组件作为输出或显式禁用时所有选项呈禁用态buttons: list[gr.Button]RadioProps.buttons渲染在组件右上角的自定义按钮点击分发custom_button_clickPython 端的preprocess还包含一层校验若回传的 payload 不在choices的内部值列表中会抛出Errornot in the list of choices防止前后端数据不一致时产生脏状态。api_info()则把choices的内部值导出为 OpenAPIenum供gradio_client与 API 文档使用。一个典型的端到端示例demo/radio_component/run.pyimport gradio as gr with gr.Blocks() as demo: gr.Radio(choices[First Choice, Second Choice, Third Choice]) demo.launch()该示例中三个选项的显示名与内部值相同若希望显示名与内部值分离可传入元组列表例如choices[(狗, dog), (猫, cat)]此时用户看到狗/猫但 Python 函数收到的是dog/cat。六、可访问性与测试保障从 Radio.test.ts 的测试设计可以看出该组件对可访问性与数据流有着成体系的保障ARIA 支持渲染的input带有aria-checkedlabel与 input 隐式关联测试通过getByRole(radio)、getByLabelText进行查询共享 Props 测试通过run_shared_prop_tests复用其他组件共用的基础属性测试确保组件符合 Gradio 前端的统一规范i18n 测试i18n choices用例验证了带翻译标记的选项会通过 i18n formatter 渲染为本地化文本且翻译不影响内部值runtime locale switching用例进一步验证运行时切换语言如 en → es后选项显示名会实时重新翻译数据读写get_data/set_data用例验证了组件与运行时之间的双向数据通道包括set_data({ value: null })清空选中值。上述测试对应的 Storybook 可视化用例Radio.stories.svelte覆盖了带选项的 RadioRTL 布局禁用态三种典型场景可作为开发与回归验证的参考。七、小结gradio/radio的组件设计体现了 Gradio 前端架构的一贯原则原子组件BaseRadio/BaseExample只负责渲染与交互状态与事件由门面组件Index.svelte统一托管并通过Gradio运行时与 Python 后端保持双向同步。其中selected internal_value的严格相等判断、bind:group的原生分组语义、模块级自增name、以及change/input/select三类事件的分工是理解整个组件行为的关键细节。若要在自己的 Gradio 自定义组件或主题中复用此组件可直接import { BaseRadio, BaseExample } from gradio/radio并参考本文梳理的 Props 契约与事件约定进行二次开发。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 15:58:36 · 阅读 1.2k Gradio Radio 前端组件深度解析：BaseRadio 与 BaseExample 的 API 设计、渲染原理与事件机制
Gradio Radio 前端组件深度解析BaseRadio 与 BaseExample 的 API 设计、渲染原理与事件机制【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradiogradio/radio是 Gradio 前端 UI 组件库中负责渲染单选按钮组radio group的 Svelte 包对应 Python 端的gr.Radio()组件。本文以 js/radio/README.md 公开的组件 API 为骨架结合 js/radio 目录下的真实源码、单元测试与 Storybook 用例深入讲解BaseRadio、BaseExample两个基础组件的 Props 契约、Index 层的事件分发逻辑以及它们如何与 gradio/components/radio.py 的 Python 端参数一一对应。读完本文你将掌握 Radio 组件的完整数据流从 Python 构造参数、JSON 序列化下发到 Svelte 渲染、用户交互、事件回传的整个过程并具备直接阅读和二次开发 Gradio 前端组件的能力。一、组件定位与包结构gradio/radio是 Gradio 前端组件体系中的一员。从 package.json 可以看到它的包名为gradio/radio主入口指向./Index.svelte同时通过./example子路径导出Example.svelte即BaseExample依赖gradio/atoms、gradio/statustracker、gradio/utils三个工作区包并以svelte: ^5.48.0作为 peer dependency——也就是说该组件基于 Svelte 5 的 runes 语法编写整体上是一个可独立发布、按需导入的组件单元。包内文件职责划分如下文件职责Index.svelte组件门面facade接收 Gradio 全局 Props渲染外层 Block、状态跟踪器与标题并循环渲染每个 BaseRadio同时负责事件分发shared/Radio.svelteBaseRadio的实现单个单选按钮的原生input[typeradio]封装含样式、选中态、禁用态与 RTL 支持Example.svelteBaseExample的实现用于示例表格Examples中展示单个选项值的文本块types.ts定义RadioProps与RadioEvents两个 TypeScript 接口Radio.test.tsVitest 单元测试覆盖 Props、事件、数据读写等 20 场景Radio.stories.svelteStorybook 用例提供桌面/移动端两种 chromatic 快照模式README 文档开头给出的导入方式正是面向二次开发者使用这两个基础组件的标准姿势script import { BaseRadio, BaseExample } from gradio/radio; /script二、BaseRadio单个单选按钮的 Props 契约与实现2.1 Props 定义来自 READMEREADME 中公开了BaseRadio的 5 个 Propsexport let display_value: string; export let internal_value: string | number; export let disabled false; export let elem_id ; export let selected: string | number | null null;这些 Props 的含义与使用方式如下display_value: string该选项显示给用户的文本标签。从 Index.svelte 可以看到它在渲染时还会经过gradio.live_i18n(display_value)处理支持国际化翻译。internal_value: string | number该选项的内部值。它不直接展示而是作为选中后回传给 Python 端、以及参与selected匹配判断的“真值”。因此同一选项可以做到“显示名与内部值分离”这是 Radio 支持(name, value)元组选项的基础。disabled: boolean是否禁用该单选按钮默认false。禁用态由 Index 层统一计算disabled !gradio.shared.interactive即当组件的interactive为false作为输出组件或显式禁用时所有选项一并禁用。elem_id: stringHTML DOM 中的元素 id用于 CSS 定向样式与端到端测试定位。selected: string | number | null当前选中的值受控绑定。注意它通过bind:从父组件传入BaseRadio自身不持有状态选中态完全由父级gradio.props.value决定。2.2 实现细节选中判定与原生 input 分组在 shared/Radio.svelte 中选中判定非常直观let is_selected $derived(selected internal_value);通过selected internal_value的严格相等判断天然支持了数字与字符串两种内部值测试用例numeric values are supported in choices验证了[[one, 1], [two, 2], [three, 3]]搭配value: 2时第二个选项被选中。同时由于是严格相等当selected为null或未定义、或传入一个不在choices中的值时所有选项都不会处于选中态——这正是 Radio.test.ts 中null value、undefined value、value not in choices三个用例所验证的行为。渲染层使用原生 HTML radio input并通过模块级自增计数器保证name唯一input {disabled} typeradio nameradio-{id} value{internal_value} aria-checked{is_selected} bind:group{selected} oninput{handle_input} /nameradio-{id}是关键细节id定义在script module块中模块级共享因此同一页面上多个 Radio 组件实例的 input 会拥有不同的name互不干扰。测试multiple radio instances on the same page do not conflictRadio.test.ts专门验证了这一点。handle_input在用户点击时先本地同步is_selected再通过await tick()等 Svelte 完成 DOM 更新后调用on_input()回调由父组件统一分发事件async function handle_input(e) { is_selected e.currentTarget.checked; if (is_selected) { await tick(); on_input(); } }2.3 样式体系CSS 变量驱动的主题化BaseRadio的样式全部通过 CSS 变量如--checkbox-label-*、--checkbox-*、--button-transition、--size-2实现本身不写死任何颜色值。这保证了 Radio 组件能够无缝继承 Gradio 的全局主题系统包括 soft、default 等主题。值得注意的两个视觉细节选中态通过background-image: var(--radio-circle)绘制圆形圆点input:checked::after再叠加一个居中的白色圆点label.rtl * * { margin-left: 0; margin-right: var(--size-2); }处理 RTL从右到左布局下图标与文字的间距翻转。同时外层label的data-testid{display_value}-radio-label属性为测试和自动化脚本提供了稳定的定位锚点。三、BaseExample示例表格中的选项值展示README 中公开的第二个组件是BaseExample用于 Gradio Examples示例组件中展示 Radio 的某个选项值export let value: string; export let type: gallery | table; export let selected false;在 Example.svelte 的实现中它的实际 Props 集合比 README 公开的还多一个choices用于把内部值反查回显示名value: string | null示例对应的内部值type: gallery | table当前示例容器的布局类型决定外层div应用gallery还是table样式类selected: boolean该示例是否处于选中态默认falsechoices: [string, string | number][]选项的(显示名, 内部值)列表用于反查显示名。核心逻辑是name_string这个派生值当value null时显示空字符串否则在choices中查找pair[1] value的条目并返回其显示名pair[0]let name_string $derived.by(() { if (value null) return ; const name choices.find((pair) pair[1] value); return name ? name[0] : ; });也就是说示例表格中展示给用户的是可读的显示名如cat而点击示例后提交给组件的才是内部值。这种“显示名/内部值分离”的设计贯穿 Radio 组件的整个数据链路。四、Index.svelte组件门面与事件分发中枢BaseRadio是“原子”Index.svelte才是真正与 Gradio 前端运行时对接的“分子”。它通过new GradioRadioEvents, RadioProps(props)建立与运行时的连接并在RadioProps中接收如下结构化的 props见 types.tsexport interface RadioProps { choices: [string, string | number][]; value: string; info: string; rtl: boolean; buttons: (string | CustomButton)[] | null; }渲染流程分四步外层使用gradio/atoms的Blocktypefieldset包裹透传visible、elem_id、elem_classes、container、scale、min_width、rtl等布局与样式属性渲染StatusTracker来自gradio/statustracker负责 loading / 错误状态展示若show_label且配置了自定义按钮渲染IconButtonWrapper点击后分发custom_button_click事件通过{#each gradio.props.choices as [display_value, internal_value], i (i)}循环渲染每个BaseRadio并将on_input回调绑定为事件分发逻辑。4.1 事件体系input / select / change / clear_status事件分发集中在 Index.svelte 的on_input回调中on_input{() { gradio.dispatch(input); gradio.dispatch(select, { value: internal_value, index: i }); }}input用户点击某个选项时立即触发不带负载select携带{ value: internal_value, index: i }即被选中的内部值与选项下标供.select()事件监听器消费change由$effect监听gradio.props.value变化而触发即外部数据更新如 Python 端回调返回新值时触发与用户交互触发的input/select严格区分。change的触发逻辑带有去重保护Index.svelte组件用old_value记录上一次的值只有old_value ! gradio.props.value时才更新记录并分发change。这一点被测试change deduplication: same value does not re-fire验证连续两次set_data({ value: cat })只触发一次change。完整的 TypeScript 事件契约定义在RadioEvents中export interface RadioEvents { select: SelectData; change: any; input: any; clear_status: LoadingStatus; custom_button_click: { id: number }; }测试用例Radio.test.ts对这一事件体系给出了精确的行为断言set_data改变 value 时只触发change不触发input组件挂载时不触发change用户点击选项时input与select各触发一次且select携带{ value: turtle, index: 2 }点击自定义按钮触发custom_button_click并携带{ id }。五、与 Python 端gr.Radio的映射关系前端组件不是孤立的它由 Python 端 gradio/components/radio.py 的gr.Radio(FormComponent)驱动。两者的核心映射如下Python 参数前端落点说明choices: Sequence[str \| int \| float \| tuple]RadioProps.choices[string, string \| number][]构造时统一归一化为(name, value)元组[tuple(c) if isinstance(c, (tuple, list)) else (str(c), c) for c in choices]纯字符串选项的显示名与内部值相同valueRadioProps.value默认选中项为None时无默认选中type: value \| index影响preprocess返回值value返回选中项的字符串/数值index返回其在 choices 中的下标非法值在构造时即抛ValueErrorinfoRadioProps.info显示在标签下方的说明文字支持 Markdown/HTMLrtl: boolRadioProps.rtl控制选项是否从右到左排列默认Falseinteractiveshared.interactive→BaseRadio.disabled组件作为输出或显式禁用时所有选项呈禁用态buttons: list[gr.Button]RadioProps.buttons渲染在组件右上角的自定义按钮点击分发custom_button_clickPython 端的preprocess还包含一层校验若回传的 payload 不在choices的内部值列表中会抛出Errornot in the list of choices防止前后端数据不一致时产生脏状态。api_info()则把choices的内部值导出为 OpenAPIenum供gradio_client与 API 文档使用。一个典型的端到端示例demo/radio_component/run.pyimport gradio as gr with gr.Blocks() as demo: gr.Radio(choices[First Choice, Second Choice, Third Choice]) demo.launch()该示例中三个选项的显示名与内部值相同若希望显示名与内部值分离可传入元组列表例如choices[(狗, dog), (猫, cat)]此时用户看到狗/猫但 Python 函数收到的是dog/cat。六、可访问性与测试保障从 Radio.test.ts 的测试设计可以看出该组件对可访问性与数据流有着成体系的保障ARIA 支持渲染的input带有aria-checkedlabel与 input 隐式关联测试通过getByRole(radio)、getByLabelText进行查询共享 Props 测试通过run_shared_prop_tests复用其他组件共用的基础属性测试确保组件符合 Gradio 前端的统一规范i18n 测试i18n choices用例验证了带翻译标记的选项会通过 i18n formatter 渲染为本地化文本且翻译不影响内部值runtime locale switching用例进一步验证运行时切换语言如 en → es后选项显示名会实时重新翻译数据读写get_data/set_data用例验证了组件与运行时之间的双向数据通道包括set_data({ value: null })清空选中值。上述测试对应的 Storybook 可视化用例Radio.stories.svelte覆盖了带选项的 RadioRTL 布局禁用态三种典型场景可作为开发与回归验证的参考。七、小结gradio/radio的组件设计体现了 Gradio 前端架构的一贯原则原子组件BaseRadio/BaseExample只负责渲染与交互状态与事件由门面组件Index.svelte统一托管并通过Gradio运行时与 Python 后端保持双向同步。其中selected internal_value的严格相等判断、bind:group的原生分组语义、模块级自增name、以及change/input/select三类事件的分工是理解整个组件行为的关键细节。若要在自己的 Gradio 自定义组件或主题中复用此组件可直接import { BaseRadio, BaseExample } from gradio/radio并参考本文梳理的 Props 契约与事件约定进行二次开发。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考