Gradio 自定义组件Custom Components配置详解包名、导出、依赖与目录结构全攻略【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio自定义组件Custom Components是 Gradio 提供的、允许开发者用纯 Python 前端代码构建可复用 UI 组件的官方扩展机制。本指南聚焦于 guides/08_custom-components/03_configuration.md 所讲解的“配置面”当你在gradio cc create生成的默认模板基础上需要重命名包、暴露更多 Python 导出、添加 Python / JavaScript 第三方依赖或调整前后端目录布局时应该如何精确地修改pyproject.toml、__init__.py、frontend/package.json以及组件类的FRONTEND_DIR属性。读完本文你将掌握自定义组件所有可配置点的完整清单及其背后的源码原理能够熟练地把一个模板组件改造成属于自己的正式开源包。如果你还不了解自定义组件的整体工作流create→dev→build→publish建议先阅读同系列的 01_custom-components-in-five-minutes.md 与本仓库中对每个阶段均有实际命令行实现支持的源码目录 gradio/cli/commands/components。核心理念约定优于配置自定义组件开发流程刻意遵循convention over configuration约定优于配置的设计思想目标是最大化减少你在起步时需要做出的决策数量。因此Python 代码默认放在backend/JavaScript 代码默认放在frontend/包名默认遵循gradio_组件Python类名小写的规则顶层导出默认只暴露组件类本身。绝大多数情况下你无需修改任何配置即可完成开发。只有在需要偏离这些默认约定时才需要按下面的章节逐项调整。也就是说本文回答的是同一个问题“当我不想遵循默认时该如何配置”包名Package Name从gradio_mytextbox改为supertextbox默认命名规则从哪里来gradio cc create在创建组件时会直接以默认规则生成包名。从本仓库的 CLI 实现可以看到# gradio/cli/commands/components/create.py package_name fgradio_{name.lower()}即创建名为MyTextbox的组件时会生成gradio_mytextbox这样的包名模板中的示例 Demo 也会以该包名引入组件参见 gradio/cli/commands/components/create.py。重命名三步走以一个真实例子演示把组件从gradio_mytextbox重命名为supertextbox。第 1 步修改pyproject.toml中的name字段[project] name supertextbox第 2 步把pyproject.toml中所有出现的gradio_组件名统一替换为新组件名pyproject.toml中不仅[project].name引用包名[tool.hatch.build]的artifacts与[tool.hatch.build.targets.wheel]的packages也引用了实际的目录路径[tool.hatch.build] artifacts [/backend/supertextbox/templates, *.pyi] [tool.hatch.build.targets.wheel] packages [/backend/supertextbox]对照仓库内置的模板文件 gradio/cli/commands/components/files/pyproject_.toml可以看到默认生成的构建配置形如[tool.hatch.build] artifacts [/backend/name/templates, *.pyi] [tool.hatch.build.targets.wheel] packages [/backend/name]其中artifacts中的/backend/包名/templates打包的是组件后端使用的静态模板资源对应组件类上的TEMPLATE_DIR见 gradio/components/base.py*.pyi打包的是类型桩文件packages指定需要打进 wheel 的源码目录。wheel的packages必须与真实目录一致否则构建出的包将是空壳。第 3 步重命名backend/下的 Python 目录mv backend/gradio_mytextbox backend/supertextbox把backend/gradio_mytextbox目录改为backend/supertextbox保证它与第 2 步的 wheelpackages路径一一对应。第 4 步易漏点同步修改demo/app.py中的 import 语句模板 Demo 通常以from gradio_mytextbox import MyTextbox形式导入组件重命名后必须改为from supertextbox import SuperTextbox另外需要提醒Python 的import机制要求模块名必须是一个合法的 Python 标识符。示例中的新名字supertextbox不含连字符可以直接被importlib导入如果起名含-会导致后续import、gradio cc install的模块探测都无法工作。这一点在gradio cc install的实现中也能看到它会用pyproject.toml里的name去执行importlib.import_module(package_name)见 gradio/cli/commands/components/install_component.py因此包名必须是可导入的模块名。与包名配置直接相关的命令链gradio cc dev在本地以热重载方式开发组件读取包名定位后端模块gradio cc build用 Hatchling 构建dist/*.whl此时pyproject.toml中的name、artifacts、packages将直接决定产物内容gradio cc publish把构建产物发布到 PyPI 并可选上传示例到 Hugging Face Spacesgradio cc install以可编辑模式安装包并执行前端依赖安装用于在修改依赖后刷新环境。所有命令的帮助信息可通过gradio cc --help或gradio cc 子命令 --help查看。顶层 Python 导出用__all__控制可导入符号默认行为自定义组件模板的backend/包名/__init__.py默认只把“组件类”作为顶层导出。这意味着用户执行from gradio_mytextbox import *时只有MyTextbox类可用AdditionalClass、additional_function等符号不会出现在命名空间中。如何增加导出要暴露更多符号直接修改backend/包名/__init__.py中的__all__from .mytextbox import MyTextbox from .mytextbox import AdditionalClass, additional_function __all__ [MyTextbox, AdditionalClass, additional_function]__all__是 Python 模块级的内建约定它不仅影响from ... import *的导出范围也向 IDE、文档生成器与静态分析工具声明该模块的“公开 API 表面”。Gradio 自身的主包就大量使用这一机制管理公开符号参见 gradio/init.py 处的__all__定义。因此为自定义组件维护一个清晰的__all__既是功能需要也是一种面向用户的 API 文档实践。需要注意若组件内部模块之间相互导入但没有加入__all__它们仍可通过显式导入使用__all__只影响“通配导入”但把辅助类/函数加入其中更利于用户、类型检查工具与自动文档工具发现你的公共 API。Python 依赖dependencies 记住执行gradio cc install在pyproject.toml的[project]段中通过dependencies键声明运行时依赖dependencies [gradio, numpy, PIL]仓库内置模板给出了基线示例gradio/cli/commands/components/files/pyproject_.tomldependencies [gradio6.0,7.0]自定义组件依赖打包在 wheel 中后会被 pip 在安装时自动解析安装因此发布到 PyPI 的依赖必须写到dependencies而不是仅仅在本地环境手动 pip 安装。一个极易踩坑的点是修改依赖后若仅更新了pyproject.toml开发环境并不会自动同步。因为模板默认使用可编辑安装依赖条目变更需要重新执行安装命令才能反映到当前环境。所以请牢记文档给出的 Tip修改dependencies后务必重新运行gradio cc installgradio cc install内部会依次执行见 gradio/cli/commands/components/install_component.pypip install -e .[dev]以可编辑模式安装当前目录并带入dev可选依赖自动探测前端目录并执行npm install可通过--npm-install覆盖例如yarn install还可通过--pip-path指定 pip 解释器。因此无论是新增 Python 依赖还是前端依赖统一流程都是“改配置文件 →gradio cc install”。JavaScript 依赖编辑frontend/package.json组件的浏览器端代码是一个独立 npm 包其依赖通过frontend/package.json的dependencies键管理。模板默认已依赖 Gradio 官方发布的一组基础前端包例如dependencies: { gradio/atoms: 0.2.0-beta.4, gradio/statustracker: 0.3.0-beta.6, gradio/utils: 0.2.0-beta.4, your-npm-package: version }gradio/atoms、gradio/statustracker、gradio/utils等官方包提供了图标、按钮、状态跟踪器与工具函数是自定义组件常用的基础库这些包在仓库 js 目录下均有对应源码如 js/atoms、js/statustracker、js/utils你自己的第三方库例如需要用的图表库、编辑器内核追加在该对象中即可版本号建议遵循 npm 的 semver 规范。前端依赖的安装由gradio cc dev开发模式或gradio cc install触发。若只新增了 npm 依赖运行gradio cc install即可同步安装。注意 Gradio 的构建链路使用 pnpm workspace 统一管理官方组件见仓库根目录 pnpm-workspace.yaml而第三方 npm 依赖会被打进最终的前端 bundle所以务必确认版本锁定避免可复现性风险。目录结构默认布局与FRONTEND_DIR覆盖默认布局backendfrontendgradio cc create默认生成如下结构与文档描述一致也符合 01_custom-components-in-five-minutes.md 中列出的模板骨架my_component/ ├── backend/ # Python 源码组件类、templates 等 ├── frontend/ # JavaScript/Svelte 前端源码 ├── demo/ # 演示应用run.py / app.py └── pyproject.toml # 打包与元数据官方文档明确建议不要修改这套默认布局统一的目录约定让任何潜在的贡献者拿到你的源码后都能立刻定位“后端在哪、前端在哪”显著降低协作成本。如果确实要改目录布局若你出于特殊原因希望自定义目录位置需要同步做三件事1. 移动 Python 代码并同步修改 Hatchling 构建配置把 Python 源码放到你选定的子目录后pyproject.toml中[tool.hatch.build]与[tool.hatch.build.targets.wheel]的路径必须跟着更新否则构建出的 wheel 无法正确包含源码与模板资源。2. 移动 JavaScript 代码到你选定的子目录把前端源码放在自选目录例如改为js/、client/等。3. 在组件类上声明FRONTEND_DIRFRONTEND_DIR是 Gradio 组件基类上预置的类属性其默认值定义在 gradio/components/base.pyFRONTEND_DIR ../../frontend/含义是“从定义组件类的 Python 文件所在目录到前端 JavaScript 目录的相对路径”。覆盖它的写法如下class SuperTextbox(Component): FRONTEND_DIR ../../frontend/同理布局类Blocks容器等也在 gradio/blocks.py 声明了同名的默认FRONTEND_DIR ../../frontend/。约束条件JavaScript 与 Python 目录必须位于同一个公共父目录之下。这是为了保证从“组件类定义文件”出发的相对路径始终能解析到前端目录如果二者跨越了不同的顶层目录例如一个在src/下、另一个在仓库外的libs/下FRONTEND_DIR的相对路径将无法表达这种关系。FRONTEND_DIR在 CLI 中如何被消费自定义组件模板是通过 Component 类的FRONTEND_DIR找到前端代码来构建/加载的。CLI 中的定位逻辑gradio/cli/commands/components/install_component.py会依次解析组件目录下pyproject.toml拿到包名importlib.import_module(package_name)导入已安装的组件模块遍历模块中所有继承自BlockContext/Component的类找出在 MRO 中自定义了FRONTEND_DIR的类即FRONTEND_DIR in c.__dict__为真的类以该类定义文件所在目录为基准把FRONTEND_DIR相对路径resolve()为绝对路径若组件尚未安装/无法导入则回退到默认的frontend目录并打印警告。由此可以推断FRONTEND_DIR的覆盖不只影响 Gradio 运行时渲染还影响gradio cc dev、gradio cc build、gradio cc install对前端代码位置的解析仓库 CHANGELOG 中也记录了相关修复见 gradio/CHANGELOG.md。因此只要你自定义了FRONTEND_DIR就应保证组件已被gradio cc install正确安装到当前环境否则 CLI 只能按默认frontend/目录回退处理导致找不到前端代码。此外模板中还有一个与目录相关的类属性TEMPLATE_DIR默认DeveloperPath(./templates/)见 gradio/components/base.py它指向组件 Python 包内的静态模板资源目录这正对应pyproject.toml中artifacts [/backend/name/templates, *.pyi]的那条打包规则——理解了这两者的关系你在移动 Python 目录时就不会漏改构建配置。配置变更后的验证清单无论你改动了哪一类配置建议按以下顺序验证防止“本地能跑、打包即废”的问题依赖变更后运行gradio cc install确认 pip 与 npm 依赖都安装成功包名变更后在新环境里python -c import supertextbox验证模块可导入在 Python 3.8 环境运行一次gradio cc build确认dist/下的.whl内含正确的包与模板目录结构变更后运行gradio cc dev确认前端热重载服务能正确加载你的 JavaScript 源码控制台会打印前端开发服务器地址顶层导出变更后在 demo 中显式尝试from supertextbox import AdditionalClass确认导出符号可按预期访问。结语自定义组件之所以对协作友好正是因为它把“约定”做得足够多、把“配置”压缩得足够少包名默认gradio_类名小写、目录默认backend/frontend、导出默认只有组件类。坚持这些默认值能让其他开发者包括未来的你一眼看懂你的组件结构而当你有充分理由偏离默认时——改包名、扩展导出、加依赖、移动目录——只要按本文的方法同步修改pyproject.toml、__init__.py、frontend/package.json与FRONTEND_DIR并配合gradio cc install/gradio cc dev/gradio cc build验证就能安全地让组件长成你想要的样子。如果你希望进一步深入自定义组件的技术细节可继续阅读同目录下的 02_key-component-concepts.md组件核心概念、04_backend.md后端 API 与预/后处理与 05_frontend.md前端开发并结合 gradio/components/base.py 这一组件基类源码逐行印证文中提到的配置语义。【免费下载链接】gradioBuild and share delightful machine learning apps, all in Python. Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/gr/gradio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
