creating-backstage-entity-page-extension

创建目录实体页面扩展

何时使用此技能

• 向目录实体的 概览 选项卡添加卡片（例如“在关联到 Jira 项目的组件上显示 Jira 项目信息”）
• 向目录实体页面添加整个 选项卡（具有独立 URL 路径的内容面板）（例如在组件上添加“/incidents”选项卡，列出该组件的事件）
• 根据实体种类、规范类型、注释是否存在或任何自定义谓词，筛选扩展的显示条件

这是搭建 frontend-plugin-module 最常见的原因。你正在编写的插件通过这些蓝图扩展宿主的目录插件。

选择合适的模式

构建内容	模式	参考
实体概览选项卡上的卡片	EntityCardBlueprint.make({ name, params: { loader, filter?, type? } })	references/card.md
实体页面上的完整选项卡（具有独立 URL 路径）	EntityContentBlueprint.make({ name, params: { path, title, loader, filter?, group?, icon? } })	references/content.md

这两个蓝图都来自 @backstage/plugin-catalog-react/alpha。它们共用以下内容：

• 用于对渲染组件进行代码分割的 loader: () => Promise<JSX.Element>。
• 控制扩展何时显示的 filter 参数（参见下文“实体筛选”）。
• 组件在目录实体上下文中渲染 — 使用来自 @backstage/plugin-catalog-react 的 useEntity() 读取当前实体。

两种调用模式

• 独立模式：编辑一个面向目录的现有 frontend-plugin-module。选择合适的参考（卡片或内容），然后添加扩展。
• 脚手架后模式（由 creating-backstage-plugin 为面向 catalog 的 frontend-plugin-module 模板调用）：搭建用户描述的扩展，以及它们所渲染的组件。

实体筛选

两个蓝图上的 filter 参数决定扩展适用于哪些实体。支持以下三种形式：

1. 字符串（最常见）：'kind:component'、'kind:component,spec.type:service'、'metadata.annotations.acme.com/jira-project'。逗号分隔表示 AND；同一键的多种形式表示 OR。
2. FilterPredicate（结构化）：使用 Zod 验证的对象形式，可实现更丰富的逻辑。请对照 ../backstage/packages/filter-predicates/src/ 验证确切结构。
3. 函数：(entity: Entity) => boolean — 可进行完整的编程控制。请谨慎使用 — 字符串筛选器更适合与上游配置覆盖系统组合。

如果省略 filter，扩展会对所有实体种类显示。这几乎总是不正确 — 请设置筛选条件，即使只是 'kind:component'。

常见注意事项

• Blueprint 来自 @backstage/plugin-catalog-react/alpha（目前为 @alpha）。请根据 ../backstage/plugins/catalog-react/src/alpha/blueprints/ 跟踪导入路径。
• 组件本身从 @backstage/plugin-catalog-react（主入口，而非 /alpha）导入 useEntity。该 Hook 返回类型为 Entity 的 { entity }——要以类型安全的方式访问 metadata、spec 等字段，请使用 @backstage/catalog-model 中的 catalog entity 模型。
• useEntity 只能在由这些 Blueprint 之一渲染的组件内使用——在 catalog entity 上下文之外调用会抛出异常。
• 为实现代码拆分，必须使用 loader: () => Promise<JSX.Element> 形式。不要传入同步组件导入——请使用 () => import('./MyCard').then(m => <m.MyCard />)。
• 对于特定 entity 的数据获取，请将 useEntity 与 using-backstage-frontend-system 中的数据 Hook 约定结合使用（用 useAsync 包装 fetchApi.fetch 的 Hook）。将 entity.metadata.name 或某个 annotation 作为缓存键传入。
• 宿主应用的 catalog 插件拥有路由 entity-content:catalog/overview（卡片挂载位置）和 page:catalog/entity（内容标签页挂载位置）。你的模块会安装到与 catalog 插件相同的 backend 中——采用者通过 backend.add(...) 和 app.installPlugin(...) 安装即可；无需其他操作。