> For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt.

# @rspress/plugin-preview 

[Исходный код](https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-preview)

Предпросмотр компонентов из блоков кода в файлах MDX. Это полезно для документации библиотек компонентов.

## Установка


```sh [npm]
npm add @rspress/plugin-preview -D
```

```sh [yarn]
yarn add @rspress/plugin-preview -D
```

```sh [pnpm]
pnpm add @rspress/plugin-preview -D
```

```sh [bun]
bun add @rspress/plugin-preview -D
```

```sh [deno]
deno add npm:@rspress/plugin-preview -D
```

## Использование

### 1. Установка плагина

Сначала добавьте следующую конфигурацию:

```ts title="rspress.config.ts" twoslash
import { defineConfig } from '@rspress/core';
import { pluginPreview } from '@rspress/plugin-preview';

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

### 2. Использование в MDX-файлах

В MDX-файлах используйте синтаксис ` ```tsx preview `:

````mdx title="example.mdx"
```tsx preview
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;
```
````

Это отображается следующим образом:

```tsx preview
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;
```

:::tip Подсказка

1. На данный момент работает только в файлах `.mdx`.
2. Экспортируйте компонент как `default` (экспорт по умолчанию), и Rspress отрендерит его автоматически.

:::

### 3. Вынос кода компонента в отдельные файлы (не обязательно)

Вместо того чтобы писать код компонента прямо в блоке кода MDX, можно использовать его вместе с [блоком кода из файла](/rspress-russian/guide/use-mdx/code-blocks.md#file-code-block) и хранить примеры кода в отдельных файлах.

````mdx title="example.mdx"
```tsx file="./_demo.tsx" preview

```
````

```tsx title="_demo.tsx" file="./_demo.tsx"
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

```

Это отображается следующим образом:

```tsx file="./_demo.tsx" preview
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

```

## Использование режима предпросмотра iframe \{#preview-mode}

Этот плагин поддерживает несколько режимов предпросмотра. Переключаться между ними можно, изменяя мета-информацию `preview="..."`. Например, ` ```tsx preview="iframe-follow" ` переключает в режим [iframe-follow](#previewiframe-follow).

` ```tsx preview` эквивалентно ` ```tsx preview="{defaultPreviewMode}"`, значение определяется параметром [defaultPreviewMode](#defaultpreviewmode).

:::tip Подсказка

Режим предпросмотра iframe имеет отдельные среды компиляции и выполнения.

1. Отдельное окружение сборки: пример кода в блоке кода компилируется как точка входа отдельным экземпляром Rsbuild, что позволяет внедрять переменные Sass/Less и другую конфигурацию.

2. Отдельное окружение выполнения: исключаются конфликты стилей с сайтом документации, а библиотека компонентов может загружать собственный `base.css`.

:::

### `preview="internal"`

`"internal"` — режим предпросмотра по умолчанию, при котором компонент рендерится непосредственно внутри документа.

Синтаксис:

````mdx title="example.mdx"
```tsx file="./_demo.tsx" preview

```
````

или

````mdx title="example.mdx"
```tsx file="./_demo.tsx" preview="internal"

```
````

Отобразится так:

```tsx file="./_demo.tsx" preview="internal"
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

```

### `preview="iframe-follow"`

Этот режим отображает область предпросмотра iframe справа от блока кода, следуя потоку содержимого. На широких экранах перетащите разделитель между кодом и предпросмотром, чтобы изменить размер области предпросмотра (двойной щелчок сбрасывает его).

Синтаксис:

````mdx title="example.mdx"
```tsx file="./_demo.tsx" preview="iframe-follow"

```
````

Отобразится так:

```tsx file="./_demo.tsx" preview="iframe-follow"
import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ textAlign: 'center' }}>
      <p>Счётчик: {count}</p>
      <button onClick={() => setCount(count + 1)}>+</button>
      <button onClick={() => setCount(count - 1)}>-</button>
    </div>
  );
}

export default App;

```

### `preview="iframe-fixed"`

Этот режим отображает фиксированную область предпросмотра iframe справа на странице, идеально подходит для документации мобильных библиотек компонентов.

Синтаксис:

````mdx title="example.mdx"
```tsx file="./_demo.tsx" preview="iframe-fixed"

