企业官网建设流程全解析

Storybook Addon 面板开发：用 addons.add 与 types.PANEL 注册你的第一个 Addon Panel

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

本篇技术指南聚焦于 Storybook 自定义 UI Addon 中最常见的一种形态——Addon Panel（面板）。文中以仓库 docs/_snippets/storybook-addon-panel-initial.md 给出的最小可运行示例为骨架，逐步讲解如何借助storybook/manager-api的addons.register与addons.add、以及storybook/internal/components提供的AddonPanel组件，把一个带标题、可切换激活态的页面注册进 Storybook 的底栏/侧栏面板区域。读完本文后，你将能独立搭建一个最小面板 Addon，并理解active属性、types.PANEL、ID 命名约定等关键概念，为开发 a11y、themes、controls 这类官方生态中的复杂面板 Addon 打下基础。

这个面板代码片段解决了什么问题

在 Storybook 中，用户看到的“Addons 面板”区域（默认位于画布下方，可通过配置挪到右侧）是一个可扩展的容器。官方 Addon（如 Actions、Controls、Accessibility）都把各自的 UI 塞进这个区域，以Tab + 面板的形式呈现：用户点击某个 Tab，下方对应面板就会被激活显示。

开发者在自己的 Addon 中想要拥有同样的能力，只需完成两件事：

1. 用addons.register()声明一个 Addon 的入口；
2. 用addons.add()把当前 Addon 要渲染的“UI 单元”登记进去，并声明其类型为types.PANEL。

上述逻辑在 docs/addons/addons-api.mdx 中被归类为Core Addon API，本片段即为该 API 中addons.add()一节的配套最小示例。其完整代码为：

import React from 'react'; import { addons, types } from 'storybook/manager-api'; import { AddonPanel } from 'storybook/internal/components'; const ADDON_ID = 'myaddon'; const PANEL_ID = `${ADDON_ID}/panel`; addons.register(ADDON_ID, (api) => { addons.add(PANEL_ID, { type: types.PANEL, title: 'My Addon', render: ({ active }) => ( <AddonPanel active={active}> <div> Storybook addon panel </div> </AddonPanel> ), }); });

这段代码就是面板 Addon 的“最小可行骨架”。把它放进 Addon 的 manager 入口文件（例如 Addon Kit 模板中的src/manager.ts），构建后在 Storybook 的 addons 面板区域就会多出一个名为My Addon的 Tab。接下来逐行拆解它的工作机制。

面板的注册入口：addons.register()

addons.register()是所有 UI 型 Addon 的统一入口函数。它接收两个参数：

• addonId：Addon 的唯一标识字符串，全仓库/全生态内应保持唯一；
• registrationCallback：注册回调，Storybook 在初始化管理器 UI 时会调用它，并把当前 Storybook API 实例作为参数传入。

