Gradio SPA 前端壳层演进全解从self/spaCHANGELOG 看单页应用架构、嵌入机制与运行历史【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio本篇技术指南以 Gradio 仓库中 js/spa/CHANGELOG.md 为骨架系统梳理 Gradio 前端单页应用SPA壳层self/spa从0.0.2到1.7.0的关键演进浏览器端运行历史Run History、gradio-appWeb Component 嵌入、Reload Mode 软刷新、离线自托管资源、Deep Link 深链、多页应用multipage与多语言i18n支持等。读完本文你将理解 Gradio 前端如何作为独立 SPA 构建、如何以自定义元素嵌入任意页面以及如何借助浏览器 LocalStorage 实现运行记录回放并能结合源码文件定位每一处实现细节。一、self/spa在 Gradio 前端架构中的定位self/spa是 Gradio 前端的单页应用入口壳层位于 js/spa 目录属于仓库内部的私有包private: true见 js/spa/package.json。它本身不实现具体的 UI 组件而是负责在浏览器中加载gradio/core核心运行时、gradio/clientAPI 客户端、gradio/theme主题样式等前端工作区包渲染入口组件 js/spa/src/Index.svelte并通过 Svelte 5 的mount/unmount挂载Embed、Blocks、Login、StatusTracker等核心视图通过自定义元素gradio-app见 js/spa/src/main.ts把整个应用包装成一个标准 Web Component从而支持在任意 HTML 页面中嵌入由 Vite 构建产出到gradio/templates/frontend见 js/spa/vite.config.ts 的build.outDir最终随 Python 后端一起分发给用户。在 js/spa/package.json 的exports中可以看到两个对外入口.指向./src/Index.svelte完整 SPA./webcomponent指向./src/main.ts自定义元素注册入口。这正是 CHANGELOG 中嵌入类改动如gradio-app修复、iframe 相关问题的落点。依据上述文件路径均可在本仓库中直接验证。二、SPA 壳层的构建与运行方式2.1 开发、构建与预览命令self/spa的命令定义在 js/spa/package.json 的scripts中命令说明pnpm dev启动 Vite 开发服务器端口9876pnpm build生产构建vite build --mode production输出到gradio/templates/frontendpnpm preview预览生产构建产物pnpm test:browser运行 Playwright 浏览器测试排除 reload 测试pnpm test:browser:dev以 UI 模式运行浏览器测试pnpm test:browser:reload仅运行 reload 相关测试--grep reload.spec.tsCHANGELOG 中反复出现的CI 上运行pnpm lint与pnpm ts:checkv1.5.0PR #13526说明静态检查与类型检查已纳入质量门槛v1.2.0PR #12998use a real browser environment for unit tests在单元测试中使用真实浏览器环境则对应 js/spa/vite.config.ts 中基于vitest/browser-playwright的 chromium 浏览器测试配置这也是 js/spa/test 下 90 余个.spec.ts端到端测试文件的运行基础。2.2 生产构建的版本注入与 CSS 隔离vite.config.ts 中从gradio/package.json读取版本号并通过define注入GRADIO_VERSION、BUILD_MODEprod/dev等编译期常量用postcss-prefix-selector将组件样式统一加上.gradio-container-{version}前缀避免多个 Gradio 实例或多个版本同时存在于一个页面时样式互相污染通过self/build提供的inject_ejs、generate_cdn_entry、inject_component_loader等插件生成 CDN 入口与组件加载逻辑。CHANGELOG v1.6.0 中Make builds go zoom zoomPR #13329加速构建即与此构建管线优化相关。2.3 页面入口与 SEO/社交标签js/spa/index.html 是 Vite 的 HTML 入口模板其中包含%gradio_config%、%gradio_api_info%服务端注入占位符由 Python 后端gradio/templates.py填充应用配置与 API 信息一组 Open Graph / Twitter 卡片 meta 标签。CHANGELOG v0.8.1PR #10968Fix Default meta social tags Add ability to override existing meta tags修复默认社交 meta 标签并支持覆盖既有 meta 标签对应的实现位于 js/spa/src/Index.svelte 的add_custom_html_head它会把后端下发的head内容解析后追加到head并针对META标签按property/name匹配已存在的节点做replaceChild从而实现覆盖而非重复插入window.__gradio_mode__ app标记应用运行模式底部挂载gradio-app control_page_titletrue embedfalse eagertrue即 SPA 模式下以非嵌入、立即加载、接管页面标题的方式启动整个应用。三、gradio-app自定义元素SPA 的嵌入协议js/spa/src/main.ts 是整个壳层的注册入口。它定义并注册了gradio-app自定义元素customElements.define(gradio-app, GradioApp)并支持以下 HTML 属性含默认值来自connectedCallback中的读取逻辑属性默认值作用host无显式指定后端主机space无Hugging Face Space 标识用于跨域嵌入src无后端地址URL与space二选一embedtrue是否以嵌入模式渲染containertrue是否显示外层容器infotrue是否显示 Space 信息eager无是否立即加载否则按 IntersectionObserver 进入视口时加载initial_height300px初始高度autoscroll无是否自动滚动到输出control_page_title无是否接管页面titletheme_mode无主题模式light/dark/system该元素实现了完整的自定义元素生命周期connectedCallback加载入口组件与gradio/core挂载主题 CSS 与入口 CSS创建MutationObserver以派发domchange事件供外层 iframe resizer 等监听 DOM 变化随后用 Svelte 5 的mount(IndexComponent, opts)挂载应用observedAttributes与attributeChangedCallback监听src、space、host三个属性的变化变化时先unmount旧实例再按新地址重新挂载。CHANGELOG 中相关的关键修复v1.5.1PR #13561修复嵌入时抛出的TypeError: this.app.$destroy is not a function——这是从旧版$destroyAPI 迁移到 Svelte 5unmountAPI 时的遗留问题v0.8.5PR #11387在前端定义 root URL即 js/spa/src/Index.svelte 中通过Client.connect(api_url, ...)建立连接api_url在开发模式下取自window.__GRADIO__SERVER_PORT__默认 7860生产模式则取自space/src或基于当前路径解析。四、浏览器本地运行历史Run Historyv1.7.0 核心特性v1.7.0PR #13718为 SPA 引入了浏览器本地运行历史与加载browser-local run history and loading——这是 CHANGELOG 最新版本中最具分量的新功能。4.1 页面形态当访问路径以/gradio_api/runs结尾时见 js/spa/src/Index.svelte 中run_history window.location.pathname.replace(/\/$/, ).endsWith(/gradio_api/runs)SPA 不再渲染Blocks而是渲染 js/spa/src/RunHistory.svelte按api_name分组展示所有已保存的运行记录每条记录展示输入/输出值、状态Completed / Failed / Running、耗时、排队时间与总时长、执行时间点支持单条删除Delete与一键清空Clear history提供Load run按钮点击后调用stage_run_history_replay暂存回放数据并跳转到应用主页见load函数明确标注数据保存在 LocalStorage 中、仅存在于当前浏览器本地saved in Local Storage, privately in this browser。4.2 底层存储协议运行历史的读写实现位于 client/js/src/utils/run_history.ts关键设计存储键gradio:run-history:v2:{app_id}历史与gradio:run-history:replay:v2:{app_id}回放暂存且app_id由应用每次启动重新生成——因此应用重启即开启一段全新历史多用户隔离若应用开启了认证存储键还会带上:user:{encodeURIComponent(username)}防止不同登录用户在同一浏览器中互相看到对方的运行记录容量上限每个应用最多保留MAX_RUNS 100条记录浏览器内最多跟踪MAX_APPS 8个应用的记录超出后按最近保存时间淘汰last_saved_at决定丢弃策略健壮性所有导出函数经由safely()包裹——运行历史只是提交的副作用任何存储失败如隐私模式下 LocalStorage 不可用都不会破坏正常提交流程数据模型StoredRun记录endpoint、api_name、fn_index、page、inputs/outputs、组件元数据、statusrunning/completed/failed、error、started_at、process_started_at、completed_at、duration_ms、queued_ms、streamed是否流式生成等字段其读取 APIread_run_history(scope)也供 SPA 页面刷新展示。4.3 回放与值预览回放流程用户在历史页点Load run→stage_run_history_replay(scope, run)把本次运行写入回放暂存键 → 跳转到应用页面 → js/spa/src/Index.svelte 在拿到配置后调用apply_run_history_replay(config)来自gradio/client恢复输入值并重放对应事件。相关测试位于 client/js/src/test/run_history.test.ts。历史页的值预览逻辑在 js/spa/src/run_value.ts复用组件自带的 Example 渲染器但实时运行值与示例数据集的值形状不同因此用to_example_value(type, value)做形状重塑例如 dataframe 由{headers, data}展开为首行表头的二维数组通过is_file_like识别带meta._type gradio.FileData判别器的文件值image/video/gallery/imageeditor等组件直接渲染文件其余组件退化为展示文件名避免把普通 JSON 误判为文件summarize为无法预览的值生成人类可读摘要gr.Label取获胜标签、gr.HighlightedText拼接 token 为句子、文件取文件名、其余JSON.stringify。五、Reload Mode 软刷新与开发体验Reload Mode热重载是 CHANGELOG 中出现频率最高的主题之一先后经历多次修复v0.1.0PR #8843Fix reload mode and streaming in 5.0 dev、Fix reload modev0.8.2PR #11338Fix Reload Mode when usinggr.renderv1.0.0PR #11908Fix Reload Mode in 6.0v1.0.0-dev.1PR #12383Fix Reload Mode in 6.0。当前实现位于 js/spa/src/Index.svelte当config.dev_mode为真时SPA 会通过EventSourceSSE订阅${api_prefix}/dev/reload端点收到reload事件后执行软刷新调用app.refresh()获取最新配置重新挂载自定义 CSS 与 head 内容更新config、space_id、is_colab等全局状态并递增reload_count。软刷新的关键优势在于——不像整页刷新那样中断连接进行中的 SSE 流与生成器generator在重载后仍能继续工作源码注释明确说明Soft-reload: refresh config in place so in-flight SSE streams (and generators) keep working across the reload。此外 v0.8.3PR #11379修复了开发重载中硬编码的 HTTP 协议问题改用实际协议v0.8.4PR #11421Preserve value in reload mode重载时保留组件值v1.0.0-dev 系列中还包含Fix custom components for gradio 6、Fix Login Gradio 6等面向 Gradio 6 的兼容性修复。六、多页应用Multipage与导航v0.6.0PR #10433Allow building multipage Gradio appsSPA 开始支持多页应用对应 js/spa/src/Index.svelte 的Config接口中的pages: [string, string, boolean][]与current_page字段Embed组件据此渲染页面切换v0.11.0PR #11833Addgr.Navbarcomponent for multipage apps新增gr.Navbar导航组件v0.12.0PR #11902Add navbar visibility controls and customization options加入导航栏可见性控制与定制选项v0.7.0PR #10569Update Lite to support multi-page appsgradio/wasmGradio Lite同步支持多页应用不过 v0.12.0PR #11858随后remove lite移除 Lite 集成wasm 相关依赖在后续版本中从 CHANGELOG 的依赖清单消失v0.8.0PR #10834Add Deep Links加入 Deep Link 支持前端读取deep_link查询参数并透传给Client.connect当config.deep_link_state invalid时弹出Deep link was not valid错误提示见 js/spa/src/Index.svelte。七、离线自托管、代理与零 GPU 支持v1.4.1PR #13463Self-host frontend assets so that Gradio works offline!前端资源改为自托管使 Gradio 可以完全离线工作v1.4.0PR #13366Offload traffic to static workers and use node as the proxy将流量卸载到静态 Worker 并以 Node 作为代理v1.6.0PR #13601Preserve browser-visible proxy origins for frontend assets and API requests, and retain app-level FastAPI root paths保留浏览器可见的代理源origin并保留应用级 FastAPI 根路径v0.6.1PR #10608[ZeroGPU] Handshake-based postMessage part.2 (non-SSR mode)非 SSR 模式下基于握手handshake的 postMessage 通信支撑 Hugging Face ZeroGPU 加速v0.12.1PR #11972Fix postMessage warning when running outside hugging face spaces修复在 Space 环境之外运行时出现的 postMessage 警告v0.11.0PR #11749fix various iFrame related UI issues when deploying to spaces修复部署到 Spaces 时多个与 iframe 相关的 UI 问题。八、主题、多语言i18n与自定义 HTML8.1 主题系统js/spa/src/Index.svelte 的主题处理逻辑handle_theme_mode确定初始主题当window.__gradio_mode__ website时强制浅色否则按theme_mode属性 → URL 参数__theme→system的优先级取值system模式通过matchMedia((prefers-color-scheme: dark))跟随系统并监听变化嵌入模式下给target.parentElement添加/移除dark类非嵌入模式则作用于document.body自定义 CSS 经prefix_css加版本前缀后注入主题样式以resolve_current_origin_url(config.root, /theme.css?v${config.theme_hash})动态加载stylesheets配置支持外部绝对 URL 与相对路径两种形式。相关演进v0.3.0PR #9950Add ability to read and write from LocalStorage、v0.5.0PR #10341PWA icon customizationPWA 图标定制、v0.4.0PR #10187manifest json for PWAPWA manifest。8.2 多语言i18nv0.10.0PR #11572handle i18n error when browsers arent set to en、v0.10.2PR #11595Ensure initialLoadingtext is translated in SPA mode确保初始 Loading 文案在 SPA 模式下被翻译、v0.10.3PR #11632ensure i18n is initialised before displaying localised loading text展示本地化 Loading 文案前先完成 i18n 初始化、v1.0.3PR #12797Refactor translation logic重构翻译逻辑。实现上js/spa/src/Index.svelte 通过setupi18n()初始化svelte-i18n从应用配置的i18n_translations合并翻译并将Loading...、errors.*、common.loading等文案接入$_翻译函数v0.9.0PR #11539还升级了huggingface/space-header以支持 Space 头部本地化。8.3 自定义 head 注入与脚本顺序js/spa/src/Index.svelte 的add_custom_html_head会把后端下发的head字符串用DOMParser解析逐个重建元素追加到head。其中对SCRIPT特别处理动态创建的脚本默认是 force-async 的代码显式设置(newElement as HTMLScriptElement).async false以恢复文档顺序执行——这正是 v1.4.2PR #13450preserve head script execution order保留 head 脚本执行顺序的修复点对META标签则按property/name去重并替换已有节点。自定义js参数v1.0.2PR #12508 Fix customjsparam则以创建script元素注入config.js的方式执行。九、SPA 的测试体系js/spa/test 下提供了覆盖几乎所有演示场景的 Playwright 端到端测试90 个.spec.ts文件与 CHANGELOG 中的质量建设一一对应v1.2.0PR #12998真实浏览器单元测试环境v1.3.0PR #13151add test utils新增测试工具即 js/spa/test/utils.ts与migrate dataframe to svelte 5dataframe 组件迁移到 Svelte 5v1.0.0PR #11908Fix browser component testsv1.1.0PR #12879Ensure svelte version mismatches do not break custom components防止 Svelte 版本不匹配破坏自定义组件。测试可按功能分组浏览例如reload_mode.reload.spec.ts、hello_blocks.reload.spec.ts等*.reload.spec.ts文件专门验证热重载行为通过pnpm test:browser:reload单独运行multipage.spec.ts验证多页应用chatinterface_deep_link.spec.ts验证 Deep Linki18n.spec.ts验证国际化。十、版本演进时间线速览版本关键变化0.0.2 → 0.1.0-beta.3初始 SSR 重构、SSR e2e、Svelte 5 迁移基础PR #9102、#88430.1.0SSR 系列修复plots、reload、streaming、custom component CLI0.3.0LocalStorage 读写能力PR #99500.4.0 → 0.5.0PWA manifest、图标定制0.6.0 → 0.7.0多页应用构建、Gradio Lite 多页支持0.8.0Deep LinksPR #108340.8.1 → 0.8.5meta 标签覆盖、root URL 定义、reload 保留值等0.9.0 → 0.10.3加载性能优化、SSR 修复、i18n 完善0.11.0 → 0.12.1Navbar、多页应用配套、ZeroGPU 握手、postMessage 修复1.0.0 → 1.0.3Gradio 6 兼容reload、login、custom components、翻译逻辑重构1.1.0 → 1.2.0Svelte 版本隔离、真实浏览器测试环境1.3.0 → 1.4.2test utils、dataframe Svelte 5、包体积缩减、head 脚本顺序1.5.0 → 1.5.1CI lint/ts:check、Svelte 5 unmount 嵌入修复1.6.0代理 origin 保留、构建加速1.7.0浏览器本地运行历史与加载Run History十一、进一步阅读壳层入口与嵌入协议js/spa/src/main.ts、js/spa/src/Index.svelte运行历史页面js/spa/src/RunHistory.svelte、js/spa/src/run_value.ts运行历史存储与回放 APIclient/js/src/utils/run_history.ts、client/js/src/test/run_history.test.ts构建配置与测试js/spa/vite.config.ts、js/spa/test核心组件库与主题js/core、js/themePython 侧模板注入可参考 gradio/templates.py前端构建产物目标目录为gradio/templates/frontend【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考