```
````

Отобразится так:

![](https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/rspress/demo-preview-mobile-fixed.png)

:::tip Советы по preEntry

Вы можете внедрить глобальные скрипты или стили в окружение предварительного просмотра iframe, используя `iframeOptions.builderConfig.source.preEntry`. Вот несколько распространённых случаев использования:

- **Эмуляция сенсорных событий для мобильных устройств**: Эмулируйте мобильные сенсорные события на ПК, импортировав [@vant/touch-emulator](https://www.npmjs.com/package/@vant/touch-emulator).

- **Обработка тёмного режима**: Внедрите `MutationObserver` для отслеживания изменений класса `html.dark`, затем синхронизируйте с `body.dark` или выполните другую обработку тёмного режима.

- **Использование Tailwind CSS**: Поскольку среда предпросмотра в iframe — это отдельный экземпляр Rsbuild, если ваши компоненты, отображаемые в предпросмотре, зависят от Tailwind CSS v4, настройте `@rsbuild/plugin-tailwindcss` в `iframeOptions.builderConfig.plugins` и внедрите вашу точку входа Tailwind CSS через `preEntry`.

```ts title="rspress.config.ts"
import { pluginTailwindcss } from '@rsbuild/plugin-tailwindcss';

pluginPreview({
  iframeOptions: {
    builderConfig: {
      plugins: [pluginTailwindcss()],
      source: {
        preEntry: [
          '@vant/touch-emulator',
          './src/dark-mode-observer.js',
          './tailwind.css',
        ],
      },
    },
  },
});
```

:::

## Интернационализация

Этот плагин использует [API плагинов `i18nSource`](/rspress-russian/plugin/system/plugin-api.md#i18nsource), чтобы добавить следующие переводы:


Источник переводов

```ts title="i18n.ts" file="<root>/node_modules/@rspress/plugin-preview/static/i18n.ts"
// cspell:disable
export const previewI18n = {
  previewRefresh: {
    en: 'Refresh',
    zh: '刷新页面',
    ja: '再読み込み',
    ko: '새로고침',
    ru: 'Обновить',
    ta: 'பக்கத்தைப் புதுப்பிக்க',
  },
  previewOpen: {
    en: 'Open in new page',
    zh: '在新页面打开',
    ja: '新しいページで開く',
    ko: '새 페이지에서 열기',
    ru: 'Открыть на новой странице',
    ta: 'புதிய பக்கத்தில் பார்க்க',
  },
};

```

Вы можете переопределить эти тексты с помощью [пользовательской конфигурации `i18nSource`](/rspress-russian/api/config/config-basic.md#i18nsource).

## Опции

Этот плагин принимает объект конфигурации со следующей типизацией:

```ts
interface PreviewOptions {
  defaultRenderMode?: 'pure' | 'preview';
  defaultPreviewMode?: 'internal' | 'iframe-fixed' | 'iframe-follow';
  iframeOptions?: IframeOptions;
  previewLanguages?: string[];
  previewCodeTransform?: (codeInfo: {
    language: string;
    code: string;
  }) => string;
}

interface IframeOptions {
  devPort?: number;
  builderConfig?: RsbuildConfig;
  customEntry?: (meta: CustomEntry) => string;;
}
```

### defaultRenderMode

- **Тип:** `'pure' | 'preview'`
- **По умолчанию:** `'pure'`

Определяет поведение по умолчанию для блоков кода, в которых явно не указаны `pure` или `preview`.

:::warning Предупреждение
Не рекомендуется изменять значение по умолчанию, поскольку это может повлиять на совместное использование с `@rspress/plugin-playground`.
:::

- ` ```tsx pure` — рендерится как обычный блок кода
- ` ```tsx` — рендерится согласно настройке `defaultRenderMode`
- ` ```tsx preview` — рендерится как блок кода с предпросмотром компонента

### defaultPreviewMode

- **Тип:** `'internal' | 'iframe-follow' | 'iframe-fixed'`
- **По умолчанию:** `'internal'`

Определяет \[режим предпросмотра]]\(#preview-mode) по умолчанию для ` ```tsx preview`.

- ` ```tsx preview` — использует режим, заданный в `defaultPreviewMode`
- ` ```tsx preview="internal"` — режим internal
- ` ```tsx preview="iframe-follow"` — режим iframe-follow
- ` ```tsx preview="iframe-fixed"` — режим iframe-fixed

### iframeOptions

Для режимов iframe плагин запускает отдельный экземпляр Rsbuild (как для dev-сервера, так и для сборки), полностью изолированный от процесса компиляции документации Rspress.

#### iframeOptions.devPort

- **Тип:** `number`
- **По умолчанию:** `7890`

Настраивает порт dev-сервера для предпросмотра в iframe. Если указанный порт уже занят, плагин автоматически попробует следующий порт, до 20 попыток.

#### iframeOptions.builderConfig

Настраивает параметры сборки Rsbuild для iframe, например, добавление глобальных стилей или скриптов.

Например, чтобы добавить поддержку Less или Sass в превью, установите и настройте соответствующий плагин Rsbuild:


```sh [npm]
npm add @rsbuild/plugin-less -D
```

```sh [yarn]
yarn add @rsbuild/plugin-less -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-less -D
```

```sh [bun]
bun add @rsbuild/plugin-less -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-less -D
```

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginLess } from '@rsbuild/plugin-less';

