Gradio 自定义组件（Custom Components）配置详解：包名、导出、依赖与目录结构全攻略-酒店常州论坛

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 = f"gradio_{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 Spaces；
gradio 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_.toml）：

dependencies = ["gradio>=6.0,<7.0"]

自定义组件依赖打包在 wheel 中后，会被 pip 在安装时自动解析安装，因此发布到 PyPI 的依赖必须写到dependencies，而不是仅仅在本地环境手动 pip 安装。

一个极易踩坑的点是：修改依赖后若仅更新了pyproject.toml，开发环境并不会自动同步。因为模板默认使用可编辑安装，依赖条目变更需要重新执行安装命令才能反映到当前环境。所以请牢记文档给出的 Tip：

修改dependencies后，务必重新运行gradio cc install！

gradio cc install内部会依次执行（见 gradio/cli/commands/components/install_component.py）：

pip 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`覆盖

默认布局：`backend`+`frontend`

gradio 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_DIR

FRONTEND_DIR是 Gradio 组件基类上预置的类属性，其默认值定义在 gradio/components/base.py：

FRONTEND_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），仅供参考

企业官网建设流程全解析