加入在线会话:美东时间周四上午 11 点,Storybook 9 发布及 AMA 问答
文档
Storybook Docs

图片、字体和资源

组件通常依赖图片、视频、字体和其他资源来按用户预期渲染。在故事文件中使用这些资源有多种方式。

将资源导入到故事中

你可以通过导入(或 require)任何媒体资源来使用它们。这在我们默认的配置中是开箱即用的。但是,如果你使用的是自定义 webpack 配置,则需要添加 文件加载器 来处理所需文件。

之后,你可以在故事中使用任何资源

MyComponent.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import imageFile from './static/image.png';
 
import { MyComponent } from './MyComponent';
 
const meta = {
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
const image = {
  src: imageFile,
  alt: 'my image',
};
 
export const WithAnImage: Story = {
  render: () => <img src={image.src} alt={image.alt} />,
};

通过 Storybook 配置提供静态文件

我们建议通过 Storybook 提供静态文件,以确保你的组件始终拥有所需的资源进行加载。对于组件经常使用的资源(如标志、字体和图标),我们推荐这种技术。

配置一个(或多个)目录,Storybook 启动时将从这些目录提供资源。使用主 Storybook 配置文件(即 .storybook/main.js|ts)中的 staticDirs 配置项来指定目录

.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
};
 
export default config;

这里 ../public 是你的静态目录。现在可以在组件或故事中这样使用它。

MyComponent.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { MyComponent } from './MyComponent';
 
const meta = {
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
// Assume image.png is located in the "public" directory.
export const WithAnImage: Story = {
  render: () => <img src="/image.png" alt="my image" />,
};

你也可以传递一个用逗号分隔(无空格)的目录列表,而不是单个目录。

.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: ['../public', '../static'],
};
 
export default config;

或者甚至可以使用配置对象来定义目录

.storybook/main.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  staticDirs: [{ from: '../my-custom-assets/images', to: '/assets' }],
};
 
export default config;

从 CDN 引用资源

将文件上传到在线 CDN 并引用它们。在此示例中,我们使用了一个占位图片服务。

MyComponent.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { MyComponent } from './MyComponent';
 
const meta = {
  component: MyComponent,
} satisfies Meta<typeof MyComponent>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const WithAnImage: Story = {
  render: () => (
    <img src="https://storybook.org.cn/images/placeholders/350x150.png" alt="My CDN placeholder" />
  ),
};

绝对路径与相对路径

有时,你可能希望将 Storybook 部署到子路径中,例如 https://example.com/storybook

在这种情况下,你需要确保所有图片和媒体文件都使用相对路径。否则,浏览器将无法找到这些文件。

如果你通过导入加载静态内容,这是自动处理的,你无需进行任何操作。

假设你正在通过 Storybook 的一个静态目录提供资源。在这种情况下,你需要使用相对路径加载图片或使用 base 元素。

在故事中引用字体

配置 Storybook 从静态文件夹提供资源后,你可以在 Storybook 中引用这些资源。例如,你可以引用自定义字体并将其应用于故事。为此,在配置目录(即 .storybook)内创建一个 preview-head.html 文件,并添加一个 <link /> 标签来引用你的字体。

.storybook/preview-head.html
<!--
Pull in static files served from your Static directory or the internet
Example:
`main.js|ts` is configured with staticDirs: ['../public'] and your font is located in the `fonts`
directory inside your `public` directory
-->
<link rel="preload" href="/fonts/my-font.woff2" />
 
<!-- Or you can load custom head-tag JavaScript: -->
<script src="https://use.typekit.net/xxxyyy.js"></script>
<script>
  try {
    Typekit.load();
  } catch (e) {}
</script>