# @aurelia/storybook 中文文档

规范地址：https://npmcn.com/package/%40aurelia/storybook/

版本：3\.0\.0
npm 元数据更新时间：2026-08-05T21:12:50.469Z
中文译文更新时间：2026-11-07T05:06:47.942Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aurelia/storybook
原文对照：https://npmcn.com/package/%40aurelia/storybook/?lang=original
项目主页：https://github.com/aurelia/storybook#readme
源码仓库：https://github.com/aurelia/storybook

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：137 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：1 个
- peer 依赖：@aurelia/vite-plugin ^2\.0\.0-rc\.2，@aurelia/webpack-loader ^2\.0\.0-rc\.2，@rsbuild/core ^1\.7\.2 \|\| ^2\.0\.0，@storybook/builder-vite ^10\.5\.6，@storybook/builder-webpack5 ^10\.5\.6，aurelia ^2\.0\.0-rc\.2，storybook ^10\.5\.6，storybook-builder-rsbuild ^3\.4\.0，ts-loader ^9\.6\.2
- 首次发布：2025-02-05T06:48:59.078Z
- 最新版本发布：2026-08-05T21:12:50.085Z
- 近 30 天下载量：5132（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 5 个）

## 中文简介

使用 Vite 、 Webpack 或 Rsbuild/ Rspack 渲染 Aurelia 2 组件的故事书插件

## 安装

```sh
npm install @aurelia/storybook
```

也可以使用：`pnpm add @aurelia/storybook`、`yarn add @aurelia/storybook`、`bun add @aurelia/storybook`

## README

# @aurelia/故事书

`@aurelia/storybook` 运行 Aurelia 2 组件 在故事书 10 。 它提供渲染器,构建器预设,CSF类型,可绑定控制,docs支持,可移植故事,以及从一等故事书框架所期望的测试集成.

该框架与Vite、Webpack 5和Rsbuilding/Rspack合作。 你准备好了 `component` 在故事元数据中写出正常的"故事本"故事; 里面没有渲染器锅炉板 `.storybook/preview.ts`。 。 。 .

## 兼容性

| 编 | 支持的版本 |
| --- | --- |
| 奥雷利亚 | `2.0.0-rc.2` |
| 故事书 | `10.5.x` |
| 节点.js | `^20.19.0` 或者说 `>=22.12.0` |
| 虚拟构建器 | 维特 `7.x` 或者说 `8.x` 财务报告和审定财务报表 `@storybook/builder-vite` `10.5.x` |
| 网页包构建器 | `@storybook/builder-webpack5` `10.5.x` |
| Rsbuilding 构建器 | 建设 `2.x` 财务报告和审定财务报表 `storybook-builder-rsbuild` `3.4.x` |

奥雷利亚 `2.0.0-rc.2` 支持Vite 8的Oxc管道,包括TC39装饰. 不需要额外的 Babel 或 SWC 配置 .

## 何谓有效

-   CSF 3 和输入的 CSF 工厂, 装有装饰器、装入器、 全球器、 标签、 故事扩展和 `run`
-   自动组件渲染, 将可装订的组件映射到 Storybook 参数和控件
-   通过操作和互动测试 `storybook/test`
-   播放函数 `mount`
-   自动文档, MDX, 可绑定的参数类型、 组件描述和动态 Aurelia 源标记
-   故事层面和全球Aurelia资源、DI注册、容器和设置钩
-   live arg 更新而不重新启动 Aurelia app; 结构变化 清空重挂载
-   便携式故事通过 `composeStory`, (中文(简体) ), `composeStories`,以及 `setProjectAnnotations`
-   Vite、Webpack 5和Rsbuilt/Rspack开发和静态建筑
-   故事书的Vitest addon 运行真正的铬测试

## 安装

从您的构建者的命令开始 。 已存在的 Aurelia app 通常已有 Aurelia 构建器插件或加载器 .

### 维特

```bash
npm install --save-dev @aurelia/storybook storybook @storybook/builder-vite @aurelia/vite-plugin
```

Vite 7和Vite 8获得支持. 使用 Vite 8 时 `@aurelia/vite-plugin` `2.0.0-rc.2` 或更新.

### 网页包 5

```bash
npm install --save-dev @aurelia/storybook storybook @storybook/builder-webpack5 @aurelia/webpack-loader ts-loader
```

### 建设/包装

```bash
npm install --save-dev @aurelia/storybook storybook storybook-builder-rsbuild @rsbuild/core @aurelia/webpack-loader
```

添加 `@storybook/addon-docs`, (中文(简体) ), `@storybook/addon-a11y`,并视需要提供其他补充.

## 配置故事书

对于 Vite , 创建 `.storybook/main.ts`数字 :

```ts
import { defineMain } from '@aurelia/storybook/node';

export default defineMain({
  stories: ['../src/**/*.@(mdx|stories.@(ts|js))'],
  addons: ['@storybook/addon-docs', '@storybook/addon-a11y'],
  framework: {
    name: '@aurelia/storybook',
    options: {},
  },
  core: {
    builder: '@storybook/builder-vite',
  },
});
```

