> 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-playground 

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

Обеспечивает интерактивную редактируемую площадку для предпросмотра компонентов в блоках MDX-кода.

:::tip
Используйте этот плагин совместно с [@rspress/plugin-preview](/rspress-russian/plugin/official-plugins/preview.md). В отличие от `plugin-preview`, `plugin-playground` компилирует код в браузере, поэтому имеет больше ограничений. Например, он не может импортировать модули из локальных файлов. Используйте `plugin-playground` как дополнение к `plugin-preview`, когда требуется редактирование кода в реальном времени.
:::

## Установка


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

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

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

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

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

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

### 1. Регистрация плагина

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

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

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

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

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

````mdx title="example.mdx"
```tsx playground
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 playground
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. Проверка типов для TSX сейчас не выполняется.

:::

### 3. Написание кода компонента в других файлах (опционально)

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

````mdx title="example.mdx"
```tsx file="./_playgroundDemo.jsx" playground

```
````

```tsx title="_playgroundDemo.jsx" file="./_playgroundDemo.jsx"
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="./_playgroundDemo.jsx" playground
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;
```

## Настройка направления макета \{#direction}

Вы можете использовать параметр `direction` для указания направления макета редактора и области предварительного просмотра. Поддерживаются `horizontal` или `vertical`.

### `direction="horizontal"`

Горизонтальный макет является режимом по умолчанию, при котором редактор и область предварительного просмотра располагаются бок о бок.

Синтаксис:

````mdx title="example.mdx"
```tsx playground direction=horizontal

```
````

### `direction="vertical"`

Вертикальный режим макета, при котором редактор и область предварительного просмотра располагаются друг над другом сверху вниз.

Синтаксис:

````mdx title="example.mdx"
```tsx playground direction=vertical

```
````

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

```tsx playground direction=vertical
import { useState } from 'react';

function App() {
  const [text, setText] = useState('Привет');

  return (
    <div>
      <input value={text} onChange={e => setText(e.target.value)} />
      <p>Вы ввели: {text}</p>
    </div>
  );
}

export default App;
```

### Определение макета всей страницы

Вы можете указать `playgroundDirection` в метаданных для определения макета редактора и области предварительного просмотра для всей страницы.

```md title="example.mdx"
---
title: Заголовок
playgroundDirection: vertical
---
```

Приоритет: Определение непосредственно в блоке кода > Определение в метаданных страницы > Конфигурация плагина.

## Опции

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

```ts
interface PlaygroundOptions {
  defaultRenderMode?: 'pure' | 'playground';
  defaultDirection?: 'horizontal' | 'vertical';
  editorPosition?: 'left' | 'right';
  babelUrl?: string;
  monacoLoader?: Parameters<typeof loader.config>[0];
  monacoOptions?: MonacoEditorProps['options'];
  include?: Array<string | [string, string]>;
  render?: string;
}
```

### defaultRenderMode

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

Настраивает поведение рендеринга по умолчанию для блоков кода, которые явно не объявляют `pure` или `playground`.

- ` ```tsx pure`: Отображается как обычный блок кода
- ` ```tsx `: Отображается в соответствии с конфигурацией `defaultRenderMode`
- ` ```tsx playground`: Отображается как редактируемый компонент песочницы

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

### defaultDirection

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

Настраивает направление макета [по умолчанию](#direction) редактора и области предварительного просмотра.

### editorPosition

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

Настраивает положение редактора в горизонтальном макете (слева/справа).

### babelUrl

- **Тип:** `string`
- **По умолчанию:** `'https://cdnjs.cloudflare.com/ajax/libs/babel-standalone/7.22.20/babel.min.js'`

Песочница использует `@babel/standalone` для компиляции демонстрационного кода. Вы можете изменить его на URL, предоставленный другими CDN, такими как unpkg, jsdelivr и т. д.

### monacoLoader

Настраивает поведение загрузчика monaco. По умолчанию загружается с [cdnjs.com](https://cdnjs.com/libraries/monaco-editor).

Вы можете изменить его на URL, предоставленный другими CDN, такими как unpkg, jsdelivr и т.д.

Полная документация доступна на [suren-atoyan/monaco-loader](https://github.com/suren-atoyan/monaco-loader#config).

### monacoOptions

- **Тип:** [IStandaloneEditorConstructionOptions](https://microsoft.github.io/monaco-editor/typedoc/interfaces/editor_editor_api.editor.IStandaloneEditorConstructionOptions.html)

Настраивает опции Monaco Editor.

:::warning Примечание
`monacoLoader` и `monacoOptions` будут сериализованы в JSON, поэтому некоторые типы данных, такие как функции и объекты с циклическими ссылками, не поддерживаются.
:::

### include

- **Тип:** `Array<string | [string, string]>`

По умолчанию этот плагин автоматически сканирует все операторы import в демо; пакеты, не используемые в демо, нельзя использовать в песочнице. Если вы хотите добавить другие пакеты в песочницу, вы можете использовать параметр `include`:

```ts
pluginPlayground({
  include: [
    // Добавление пакета dayjs
    'dayjs',
    // Добавление пакета с именем "my-package", фактически указывающего на "/path/to/package/index.js"
    ['my-package', '/path/to/package/index.js'],
  ],
});
```

### render

- **Тип:** `string`

Вы можете настроить файл рендеринга для отображения песочницы. Обратите внимание, что имя файла должно быть `Playground.(jsx?|tsx?)`.

```ts
pluginPlayground({
  render: '/path/to/render/Playground.tsx',
});
```

В пользовательской песочнице вы можете напрямую импортировать оригинальный редактор и рендерер, а также импортировать предварительно упакованные зависимости через `_rspress_playground_imports`:

```ts
import getImport from '_rspress_playground_imports';
import { Runner, Editor } from '@rspress/plugin-playground/web';
```

Для настройки вы можете обратиться к встроенному компоненту [Playground.tsx](https://github.com/web-infra-dev/rspress/blob/main/packages/plugin-playground/static/global-components/Playground.tsx).
