Feature Request: Native file handling support for `gr.HTML`

问题场景

开发者使用 gr.HTML 构建画布查看器、标注编辑器等富交互界面时，需要在 Python 后端与前端 JavaScript 之间传递图片、文件等二进制数据。由于 gr.HTML 只支持纯字符串序列化，开发者被迫调用 Gradio 内部接口实现文件传输。

报错原文

Feature Request: Native file handling support for `gr.HTML`

原因分析

原因是 gr.HTML 组件的数据通道设计为仅支持字符串序列化，缺少官方的文件传递机制。开发者只能通过两种非官方途径绕过限制：

• Python → JS：调用内部 processing_utils.save_pil_to_cache() 将图片存入文件缓存后手动拼接 /gradio_api/file=... 形式的 URL；
• JS → Python：直接 fetch() 内部上传端点 /gradio_api/upload 获取服务端文件路径。

这两种方式均依赖未文档化的内部接口，不同版本间可能变动，且缺乏官方指引。

环境排查

• 确认 Gradio 版本是否已包含 #12909 修复（需查阅对应版本的 Release Notes）；
• 检查自定义组件中是否直接调用了 processing_utils.save_pil_to_cache 或 /gradio_api/upload 端点；
• 若涉及远程服务器（如 Hugging Face Spaces），注意 base64 内嵌图片会显著增加延迟，优先排查是否已改用文件 URL 方案。

解决步骤

1. 升级 Gradio 至包含 #12909 修复的版本；
2. 查阅该版本官方文档中 gr.HTML 关于文件处理的新增 API（Issue 中提出的理想方案包括：postprocess 自动将 PIL.Image、pathlib.Path、gradio.FileData 转换为 URL；前端提供 uploadFile(file) 官方辅助方法）；
3. 迁移现有代码：删除对 processing_utils.save_pil_to_cache 和 /gradio_api/upload 的手动调用，替换为官方 API；
4. 如暂时无法升级，可继续使用现有内部接口，但需关注后续版本更新可能导致的兼容性问题。

验证方法

确认 gr.HTML 组件中 Python 返回的图片对象能自动转换为可访问 URL，前端无需手动拼接地址；同时前端上传文件后能通过官方接口获取服务端路径，整个过程不依赖内部函数或未文档化端点。

参考来源

gradio-app/gradio #12897

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。