@rspress/plugin-preview#

用于预览 md(x) 文件代码块中的组件。

安装#

npm add @rspress/plugin-preview -D

使用#

引入插件#

首先在配置文件中写入以下的配置：

import { defineConfig } from 'rspress/config';
import { pluginPreview } from '@rspress/plugin-preview';

export default defineConfig({
  plugins: [pluginPreview()],
});

内部组件#

内部组件的组件代码声明在 mdx 文件内。你可以在 mdx 文件中声明如下的代码块：

```tsx
function App() {
  return Hello World;
}

export default App;
```

值得注意的是，你需要将组件作为 default 导出，Rspress 会自动渲染这个组件。

但是如果你想保留代码块的样式，而不是将其作为组件渲染，你可以添加 pure 标识符来指定，使用方式如下：

```tsx pure
function App() {
  return Hello World;
}
export default App;
```

如果你配置了 defaultRenderMode 为 'pure'，那么默认情况下，Rspress 将不会渲染这个组件，而是将其作为代码块来渲染。这种情况下，如果需要将某个代码块渲染为组件，可以通过添加 preview 标识符来指定，使用方式如下：

```tsx preview
function App() {
  return Hello World;
}
export default App;
```

外部组件#

除了将组件代码写在 mdx 文件的代码块中，你还可以将组件代码写在外部文件中，然后在 mdx 文件中通过 code 标签引入。比如

<code src="./Demo.tsx" />

export default function App() {
  return <div>Hello World</div>;
}

外部组件中同样需要将组件作为 default 导出。而通过 code 标签的 src 属性，你可以指定外部组件的路径，该插件同时支持相对路径以及别名路径(alias)。

对于某些比较复杂的组件，这种外部组件的使用方式会更加方便。

配置#

这个插件接受一个对象参数，类型如下:

interface PreviewOptions {
  previewMode?: 'internal' | 'iframe';
  iframeOptions?: IframeOptions;
  defaultRenderMode?: 'pure' | 'preview';
}

interface IframeOptions {
  framework?: 'react' | 'solid';
  position?: 'fixed' | 'follow';
  devPort?: number;
}

defaultRenderMode#

支持用户配置没有主动声明 pure 或 preview 标识符的内部代码块的默认行为，默认为 preview。

• pure: 渲染为普通代码块
• preview: 渲染为预览组件

previewMode#

previewMode 参数用于指定预览组件是否内置，默认为 internal。默认内置模式的展示效果如下：

你也可以针对单个代码块设置，例如

<code src="./Demo.tsx" previewMode="iframe"/>

```tsx iframe
function App() {
  return Hello World;
}
export default App;
```

如果使用 iframe 预览模式，还有以下配置：

iframeOptions.position#

在 iframe 预览模式下时，你可以通过 position 参数来决定预览区 iframe 的位置，是跟随页面滚动(follow 模式)还是固定在页面中(fixed 模式)，默认为 follow。

follow 模式效果如下：

fixed 模式效果如下：

iframeOptions.framework#

在 iframe 预览模式下，你可以选择渲染框架，目前支持 react 和 solid。

iframeOptions.devPort#

在 iframe 预览模式下，你可以配置预览组件的 dev server port。

iframeOptions.builderConfig#

配置 iframe 的构建配置，例如添加一些全局代码逻辑。

deprecated: isMobile#

从 1.12.0 版本开始，请使用 previewMode 配置预览模式。

deprecated: iframePosition#

从 1.12.0 版本开始，请使用 iframeOptions.position。

previewLanguages#

• Type: string[]
• Default: ['jsx', 'tsx']

支持预览的代码语言，默认支持 jsx 和 tsx 代码。如果你需要支持其它格式的代码，如 json/yaml, 可以配合下面的 previewCodeTransform 配置一起使用。

previewCodeTransform#

• Type: (codeInfo: { language: string; code: string }) => string
• default: ({ code }) => code

预览前对代码进行自定义的转换。以 JSON 代码为例，如果你想要通过自定义的转换逻辑渲染一段 JSON Schema：

{
  "type": "div",
  "children": "Render from JSON"
}

可以做如下配置：

pluginPreview({
  // 注意添加默认的 jsx 和 tsx
  previewLanguages: ['jsx', 'tsx', 'json'],
  previewCodeTransform(codeInfo) {
    if (codeInfo.language === 'json') {
      return `
import React from 'react';

const json = ${codeInfo.code};

export default function() {
return React.createElement(json.type, null, json.children);
}
`;
    } else {
      return codeInfo.code;
    }
  },
});

这样，最后会渲染出自定义逻辑转换后的组件代码。