框架预设在故事本配置还没有时会添加Aurelia Vite插件. 也使Aurelia的运行时包脱离了Vite依赖性预捆绑,因此渲染器和组件使用一个运行时实例.

Webpack 用不同的构建器使用相同的文件 :

```ts
core: {
  builder: '@storybook/builder-webpack5',
},
```

预设添加 `ts-loader` 财务报告和审定财务报表 `@aurelia/webpack-loader` 规则一次,保留任何已经在配置中的规则.

用于 Rsbuilding,使用:

```ts
core: {
  builder: 'storybook-builder-rsbuild',
},
```

Rsbuild预设增加了相匹配的Aurelia Rspack规则.

 `.storybook/preview.ts` 包含工程设置和附加类型 :

```ts
import { definePreview } from '@aurelia/storybook';
import addonA11y from '@storybook/addon-a11y';
import addonDocs from '@storybook/addon-docs';

export default definePreview({
  addons: [addonA11y(), addonDocs()],
  tags: ['autodocs'],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
});
```

不导出 `render` 或者说 `renderToCanvas` 从预览文件。 故事本从框架预设中加载它们.

上面的工厂表可以输入故事本 `preview.meta` 财务报告和审定财务报表 `meta.story` APIs (英语). 使用正则对象 `satisfies Preview` 继续支助CSF 3项目.

添加常用脚本 :

```json
{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  }
}
```

## 写故事

故事书的CSF 工厂 API 推断 Aurelia 组件实例、附加参数、装饰器和故事参数:

```ts
import preview from '../../.storybook/preview';
import { expect, fn, userEvent } from 'storybook/test';
import { HelloWorld } from '../hello-world';

const meta = preview.meta({
  title: 'Example/HelloWorld',
  component: HelloWorld,
  args: {
    message: 'Hello from Storybook',
    onIncrement: fn(),
  },
});

export const Default = meta.story({
  play: async ({ args, canvas }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Increment' }));
    await expect(args.onIncrement).toHaveBeenCalledWith(1);
  },
});

export const Renamed = Default.extend({
  args: { message: 'Extended story' },
});
```

工厂故事也揭露了故事书的元数据, `run`, (中文(简体) ), `extend`,测试API。 当项目倾向于物品出口时,CSF 3仍然可用.

自动渲染覆盖了普通大小写 :

```ts
import type { Meta, StoryObj } from '@aurelia/storybook';
import { fn, userEvent, within } from 'storybook/test';
import { HelloWorld } from '../hello-world';

const meta = {
  title: 'Example/HelloWorld',
  component: HelloWorld,
  args: {
    message: 'Hello from Storybook',
    onIncrement: fn(),
  },
  argTypes: {
    message: { control: 'text' },
    onIncrement: { action: 'increment' },
  },
} satisfies Meta<typeof HelloWorld>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default = {} satisfies Story;

export const Interaction = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByRole('button', { name: 'Increment' }));
  },
} satisfies Story;
```

生成的 Aurelia 模板只绑定了存在的参数 。 Oncentables 保存组件自身的默认值. 添加或去除可绑定的参数重挂已生成的模板;更改已存在的值更新运行中的视图模型.

### 自定义模板和计划内容

使用 `defineAureliaStory` 当组件需要具体标记、本地资源或预测内容时:

```ts
import {
  defineAureliaStory,
  type Meta,
  type StoryObj,
} from '@aurelia/storybook';
import { CardHeading } from '../card-heading';
import { ProductCard } from '../product-card';

const meta = {
  component: ProductCard,
} satisfies Meta<typeof ProductCard>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Detailed = {
  render: (args) =>
    defineAureliaStory({
      template: `
        <product-card product.bind="product">
          <card-heading>Featured</card-heading>
        </product-card>
      `,
      props: args,
      register: [ProductCard, CardHeading],
    }),
  args: {
    product: { name: 'Desk lamp' },
  },
} satisfies Story;
```

故事结果可以包含:

| 外地 | 目的 |
| --- | --- |
| `template` | 故事的奥雷莉亚标记 |
| `Component` | 此故事的组件覆盖 |
| `props` | 在故事书参数后合并的值 |
| `innerHtml` | 自动生成组件元素的预计加价 |
| `register` 或者说 `components` | 自定义元素、属性、数值转换器、插件和其他注册 |
| `items` | DI 登记和服务 |
| `container` | 现有的 Aurelia 容器 |

渲染函数也可能直接返回模板字符串或Aurelia自定义元素类.

### Aurelia 配置

为预览、组件组或单个故事注册资源 `parameters.aurelia`数字 :