export default defineConfig({
  plugins: [
    pluginPreview({
      iframeOptions: {
        builderConfig: {
          plugins: [pluginLess()],
        },
      },
    }),
  ],
});
```

#### iframeOptions.customEntry

Позволяет задать пользовательскую точку входа для поддержки других фреймворков, например Vue.

:::warning Внимание
Доступно только в режиме `preview="iframe-follow"`.
:::

Пример для фреймворка Vue:

```ts
import { defineConfig } from '@rspress/core';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  // ...
  plugins: [
    pluginPreview({
      previewMode: 'iframe',
      previewLanguages: ['vue'],
      iframeOptions: {
        position: 'follow',
        customEntry: ({ demoPath }) => {
          return `
          import { createApp } from 'vue';
          import App from ${JSON.stringify(demoPath)};
          createApp(App).mount('#root');
          `;
        },
        builderConfig: {
          plugins: [pluginVue()],
        },
      },
    }),
  ],
});
```

### previewLanguages

- **Тип:** `string[]`
- **По умолчанию:** `['jsx', 'tsx']`

Определяет языки кода, для которых включён предпросмотр. Чтобы добавить поддержку других форматов (например, JSON или YAML), используйте эту опцию вместе с `previewCodeTransform`.

### previewCodeTransform

- **Тип:** `(codeInfo: { language: string; code: string }) => string`
- **По умолчанию:** `({ code }) => code`

Выполняет пользовательское преобразование кода перед предпросмотром.

В примере ниже показано, как превратить JSON Schema в рендерящийся React-компонент:

```json
{
  "type": "div",
  "children": "Рендеринг JSON"
}
```

Настроить можно следующим образом:

```ts
pluginPreview({
  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;
    }
  },
});
```

## Миграция с V1 \{#migrating-from-v1}

При переходе с Rspress V1 функциональность плагина остаётся прежней. Изменился только синтаксис исходного кода MDX:

- `<code src="./foo.tsx"/>` → нужно заменить на [Блок кода из файла](/rspress-russian/guide/use-mdx/code-blocks.md#file-code-block): `tsx file="./foo.tsx"`
- Опция `defaultPreviewMode` заменяет прежние `iframeOptions.position` и `previewMode`
- Значение по умолчанию `defaultRenderMode` изменилось с `'preview'` на `'pure'`
- `@rsbuild/plugin-less` и `@rsbuild/plugin-sass` больше не встроены. Если вам нужна поддержка Less или Sass в превью, установите соответствующий плагин и настройте его через `iframeOptions.builderConfig`:


```sh [npm]
npm add @rsbuild/plugin-less -D
```

```sh [yarn]
yarn add @rsbuild/plugin-less -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-less -D
```

```sh [bun]
bun add @rsbuild/plugin-less -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-less -D
```

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginLess } from '@rsbuild/plugin-less';

export default defineConfig({
  plugins: [
    pluginPreview({
      iframeOptions: {
        builderConfig: {
          plugins: [pluginLess()],
        },
      },
    }),
  ],
});
```

:::tip Примеры миграции

**Пример 1**:

Раньше: требовалось объявлять и в конфиге, и в MDX-файле.

```ts
pluginPreview({
  previewMode: 'iframe',
  iframeOptions: { position: 'fixed' },
});
```

````mdx
```tsx preview

```
````

После: достаточно объявить только в MDX-файле.

````mdx
```tsx preview="iframe-fixed"

```
````

**Пример 2**:

Раньше: использовался атрибут `iframe` или `previewMode="iframe"`.

````mdx
```tsx iframe

```

{/* or */}

<code src="./_demo.tsx" previewMode="iframe" />
````

После: используется единый атрибут `preview="..."`.

````mdx
```tsx preview="iframe-follow"

```

```tsx file="./_demo.tsx" preview="iframe-follow"

```
````

:::
