creating-backstage-extension-blueprint

创建前端扩展蓝图

何时使用此技能

你正在编写一个前端插件，并希望为其他插件或模块提供一种类型安全、结构化的方式，让它们能够向该插件贡献 UI。比如：

• 一个仪表盘插件，希望模块能注册自定义仪表盘面板
• 一个代码质量插件，希望模块能注册显示在结果页上的其他检查项
• 一个可复用的“功能标志”插件，让模块为每个标志贡献 UI 控件

Backstage 本身也使用了相同模式，例如 PageBlueprint、EntityCardBlueprint、EntityContentBlueprint、FormFieldBlueprint、ApiBlueprint。你要为自己的插件创建这样一个蓝图。

不要在以下情况下创建蓝图：

• 已有内置蓝图可以满足需求（例如，目录页卡片使用 EntityCardBlueprint，scaffolder 字段使用 FormFieldBlueprint 等）
• 扩展点只会触发一次，并且只有你的插件会向其中添加内容——直接编写常规扩展，省去蓝图这一层
• 你正在编写后端插件——后端使用扩展点（createExtensionPoint），而不是蓝图。请参阅 using-backstage-backend-system/references/extension-points.md

要构建的内容

蓝图由两个相互关联的部分组成：

1. 蓝图本身（createExtensionBlueprint）——类型安全的工厂，其他插件可以调用 MyBlueprint.make({ name, params }) 来贡献单个实例。
2. 父扩展——声明 input，并渲染或使用附加到该输入的所有内容。通常，这是你在插件的 extensions.tsx 中定义的 PageBlueprint 扩展。

两部分缺一不可，并且必须对输入名称以及贡献所生成的数据引用保持一致。大多数插件会在同一个 extensions.tsx 文件（或同目录下的模块）中编写这两部分。

选择合适的模式

要构建的内容	参考资料
蓝图本身（createExtensionBlueprint 定义）	references/defining-the-blueprint.md
通过 inputs 收集贡献内容的父扩展	references/parent-collecting-extensions.md

两种调用模式

• 独立使用：编辑现有前端插件，以添加新蓝图或完善现有蓝图。
• 脚手架后（由 creating-backstage-plugin 针对 frontend-plugin 调用）：较为少见——仅在用户明确表示“我希望我的插件可以由其他模块扩展”时使用。大多数插件不需要此模式，也不应采用。

常见注意事项

• 蓝图位于前端。后端对应的是 createExtensionPoint——API 不同，包也不同。如果你既想实现可扩展的 UI，又想实现可扩展的后端行为，就需要分别创建两者，并使用不同的符号和文档。
• 蓝图的 attachTo 必须指向同一插件 extensions 数组中某个实际扩展声明的输入。ID 或输入字符串不匹配会导致静默的“无贡献”——蓝图可以编译，但永远不会有任何内容附加到它上面。
• 谨慎选择 output——这里定义了每个贡献都必须提供的数据引用。如果蓝图要求 coreExtensionData.reactElement 和自定义数据引用，那么每个使用方的工厂都必须提供两者。之后再添加必需的数据引用会对使用方造成破坏性变更。
• 使用 dataRefs 定义可选的命名访问器，供父级读取贡献中的数据（例如，“贡献可以选择提供一个排序键，可通过 MyBlueprint.dataRefs.sortKey 访问”）。必需输出放在 output 中；可选数据或类型化的贡献数据放在 dataRefs 中。
• configSchema 允许采用方通过 app-config 覆盖每项贡献的设置，而无需修改代码。只有当贡献有面向用户的设置（标题、路径、筛选条件）时才定义它；否则跳过。
• factory 是一个生成器——使用 function* (...) 并生成 ref(value) 调用。每个 yield 都会添加一项扩展数据。循环、条件判断以及看似异步的工作都会在工厂内部同步执行；真正的异步工作应放在参数传入的 loader 回调中。
• 两阶段参数（createExtensionBlueprintParams）——对于参数必须采用函数形式的蓝图（例如 { field: () => Promise<...> }），请使用 createExtensionBlueprintParams 包装，以便使用方获得类型推断。真实示例请参阅 ../backstage/plugins/scaffolder-react/src/next/blueprints/FormFieldBlueprint.tsx 中的 FormFieldBlueprint。
• make 与 makeWithOverrides：使用方通常调用 MyBlueprint.make({ name, params })。更高级的使用方可以通过 makeWithOverrides 覆盖 factory，以包装原工厂——当在蓝图上添加 inputs: 时会用到。请在 README 中说明 make；仅在高级场景下提及 makeWithOverrides。