```ts
import { Registration } from 'aurelia';
import type { Preview } from '@aurelia/storybook';
import { FeatureFlags } from '../src/feature-flags';
import { MoneyValueConverter } from '../src/money-value-converter';

const preview = {
  parameters: {
    aurelia: {
      register: [MoneyValueConverter],
      configureContainer: (container) => {
        container.register(
          Registration.instance(FeatureFlags, { newCheckout: true })
        );
      },
      configure: (aurelia, context) => {
        // Configure the app before it starts.
      },
    },
  },
} satisfies Preview;

export default preview;
```

全包设置, 使用 `setup` 从 `.storybook/preview.ts`数字 :

```ts
import { setup } from '@aurelia/storybook';

setup(async (aurelia, context) => {
  // Runs for every newly mounted story app.
});
```

`setup` 返回未注册函数,该函数在测试环境中有用.

### 从播放函数挂起

结构 `mount` 当播放函数控制初始渲染时 :

```ts
import { expect } from 'storybook/test';

export const MountedByPlay = {
  play: async ({ mount }) => {
    const canvas = await mount({
      Component: HelloWorld,
      props: { message: 'Mounted from play' },
    });

    await expect(canvas.getByText('Mounted from play')).toBeVisible();
  },
};
```

故事书检测到已解结构的参数,并在运行故事后检查前等待这个挂载.

## 文档和MDX

添加 `@storybook/addon-docs` 以启用 autodocs 和 MDX。 Aurelia 可绑定物出现在 `bindables` 类别,和动态源块显示故事使用的 Aurelia 标记。 设定 `parameters.docs.source.code` 当一个故事需要一个手写源的例子时.

常规故事书 MDX 工作没有奥雷利亚特有的包装:

```mdx
import { Meta, Canvas } from '@storybook/addon-docs/blocks';
import * as Stories from './hello-world.stories';

<Meta of={Stories} />

# Hello World

<Canvas of={Stories.Default} />
```

## Vest 浏览器测试

故事书"Vitest"的"addon"可以在Chrimium运行同样的故事. 扩展该应用程序的 Vite 配置, 以便测试项目得到一个完全的 Aurelia 插件实例 :

```ts
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
import { playwright } from '@vitest/browser-playwright';
import { defineConfig } from 'vitest/config';

const dirname = path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  test: {
    projects: [
      {
        extends: './vite.config.ts',
        plugins: [
          storybookTest({ configDir: path.join(dirname, '.storybook') }),
        ],
        test: {
          name: 'storybook',
          browser: {
            enabled: true,
            headless: true,
            provider: playwright({}),
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
});
```

不添加另一个 `aurelia()` 当扩展的 Vite 配置已经拥有时, 请调用此工程 。 将奥雷利亚公约模板两次将第一个生成的模块变为模板文本.

Vite 8 和工厂预览, 预装该预览导入的附加入口 。 这使得Vite无法在发现浏览器时重新加载首个浏览器测试运行:

```ts
optimizeDeps: {
  include: [
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
    '@storybook/addon-vitest',
    'storybook/internal/csf',
  ],
},
```

## 便携式故事

该套件输出Aurelia-aware可移植-故事帮助:

```ts
import { composeStories } from '@aurelia/storybook/portable-stories';
import * as stories from './hello-world.stories';

const { Default } = composeStories(stories);

await Default.run();
```

何时 `.storybook/preview.ts` 导出一个 CSF 3 配置对象, 使用 `setProjectAnnotations` 一次在一个测试设置文件中,如此可移植的故事收到:

```ts
import { setProjectAnnotations } from '@aurelia/storybook/portable-stories';
import preview from '../.storybook/preview';

setProjectAnnotations(preview);
```

国别服务框架 工厂故事已经带有预览说明. 导入一个并拨打 `await Story.run()` 直接代替再编组.

## 发展

这个寄存器是一个npm工作空间,包含框架和Vite,Webpack,和Rsbuild等实例.

```bash
npm ci
npm run sync:versions:check
npm run lint
npm run typecheck
npm test
npm run build
npm run lint:examples
npm run typecheck:examples
npm run test:examples
npm run build:examples
npm run build:storybooks
npm run test:storybook
```

`npm run test:storybook` 需要一个铬二进制。 安装它 `npx playwright install chromium` 如果Playwright还没有这样做.

## 许可证

麻省理工学院

## 常见问题

### @aurelia/storybook 是什么？

使用 Vite 、 Webpack 或 Rsbuild/ Rspack 渲染 Aurelia 2 组件的故事书插件

### 如何安装 @aurelia/storybook？

在项目目录运行 npm install @aurelia/storybook，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：aurelia（^2\.0\.0-rc\.2）、storybook（^10\.5\.6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aurelia/storybook 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aurelia/storybook 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aurelia/storybook 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aurelia/storybook 可以商用吗？

@aurelia/storybook 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aurelia/storybook 的下载量有多少？

根据 npm 官方下载统计，@aurelia/storybook 在 2026/10/07 – 2026/11/05 这 30 天内被下载 5,132 次，日均约 171 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aurelia/storybook 还在维护吗？

最新版本 3\.0\.0 发布于 2026/08/06（3 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/02/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。