using-backstage-ui

Backstage UI（BUI）模式

何时使用此技能

• 在 Backstage 插件中编写或编辑任何前端组件
• 为布局、排版、表单输入、对话框、菜单、标签页、表格等选择合适的组件
• 设置组件样式（BUI 使用 CSS modules 和设计令牌，而不是 makeStyles）
• 添加图标（使用 @remixicon/react）

设置

使用 yarn new 搭建的新插件会自动包含 @backstage/ui。如果手动安装：

yarn add @backstage/ui @remixicon/react

然后将样式表添加到应用入口（packages/app/src/index.tsx 或类似文件）：

import '@backstage/ui/css/styles.css';

选择合适的组件

需求	组件	参考
页面布局 / 容器	Box、Container、Flex、FullPage、Grid	references/components.md
排版	Text	references/components.md
按钮 / 操作	Button、ButtonIcon、ButtonLink	references/components.md
表单	TextField、PasswordField、SearchField、Select、Combobox、Checkbox、RadioGroup、Switch、DatePicker、DateRangePicker	references/components.md
反馈	Alert、Skeleton、Tooltip、Tag、TagGroup	references/components.md
覆盖层	Dialog、Menu、Popover	references/components.md
导航	Tabs、Header、PluginHeader、Link	references/components.md
数据	Table（+ useTable hook）、List（+ ListRow）、Avatar、Card	references/components.md
图标	@remixicon/react（例如 RiSearchLine、RiAddLine）	references/icons.md
样式	使用 BUI 令牌的 CSS modules（--bui-space-*、--bui-fg-*、--bui-bg-*）	references/styling.md

两种调用模式

• 独立模式（开发过程中）：用户正在编辑现有插件组件。选择相关参考并应用。
• 脚手架完成后（由 creating-backstage-plugin 为任何前端模板调用）：将 BUI 默认设置应用到刚搭建的插件示例组件，确保导入来自 @backstage/ui，样式使用带有 BUI 令牌的 CSS modules。

常见问题

• BUI ≠ Material UI。不要混用属性名称：disabled → isDisabled；variant="contained" → variant="primary"。
• Flex 使用 justify="between"（而不是 space-between）；gap 通过内联 style 或 BUI 令牌设置。
• Tooltip 必须以 TooltipTrigger 为父级。
• TextField 的 onChange 直接接收字符串，而不是事件对象。
• 有一种已知的回退情况：BUI 没有对应项——@material-ui/lab 的 Timeline 没有 BUI 替代组件。这种情况下请使用 MUI。

数据获取约定

不要手动使用 useState 管理加载、错误和数据状态。请使用 react-use 钩子：

• useAsync(fn, deps) — 在挂载时以及 deps 变化时运行异步函数。用于“在组件渲染或其 props 变化时加载数据”。
• useAsyncFn(fn) — 返回 [state, callback]。用于“在用户执行某项操作时加载数据”（例如点击按钮、提交表单等）。

在此代码库中，手动使用 useState 管理 { loading, error, value } 是一种反模式：这会重复实现钩子已妥善处理的逻辑（竞态条件、获取数据期间卸载等）。catalog 和 identity 中的示例使用了 useAsync；任何获取数据的地方都应如此。

import useAsyncFn from 'react-use/lib/useAsyncFn';
import { Button, Skeleton, Alert, Text } from '@backstage/ui';

export const FetchOnDemand = () => {
  const [{ loading, error, value }, fetch] = useAsyncFn(async (id: string) => {
    return await someApi.get(id);
  }, []);

  return (
    <>
      <Button onClick={() => fetch('foo')}>Fetch</Button>
      {loading && <Skeleton width={200} height={20} />}
      {error && <Alert status="danger" title={error.message} />}
      {value && <Text>{value.name}</Text>}
    </>
  );
};