storybook-addon-mantine

无需重启 Storybook 即可在多个 Mantine 主题之间切换，并使用每个主题可视化你的组件/页面。

如何使用

安装插件

npm i -D storybook-addon-mantine

注册插件

在你的项目 .storybook/main.ts 文件中执行此操作

// .storybook/main.ts
import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  // ... other config properties
  addons: [
    // ... other addons
    "storybook-addon-mantine",
  ],
};

export default config;

主题

// src/themes.ts
import { createTheme } from "@mantine/core";

export const greenTheme = createTheme({
  primaryColor: "green",
  // ... other theme override properties
});

export const brandTheme = createTheme({
  fontFamily: "serif",
  // ... other theme override properties
});

将你的主题传递给插件

在你的 .storybook/preview.tsx 文件中执行此操作

import "@mantine/core/styles.css";

import { withMantineThemes } from "storybook-addon-mantine";
import { greenTheme, brandTheme } from "../themes";

export const decorators = [
  withMantineThemes({
    themes: [
      {
        id: "brand-theme",
        name: "Brand Theme",
        ...brandTheme,
      },
      {
        id: "light-green",
        name: "Light Green Theme",
        ...greenTheme,
      },
    ],
  }),
];

选项

withMantineThemes({themes, mantineProviderProps})

在 .storybook/preview.js 文件中的 decorators 数组内调用此函数。

themes

要在 Storybook 中显示的主题列表。每个主题都应该是有效的 Mantine 主题覆盖对象。

此外，每个主题对象都必须包含

• id: string - 必需，在主题之间必须唯一
• name?: string - 可选，用于在列表中选择主题时显示的名称。

mantineProviderProps

这是一个可选的属性对象，用于传递给 MantineProvider 组件。
详情请参阅文档页面。

大多数使用场景无需为此对象设置任何内容。

颜色方案 (深色/浅色模式) 支持

在 Storybook v7 的插件中无法使用 Mantine 钩子。需要将 Storybook 管理器 UI 升级到 React 18（这样插件就可以使用 React 的 useId 钩子）。这似乎已计划在 Storybook 8 版本中实现。

变通方法是在你的 Storybook 实例中配置 Mantine 的 useMantineColorScheme 钩子，请参阅Mantine 文档了解所有步骤。

安装 Storybook 插件

npm install -D storybook-dark-mode @storybook/addon-styling storybook-addon-mantine

将插件添加到 .storybook/main.ts

import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  // ... other config properties
  addons: [
    // ... other addons
    "@storybook/addon-styling",
    "storybook-dark-mode",
    "storybook-addon-mantine",
  ],
};

export default config;

按之前说明创建你的主题。

// Import styles of packages that you've installed.
// All packages except `@mantine/hooks` require styles imports
import "@mantine/core/styles.css";

import React, { useEffect } from "react";
import { addons } from "@storybook/preview-api";
import { DARK_MODE_EVENT_NAME } from "storybook-dark-mode";
import { MantineProvider, useMantineColorScheme } from "@mantine/core";
import { withMantineThemes } from "storybook-addon-mantine";
import { greenTheme, brandTheme } from "../themes";

const channel = addons.getChannel();

function ColorSchemeWrapper({ children }: { children: React.ReactNode }) {
  const { setColorScheme } = useMantineColorScheme();
  const handleColorScheme = (value: boolean) =>
    setColorScheme(value ? "dark" : "light");

  useEffect(() => {
    channel.on(DARK_MODE_EVENT_NAME, handleColorScheme);
    return () => channel.off(DARK_MODE_EVENT_NAME, handleColorScheme);
  }, [channel]);

  return <>{children}</>;
}

export const decorators = [
  (renderStory: any) => (
    <ColorSchemeWrapper>{renderStory()}</ColorSchemeWrapper>
  ),
  withMantineThemes({
    themes: [
      {
        id: "brand-theme",
        name: "Brand Theme",
        ...brandTheme,
      },
      {
        id: "light-green",
        name: "Light Green Theme",
        ...greenTheme,
      },
    ],
  }),
];

就这样！

npm run storybook

版本

此表格应有助于你选择正确的 storybook-addon-mantine 版本

Storybook 版本	Mantine 版本	storybook-addon-mantine 版本
8	7	4.x
7	7	3.0.1
7	6	2.0.21
6	6	1.3
6	5	1.2
6	4	1.0

5.0

支持 React 19。

4.0

仅支持 Storybook 8 和 Mantine 7。如果使用 React 18，请使用此版本。

3.0

支持 Storybook 7。支持 Mantine v7 版本。

以下为重要说明

• 仅限 React 18+
• 颜色方案不在主题对象中
• [Create theme function](https://mantine.dev/changelog/7-0-0/#createtheme-function
• 主题对象变更

2.0

• 支持 Storybook 7 - 不兼容旧版本 Storybook。
• 使用 AddonKit 和 Typescript 重建整个包。
• 在切换组件示例时，保持选定的主题一致，而不会每次都默认回到第一个主题。

1.3

• 支持 Mantine v6 (https://mantine.dev/changelog/6-0-0/)。
• 仅需 @mantine/core 作为对等依赖

1.2

• 更新对等依赖

1.1

• 支持 Mantine v5 (https://mantine.dev/changelog/5-0-0/)。
• 为 mantineTheme(themesList, mantineProviderProps) 添加第二个参数 mantineProviderProps

1.0

初次发布