Gradio Sidebar 组件深度解析从 Svelte 前端实现到 Python 布局【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradioGradio 的 Sidebar侧边栏是一个可折叠面板组件用于在 Blocks 布局中把子组件渲染到屏幕左侧或右侧是构建左侧导航/控制面板 右侧主内容区这类经典应用布局的核心构件。本文以gradio/sidebar前端包为骨架结合 Python 端gr.Sidebar布局、源码实现与测试用例完整讲解其 Svelte 用法、Props 与事件契约、动画与重叠避让原理、移动端适配及无障碍细节帮助你从用法到原理全面掌握这一组件。一、组件概览README 中的最小用法原文档js/sidebar/README.md给出的最小示例展示了如何在 Svelte 应用中直接引用该组件script import { Sidebar } from gradio/sidebar; /script Sidebar /Sidebar这是前端包gradio/sidebar的入口用法导入组件后在 Svelte 模板中渲染子内容通过 childrenSnippet 插槽传入。对于大多数 Gradio 应用开发者而言日常更常用的是 Python 端等价写法import gradio as gr with gr.Blocks() as demo: with gr.Sidebar(): gr.Textbox() gr.Button()Python 端与前端包通过package.json中声明的导出映射关联.字段将包入口指向 Index.svelte同时暴露 svelte 与 types 导出js/sidebar/package.json。当前包版本为 0.2.12peerDependencies 要求svelte: ^5.48.0即基于 Svelte 5 的 runes 语法编写。二、前端 Props 与事件契约Sidebar 前端的类型定义集中在 js/sidebar/types.ts这是理解组件对外接口的第一手资料export interface SidebarProps { open: boolean; position: left | right; width: number | string; } export interface SidebarEvents { expand: never; collapse: never; clear_status: never; }结合 shared/Sidebar.svelte 中的$props()解构各 Props 的完整语义如下Prop类型默认值说明openbooleantrue侧边栏是否默认展开$bindable可由外部双向绑定widthnumber \| string320宽度数字按像素处理字符串按 CSS 单位处理positionleft \| rightleft侧边栏停靠方向elem_idstring挂载到 DOM 根元素的 id用于 CSS 定位elem_classesstring[][]追加到 DOM 根元素的 classonexpand/oncollapse() void空函数展开/收起回调宽度转换逻辑在源码中体现为typeof width number ? \${width}px : width即传320等价于传320px也可以直接传20rem、30vw 等任意合法 CSS 长度。在 Index.svelte 这一层组件做了三件关键的事通过GradioSidebarEvents, SidebarProps运行时封装接入 Gradio 前端基础设施渲染StatusTracker复用gradio/statustracker展示加载状态用{#if gradio.shared.visible}控制是否挂载可见时把open、position、width绑定给内部实现并通过onexpand/oncollapse把 UI 状态派发为expand/collapse事件子内容被包进BaseColumn来自gradio/column以保持纵向布局一致性。事件契约上只有用户点击切换按钮才会触发expand/collapse程序化修改openset_data不会触发任何事件——这一行为被测试用例set_data does not fire expand or collapse (events only come from user click)显式锁定见 Sidebar.test.ts。三、Python 端gr.Sidebar布局与全部参数Python 端对应实现是 gradio/layouts/sidebar.py 中的Sidebar(BlockContext)类它继承BlockContext并声明事件EVENTS [Events.expand, Events.collapse]。构造函数参数如下参数类型默认值说明labelstr \| I18nData \| NoneNone侧边栏名称不展示给用户openboolTrue默认是否展开visiblebool \| hiddenTrue控制渲染hidden时仍渲染但视觉隐藏elem_idstr \| NoneNoneDOM id用于 CSS 定位elem_classeslist[str] \| str \| NoneNoneDOM classrenderboolTrue为False时先注册事件、稍后再渲染widthint \| str320宽度数字为像素字符串为 CSS 单位positionleft \| rightleft停靠方向keyint \| str \| tupleNonegr.render中按 key 复用组件preserved_by_keylist[str] \| str \| NoneNone重渲染时保留的用户修改项一个完整的实战示例是仓库自带的演示程序 demo/blocks_sidebar/run.py宠物名生成器在with gr.Sidebar(positionleft)内放置 Markdown 标题、gr.Dropdown和gr.Radio作为控制面板主区域放gr.Textbox输出与gr.Button按钮按钮的click事件引用侧边栏内的控件作为输入。这正体现了 Sidebar 最典型的应用场景左侧参数面板 右侧内容展示区。四、开合动画与重叠避让的实现原理Sidebar 的可折叠体验并非简单显隐而是内容区让位式布局核心逻辑集中在 shared/Sidebar.svelte定位方式外层.sidebar采用position: fixed; top: 0; height: 100%通过stylewidth: {width_css}; {position}: calc({width_css} * -1)把侧边栏隐藏在屏幕边缘外侧再用transform: translateX(100%)左侧或translateX(-100%)右侧滑入视野实现 0.3s ease-in-out 的展开动画。重叠检测check_overlap()在挂载时和窗口resize时执行比较侧边栏宽度与.wrap容器外侧可用空间把差值写入 CSS 变量--overlap-amountMath.max(0, sidebar_rect.width - available_space 30)由$effect同步到document.documentElement.style。内容让位挂载时会给最近的.wrap添加sidebar-parentclass配合:global(.sidebar-parent:has(.sidebar.open:not(.right)))设置padding-left: var(--overlap-amount)让主内容区自动让出侧边栏所占空间当可用空间足够时重叠量为 0侧边栏悬浮在内容旁。首次动画源码注释说明用mounted临时变量延迟同步_open等待组件真正挂载后再置位确保初始状态也能正确播放动画。CHANGELOGjs/sidebar/CHANGELOG.md记录了 0.2.12 版本在 resize 时重新计算 overlap 量的修复与上述check_overlap逻辑对应侧面印证了重叠避让是该组件持续演进的核心能力。五、移动端适配与无障碍设计响应式media (max-width: 768px)下侧边栏强制width: 100vw并分别用left/right: -100vw完全移出视口收起时z-index: 1001覆盖在内容之上等价于全屏抽屉sidebar-parent的内边距在移动端被强制归零避免内容区空出多余空间。减少动画偏好通过matchMedia((prefers-reduced-motion: reduce))检测用户系统偏好命中时给根元素追加reduce-motionclass关闭 transform 与 padding 过渡满足无障碍要求。可访问性切换按钮带有aria-labelToggle Sidebar测试renders the toggle button with an accessible label通过getByRole(button, { name: Toggle Sidebar })验证见 Sidebar.test.ts。六、测试与可视化验证Sidebar.test.ts 是理解组件行为的权威参考覆盖以下契约渲染与 DOMvisible: true时侧边栏在 DOM 中visible: false时整棵子树含插槽子内容被移除hidden字符串为 truthy仍会渲染。样式挂载elem_id写入容器 idelem_classes追加到 class 列表position: right会添加.rightclass#sb-right.right选择器断言。开合状态get_data()/set_data()可读写open往返保持状态一致点击按钮后get_data报告open: true。事件时序关闭时点击触发一次expand开启时点击触发一次collapse连续两次点击按展开→收起顺序各触发一次挂载时不触发任何事件。重叠计算通过操作.wrap的marginLeft并派发resize断言--overlap-amount从大于 0 变为 0 再恢复验证响应式重算逻辑。文件末尾还留有若干test.todo点名需要 Playwright 视觉回归的项opentrue的translateX(±100%)滑入动画、positionright的停靠与按钮翻转、width对容器宽度的控制、以及 open 时父容器 padding 的让位效果——这些与 Sidebar.stories.svelte 中 Open Sidebar / Closed Sidebar 两个 Storybook 用例互相呼应可作为手动验证清单。七、小结Sidebar 是 Gradio 中少数前端包 Python 布局双端齐备的复杂布局组件Python 端负责参数透传与事件注册gradio/layouts/sidebar.py前端端由 Index.svelte 接入 Gradio 运行时、shared/Sidebar.svelte 实现动画、重叠避让与响应式。开发者既可以在 Python 中通过gr.Sidebar(position..., width..., open...)快速搭建左右分栏布局也可以在自定义 Svelte 组件中直接import { Sidebar } from gradio/sidebar并通过open/position/width三个核心 Props 与expand/collapse事件获得完全一致的交互体验。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考