Storybook 附加组件 Web 组件 HTML

一个 Storybook 附加组件，用于从 Web 组件中提取和显示语法高亮 HTML

开发脚本

• npm run start 以监控模式运行 babel 并启动 Storybook
• npm run build 构建和打包您的附加组件代码

从 TypeScript 切换到 JavaScript

不想使用 TypeScript？我们提供一个方便的弹出命令：npm run eject-ts

这会将所有代码转换为 JS。这是一个破坏性的过程，因此建议您在开始编写任何代码之前运行它。

包含什么？

附加组件代码位于 src 中。它演示了所有与核心附加组件相关的概念。三个基于 UI 的附加组件范式

• src/Tool.tsx
• src/Panel.tsx
• src/Tab.tsx

这些与附加组件本身一起在 src/manager.ts 中注册。

管理状态并与故事交互

• src/withGlobals.ts 和 src/Tool.tsx 演示了如何使用 useGlobals 来管理全局状态并修改故事的内容。
• src/withRoundTrip.ts 和 src/Panel.tsx 演示了使用通道进行双向通信。
• src/Tab.tsx 演示了如何使用 useParameter 来访问当前故事的参数。

您的附加组件可能会使用一种或多种这些模式。您可以随意删除未使用的代码。相应地更新 src/manager.ts 和 src/preview.ts。

最后，在 src/constants.ts 中配置您的附加组件名称。

捆绑

附加组件可以通过多种方式与 Storybook 项目交互。建议您在开始之前先熟悉基础知识。

• 管理器条目用于向 Storybook 管理器 UI 添加 UI 或行为。
• 预览条目用于向渲染故事的预览 iframe 添加 UI 或行为。
• 预设用于修改 Storybook 配置，类似于用户如何配置其 main.ts 配置。

由于这些地方中的每一个都代表着具有不同功能和模块的不同环境，因此还建议相应地拆分和构建您的模块。此附加组件工具包附带一个预配置的捆绑配置，它支持这种拆分，您可以随意根据需要修改和扩展它。

您可以在package.json#bundler 属性中定义哪些模块匹配哪些环境

• exportEntries 是用户可以从任何需要的地方手动导入的模块条目列表。例如，您可能有一些装饰器，用户需要将其导入其 preview.ts 文件中，或者一些可以在其 main.ts 文件中使用的实用程序函数。
• managerEntries 是专为管理器 UI 设计的模块条目列表。这些模块将捆绑到 ESM，并且不包含类型，因为它们主要由 Storybook 直接加载。
• previewEntries 是专为预览 UI 设计的模块条目列表。这些模块将捆绑到 ESM，并且不包含类型，因为它们主要由 Storybook 直接加载。

管理器和预览条目仅在浏览器中使用，因此它们仅输出 ESM 模块。导出条目可以在浏览器和 Node 中使用，具体取决于其用例，因此它们同时输出 ESM 和 CJS 模块。

全局化包

Storybook 提供了一组预定义的包，这些包在管理器 UI 和预览 UI 中可用。在您的附加组件的最终包中，不应包含这些包。相反，导入应该保留在适当的位置，使 Storybook 能够在 Storybook 构建过程中用实际的包替换这些导入。

管理器和预览之间的包列表有所不同，这就是 managerEntries 和 previewEntries 之间略有区别的原因。最值得注意的是，react 和 react-dom 在管理器中预捆绑，但在预览中没有。这意味着您的管理器条目可以使用 React 来构建 UI，而无需捆绑它或直接引用它。因此，即使您在生产环境中使用 React，将其作为 devDependency 也是安全的。将 React 作为对等依赖项将不必要地强制您的用户安装 React。

此规则的一个例外是，如果您使用 React 将 UI 注入到预览中，而预览没有预捆绑 React。在这种情况下，您需要将 react 和 react-dom 移动到对等依赖项中。但是，我们通常建议不要使用这种模式，因为它会将您附加组件的使用限制在基于 React 的 Storybooks 中。

元数据

Storybook 附加组件在目录中列出，并通过 npm 分发。目录通过查询 npm 注册表中的 package.json 中的 Storybook 特定元数据来填充。此项目已配置了示例数据。在附加组件元数据文档中了解有关可用选项的更多信息。

文档

为了帮助社区使用您的附加组件并了解其功能，请对其进行全面记录。

要开始，请用此示例模板中的内容替换此自述文件，该模板模仿了基本附加组件（如Actions）的记录方式。然后更新内容以描述您的附加组件。

示例文档模板

# My Addon

## Installation

First, install the package.

```sh
npm install --save-dev my-addon
```

Then, register it as an addon in `.storybook/main.js`.

```js
// .storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  // ...rest of config
  addons: [
    '@storybook/addon-essentials'
    'my-addon', // 👈 register the addon here
  ],
};

export default config;
```

## Usage

The primary way to use this addon is to define the `exampleParameter` parameter. You can do this the
component level, as below, to affect all stories in the file, or you can do it for a single story.

```js
// Button.stories.ts

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';

import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    myAddon: {
      exampleParameter: true,
      // See API section below for available parameters
    }
  }
};

export default meta;
```

Another way to use the addon is...

## API

### Parameters

This addon contributes the following parameters to Storybook, under the `myAddon` namespace:

#### `disable`

Type: `boolean`

Disable this addon's behavior. This parameter is most useful to allow overriding at more specific
levels. For example, if this parameter is set to true at the project level, it could then be
re-enabled by setting it to false at the meta (component) or story level.

### Options

When registering this addon, you can configure it with the following options, which are passed when
registering the addon, like so:

```ts
// .storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  // ...rest of config
  addons: [
    '@storybook/essentials',
    {
      name: 'my-addon',
      options: {
        // 👈 options for my-addon go here
      },
    },
  ],
};

export default config;
```

#### `useExperimentalBehavior`

Type: `boolean`

Enable experimental behavior to...

版本管理

设置

此项目配置为使用auto 进行版本管理。它生成变更日志并将其推送到 GitHub 和 npm。因此，您需要配置对这两者的访问权限

• NPM_TOKEN 创建一个具有读取和发布权限的令牌。
• GH_TOKEN 创建一个具有 repo 范围的令牌。

然后打开您的 package.json 并编辑以下字段

• 名称
• 作者
• 存储库

本地

要在本地使用 auto，请在项目根目录中创建一个 .env 文件，并将您的令牌添加到其中

GH_TOKEN=<value you just got from GitHub>
NPM_TOKEN=<value you just got from npm>

最后，在 GitHub 上创建标签。您将在将来更改包时使用这些标签。

npx auto create-labels

如果您在 GitHub 上查看，您现在会看到一组标签，auto 希望您使用它们。使用这些标签来标记将来的拉取请求。

GitHub Actions

此模板附带已设置的 GitHub actions，以便在有人推送您的存储库时发布您的附加组件。

转到 设置 > 机密，单击 新建存储库机密，并添加您的 NPM_TOKEN。

创建版本

要本地创建版本，您可以运行以下命令，否则 GitHub action 会为您创建版本。

npm run release

这将

• 构建和打包附加组件代码
• 提升版本
• 将版本推送到 GitHub 和 npm
• 将变更日志推送到 GitHub