addons.register(ADDON_ID, (api) => { // 在这里通过 api 访问 Storybook API（selectStory、setQueryParams 等） // 并在此调用 addons.add() 注册本 Addon 的各种 UI 单元 });

片段中ADDON_ID = 'myaddon'就是当前示例 Addon 的唯一名称。而(api)回调参数来自官方文档中反复强调的 Storybook API，它提供了selectStory、setQueryParams、openInEditor、getCurrentStoryData、togglePanel等一系列方法与管理器 UI 交互，详见 docs/addons/addons-api.mdx#storybook-api。在真实生态中，Addon 命名常采用组织名/addon 名风格，例如addons.register('my-organisation/my-addon', ...)（见 storybook-addons-api-register.md）。

值得注意的是：文档中storybook-addons-api-imports.md（见 docs/_snippets/storybook-addons-api-imports.md）明确区分了两个包的使用场景——与管理器 UI打交道的代码从storybook/manager-api导入，而控制预览区行为的代码从storybook/preview-api导入。本片段导入的addons、types正来自storybook/manager-api，因为它们操作的是管理器（manager）一侧的界面。

登记面板：addons.add() 与 types.PANEL

在addons.register()回调内部，紧接着调用addons.add(PANEL_ID, { ... })来登记 UI 单元。针对“面板”这种类型，官方文档（docs/addons/addons-api.mdx#addonsadd）要求提供三个核心字段：

其中type取自storybook/manager-api暴露的types常量对象。把该字段设为types.PANEL即告诉 Storybook：这个 UI 单元应该以“面板”的形式出现在 addons 区域，并作为一个可点击的 Tab。

关于render回调接收的参数，docs/addons/addons-api.mdx 用一个信息提示框特别强调：

The render function is called withactive. Theactivevalue will be true when the panel is focused on the UI.

也就是说，当用户在 addons 区域点击并聚焦到当前面板的 Tab 时，active为true；切换到其他面板/隐藏面板时则为false。这是面板 Addon 必须处理的关键状态——它决定了面板内容何时真正渲染、何时执行副作用（例如当面板失焦时暂停监听事件或释放资源）。

ID 命名约定：PANEL_ID =${ADDON_ID}/panel

片段中有两行容易被忽略但极其重要的常量：

const ADDON_ID = 'myaddon'; const PANEL_ID = `${ADDON_ID}/panel`;

这是 Storybook 生态中的一种通用约定：Addon 注册时使用一个基础 ID（ADDON_ID），其下每类 UI 单元（panel、tool、tab）再各自派生出子 ID。派生方式通常是ADDON_ID + '/' + 单元类型，例如：

• 面板：myaddon/panel
• 工具栏按钮：myaddon/tool
• 自定义 Tab：myaddon/tab

这种分层命名能避免同一个 Addon 内不同单元之间、以及不同 Addon 之间产生 ID 冲突。如果你在写更复杂的 Addon（同时含 toolbar 和 panel，例如官方 a11y Addon），通常会定义TOOL_ID =${ADDON_ID}/tool、`PANEL_ID = `${ADDON_ID}/panel并分别addons.add()。ID 还会被api.setConfig({ selectedPanel })（见 docs/addons/addons-api.mdx 中的配置表格）等 API 引用，用来把某个面板设为默认选中项。

AddonPanel 组件与 active 属性的配合

render函数的返回值直接决定了面板区域的 UI。片段中使用了storybook/internal/components提供的AddonPanel容器组件：

<AddonPanel active={active}> <div> Storybook addon panel </div> </AddonPanel>

把回调中解构出的active原样传给AddonPanel是标准用法。AddonPanel承担了面板外层容器（Tab 页签切换后的内容承载区）的职责，active用来控制该面板内容区是否处于可见/激活状态，避免未激活时仍挂载内容造成性能浪费或非预期副作用。

仓库中的官方 Addon 也遵循同样的模式。以官方可访问性 Addon code/addons/a11y/src/manager.tsx 为例，其核心注册代码如下：

addons.register(ADDON_ID, (api) => { addons.add(PANEL_ID, { title: Title, type: types.PANEL, render: ({ active = true }) => ( <A11yContextProvider>{active ? <A11YPanel /> : null}</A11yContextProvider> ), paramKey: PARAM_KEY, }); });

可以看到，官方实现同样由addons.register+addons.add+type: types.PANEL+ 从render接收active组成，并额外通过active ? <A11YPanel /> : null做条件渲染——这正体现了“面板激活才渲染内容”的推荐实践：从源码结构看，这种写法可以有效避免失焦面板持续占用 DOM 与计算资源。其单元测试（见 code/addons/a11y/src/manager.test.tsx）也通过断言注册对象中type === api.types.PANEL来校验面板类型是否注册正确，印证了types.PANEL在 API 层面的真实语义。

在 addon-types 语境中定位面板 Addon

在 Storybook 的 Addon 分类体系中（详见 docs/addons/addon-types.mdx#panels），UI-based Addon 可渲染三类元素：

• Panels（面板）：在 addons 区域中显示自定义 UI，是生态中最常见的 Addon 类型，官方@storybook/addon-a11y即采用此模式；
• Toolbars（工具栏）：向 Storybook 顶部工具栏添加自定义工具按钮；
• Tabs（自定义页签）：在画布区域新增独立 Tab。

面板 Addon 的价值在于：它能与当前选中的 story 联动，展示组件状态、参数调试控件、测试结果、无障碍违规列表等“伴随性信息”。本文讨论的types.PANEL与AddonPanel组合正是支撑这类能力的核心载体。

完整接入 Storybook 的落地方案

要把上面的骨架片段真正跑起来，你需要把它放置到 Addon 包中会被 Storybook manager 加载的入口文件里。结合 docs/addons/writing-addons.mdx 的说明，落地的关键步骤与文件布局如下：

1. Addon 包结构：在 Addon 源码目录（典型如 Addon Kit 模板生成的my-addon/src/）中维护 manager 侧代码。使用 TypeScript 时文件后缀为.ts，使用 JavaScript 时后缀为.js——这正是片段头注filename="my-addon/src/manager.js|ts"的含义，即该代码既可存为manager.ts也可存为manager.js。

2. 包内 React 版本约束：由于面板直接渲染进 Storybook 的 manager UI，带 UI 的 Addon 必须与 Storybook 使用相同的 React 版本（见 docs/addons/writing-addons.mdx 中的提示）。如果你的组件库使用不同 React 版本，则不能把组件直接嵌进 manager 代码，而应让 Addon 作为独立包发布、通过预览区通信来解耦。

3. 构建与发布：Addon 在管理器与预览区运行环境不同，需要产出不同 bundle。典型发布产物在package.json中以exports声明入口，例如"./manager": "./dist/manager.mjs"，并在bundler字段中列出managerEntries，从而让 Storybook 正确加载这段 manager 代码（完整字段可参考 docs/addons/writing-addons.mdx 中 Packaging 一节的示例）。

4. 验证：本地运行storybook dev后，切换到任意 story，观察 addons 区域是否出现标题为My Addon的 Tab；点击它，面板内容区应显示Storybook addon panel这段文字。

从初始面板到完整 Addon 的进阶路线

这段代码名为storybook-addon-panel-initial，“initial（初始）”一词点明了它的定位——它只负责把面板“立起来”，是一个可运行的起点。在此基础上继续演进，通常会涉及以下能力（均属 docs/addons/addons-api.mdx 的 API 范畴）：

• 数据持久化与多单元协作：使用useAddonStatehook 让面板状态跨 Storybook UI 生命周期保存（例如记住上次的开关状态）；
• 订阅事件通道：通过addons.getChannel()或useChannel在管理器与预览 iframe 之间收发消息，面板因此能实时反映当前 story 的运行状态；
• 读取当前 story 信息：用api.getCurrentStoryData()或useParameter获取当前 story 的参数，据此渲染与 story 强相关的面板内容；
• 控制面板可见性：用api.togglePanel()编程式展开/收起整个 addons 面板区域；
• 设置默认选中面板：通过api.setConfig({ selectedPanel: 'myaddon/panel' })让 Storybook 启动时默认聚焦到本 Addon 的面板（docs/addons/addons-api.mdx 中给出了storybook/actions/panel这类真实取值）。

在官方生态中，从 A11y 面板（展示无障碍违规列表）、Controls 面板（调试组件参数）到测试相关面板，本质上都是对本文骨架的扩展：以types.PANEL挂载入口，以active控制渲染时机，再通过 manager/preview 之间的通道把数据灌入面板。掌握这段最小代码，你就拿到了进入整个 Storybook Addon 生态的钥匙。

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook