Storybook 插件故事覆盖面板

一个 Storybook 插件，与 @storybook/addon-coverage 配合使用，在 Storybook UI 面板中显示覆盖率指标。

开发脚本

• npm run start 在 watch 模式下运行 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 项目交互。建议在开始之前熟悉 基础知识。

• Manager 入口用于向 Storybook manager UI 添加 UI 或行为。
• Preview 入口用于向故事渲染所在的预览 iframe 添加 UI 或行为。
• 预设用于修改 Storybook 配置，类似于 用户如何配置他们的 main.ts 配置。

由于这些位置都代表着不同的环境，具有不同的特性和模块，因此也建议相应地拆分和构建您的模块。这个插件工具包带有一个预配置的 打包配置，支持这种拆分，您可以根据需要自由修改和扩展它。

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

• exportEntries 是一个模块入口列表，用户可以在任何需要的地方手动导入。例如，您可以有用户需要导入到 preview.ts 文件中的装饰器，或者可以在 main.ts 文件中使用的实用函数。
• managerEntries 是一个仅用于 manager UI 的模块入口列表。这些模块将被打包为 ESM，并且不包含类型，因为它们主要由 Storybook 直接加载。
• previewEntries 是一个仅用于预览 UI 的模块入口列表。这些模块将被打包为 ESM，并且不包含类型，因为它们主要由 Storybook 直接加载。

Manager 和 preview 入口仅在浏览器中使用，因此它们只输出 ESM 模块。Export 入口根据其用例可以在浏览器和 Node 中使用，因此它们同时输出 ESM 和 CJS 模块。

全局化包

Storybook 提供了一组预定义的包，可在 manager UI 和 preview UI 中使用。在您的插件的最终打包中，不应包含这些包。相反，导入应保留原样，允许 Storybook 在 Storybook 构建过程中将这些导入替换为实际的包。

manager 和 preview 之间的包列表有所不同，这就是为什么 managerEntries 和 previewEntries 之间存在细微差异的原因。最值得注意的是，react 和 react-dom 在 manager 中预打包，但在 preview 中没有。这意味着您的 manager 入口可以使用 React 构建 UI，而无需打包它或直接引用它。因此，即使您在生产环境中使用它，将 React 作为 devDependency 也是安全的。将 React 作为 peer dependency 会不必要地强制您的用户安装 React。

此规则的一个例外是，如果您使用 React 将 UI 注入到 preview 中，而 preview 没有预打包 React。在这种情况下，您需要将 react 和 react-dom 移动到 peer dependency。但是，我们通常不建议这种模式，因为它会限制您的插件仅用于基于 React 的 Storybook。

元数据

Storybook 插件在 目录中列出，并通过 npm 分发。目录通过查询 npm 注册表中的 package.json 中 Storybook 特定的元数据来填充。本项目已配置示例数据。了解更多可用选项，请参阅 插件元数据文档。

文档

为了帮助社区使用您的插件并了解其功能，请进行详尽的文档编写。

要开始使用，请将此 README 替换为此示例模板中的内容，该模板模仿了核心插件（如 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 并编辑以下字段

• name
• author
• repository

本地

要在本地使用 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，以便在任何人推送到您的仓库时发布您的插件。

转到 Settings > Secrets，点击 New repository secret，然后添加您的 NPM_TOKEN。

创建发布

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

npm run release

这将

• 构建并打包插件代码
• 提升版本
• 将发布推送到 GitHub 和 npm
• 将变更日志推送到 GitHub