Backstage主屏幕的蜕变！渲染自定义小部件的必备指南 🛠️

各位平台工程师们，大家好！ 👋 引入Backstage后，最想做的事情之一可能就是为“我们团队定制一个专属的主屏幕”吧。

您编写了很棒的自定义小部件代码，但为什么它没有出现在主屏幕上呢？仅仅创建组件是不够的，您还需要一个“连接纽带”，让Backstage主页插件能够识别它。接下来，我将详细介绍其核心秘诀！

---

1. 主页小部件的基本原理 🧩

Backstage的主页（Home page）不仅仅是一个页面，它是由多个小部件（Widgets）组成的动态布局。您创建的自定义小部件若要显示在主屏幕上，需要准备两大要素：

1. 小部件组件（Widget Component）： 实际呈现在屏幕上的React代码。
2. 小部件扩展（Widget Extension）： 将此组件包装起来，以便Backstage能将其识别为“主页小部件”的过程。

---

2. 步骤1：创建小部件组件 💻

首先，您需要编写要在主屏幕上显示的实际内容。这通常位于插件的src/components文件夹中。

TypeScript

// MyCustomWidget.tsx
import React from 'react';
import { InfoCard } from '@backstage/core-components';

export const MyCustomWidget = () => (
  <InfoCard title="오늘의 공지사항 📢">
    <p>플랫폼 팀에서 전합니다. 오늘은 정기 점검일입니다!</p>
  </InfoCard>
);

---

3. 步骤2：核心！定义小部件扩展（Extension） 🔗

这一步正是对问题的直接回答。您不能仅仅导出小部件，而必须使用createCardExtension函数进行注册。

• 原因： Backstage主页插件通过此扩展读取小部件的元数据，并安全地将小部件放置在布局引擎中。

TypeScript

// plugin.ts
import { createCardExtension } from '@backstage/plugin-home';
import { rootRouteRef } from './routes';

export const MyCustomWidgetExtension = homePlugin.provide(
  createCardExtension({
    name: 'MyCustomWidget',
    title: '나의 커스텀 위젯',
    components: () => import('./components/MyCustomWidget').then(m => m.MyCustomWidget),
    // 可以设置点击小部件时要导航的路径等。
  }),
);

---

4. 步骤3：将小部件放置在HomePage.tsx中 🏠

定义了扩展（Extension）之后，现在需要前往实际的主页配置文件（App.tsx或HomePage.tsx），并将此小部件添加到渲染树中。

TypeScript

// App.tsx 或 HomePage.tsx
import { MyCustomWidgetExtension } from '@internal/plugin-my-custom-plugin';

// ... (省略)
<Grid item xs={12} md={6}>
  <MyCustomWidgetExtension />
</Grid>

此时请注意！ 如果小部件依赖于其他插件或需要权限（Permissions），则相应的上下文必须存在于上层。

---

5. 成功渲染的检查清单 ✅

如果小部件没有显示在屏幕上，请务必检查以下3点！

1. 是否导出： 您是否已从插件的index.ts中正确导出了小部件扩展（MyCustomWidgetExtension）？
2. 布局设置： 小部件是否在标签等布局组件中占据了过小的区域？（检查xs、md值）
3. 动态导入（Lazy Loading）： 如果您使用了`components: () => import(…)`形式，请确认路径是否准确。

---

6. 总结：您需要做什么？ 📝

要在Backstage主页上渲染自定义小部件，您必须执行以下操作：

• 您必须使用createCardExtension包装（Wrap）并导出小部件。
• 然后，您必须将该扩展组件放置在应用程序的主页布局（HomePage.tsx）内。

---

🏁 总结

Backstage主页是开发人员的“起点”。尝试创建自定义小部件，以显示团队成员最常需要查看的信息（例如：值班轮换、构建状态、团队公告）。一个小小的部件就能大大提高整个团队的生产力！ 🚀

---