dumidumi
  • 指南
  • 配置项
  • 主题
  • 插件
⌘ K
介绍
什么是 dumi
基础
初始化
目录结构
约定式路由
页面渲染配置
写组件 demo
Markdown 增强
进阶
多语言
页面 Tab
移动端组件研发
自动 API 表格
其他
从 dumi 1.x 升级
常见问题
Open-source MIT Licensed | Copyright © 2019-present
Powered by self

写组件 demo

编写方式

dumi 提供了两种编写 demo 的方式,分别应对不同的场景。

代码块

如果我们的 demo 非常轻量,建议直接编写代码块,比如:

```jsx
import React from 'react';

export default () => <h1>Hello dumi!</h1>;
```

jsx 和 tsx 的代码块将会被 dumi 解析为 React 组件,以上代码块将会被渲染成:

import React from 'react';
export default () => <h1>Hello dumi!</h1>;

但是在 markdown 代码块中编写代码会失去类型提示和校验,不能像直接在 tsx 中那样丝滑,因此我们推荐使用 VSCode 插件 TS in Markdown。

在 demo 中引入组件

dumi 有一个非常重要的原则——开发者应该像用户一样使用组件。

如何理解?假设我们正在研发的组件库 NPM 包名叫做 hello-dumi,我们正在为其中的 Button 组件编写 demo,下面列举出引入组件的正确方式及错误示例:

// 正确示例
import { Button } from 'hello-dumi';
// 错误示例,用户不知道 Button 组件是哪里来的
import Button from './index.tsx';
import Button from '@/Button/index.tsx';

当我们的每个 demo 都秉持这一原则时,意味着我们写出的 demo,不仅可以用来调试组件、编写文档,还能被用户直接拷贝到项目中使用。

也许你会有疑问,研发阶段的组件库源代码尚未发布成 NPM 包,怎么才能成功引入组件?无需担心,dumi 会为我们自动建立组件库 NPM 包 -> 组件库源代码的映射关系。

不渲染代码块

如果我们希望某段 jsx/tsx 代码块被渲染为源代码,可以使用 pure 修饰符告诉 dumi:

```jsx | pure
// 我不会被渲染为 React 组件
```

外部 demo

如果我们的 demo 非常复杂,甚至可能有很多外部文件,那么建议使用外部 demo:

<code src="/path/to/complex-demo.tsx"></code>

和代码块 demo 一样,上述代码也会被渲染为 React 组件,并且外部 demo 的源代码及其他依赖的源代码都可以被用户查看,就像这样:

控制 demo 渲染

dumi 提供了一些 FrontMatter 属性,以满足不同的 demo 渲染需求,在源代码顶部配置即可:

```jsx
/**
 * [配置项名称]: [值]
 */
```

对于外部 demo,这些 FrontMatter 属性除了写在源代码里,也可以写在 code 标签的属性上:

<code src="/path/to/demo" 配置项="值"></code>

dumi 目前支持如下 demo 控制能力。

捕获 fixed 元素

设置 transform 为 true,可使得内部 position: fixed; 元素相对于 Demo 包裹器定位:

/**
* transform: true
*/
import React from 'react';
export default () => (
<h1 style={{ position: 'fixed', top: 0, left: 0 }}>我不会飞出去</h1>
);

修改背景色

通过 background 配置项,可以修改它的背景颜色、渐变甚至加上背景图片,dumi 会将其当做 CSS 属性值处理,比如配置 background 为 '#f6f7f9':

/**
* background: '#f6f7f9'
*/
import React from 'react';
export default () => null;

不需要内边距

配置 compact 为 true,则会移除所有内边距:

/**
* compact: true
*/
import React from 'react';
export default () => '我会贴边站';

标题与简介

通过 title 和 description 配置 demo 的标题和简介:

我是标题

我是简介,我可以用 Markdown 来编写

/**
* title: 我是标题
* description: 我是简介,我可以用 `Markdown` 来编写
*/
import React from 'react';
export default () => null;

直接嵌入文档

配置 inline 为 true 则不会展示包裹器、直接在文档里嵌入 demo:

```jsx
/**
 * inline: true
 */

import React from 'react';

export default () => <p>我会被直接嵌入</p>;
```

就像这样:

调试型 demo

设置 debug 为 true,则该 demo 仅在开发环境下展示、且会有一个特殊标记:

iframe 模式

设置 iframe 为 true,将会使用 iframe 渲染 demo,可实现和文档的完全隔离,通常用于布局型组件,此时 compact 配置默认为 true:

/**
* iframe: true
* compact: true
*/
import React from 'react';
export default () => (
<h2
style={{
boxShadow: '0 2px 15px rgba(0,0,0,0.1)',
padding: '5px 20px',
margin: 0,
}}
>
iframe 模式
</h2>
);
Demo 分栏演示

Hello dumi!

我不会飞出去

我会贴边站

我会被直接嵌入

我仅在开发环境下展示
DEV ONLY
/**
* debug: true
*/
import React from 'react';
export default () => '我仅在开发环境下展示';