Настройка
EditorConfig и RendererConfig: точки входа для любой настройки. Передайте один из них в Editor.create() или Renderer.render() соответственно. Обязательны только containerId (и data для рендерера); все остальные параметры имеют безопасные значения по умолчанию.
EditorConfig
Передайте EditorConfig как единственный аргумент в Editor.create(). Обязательный containerId должен совпадать с id существующего элемента DOM.
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| containerId | string | Да | ID DOM-элемента, в котором будет размещён редактор. Должен существовать в DOM до вызова Editor.create(). |
| maxHeight | number | Нет | Максимальная высота редактора в пикселях. Установите 0 (по умолчанию) для снятия ограничения высоты. |
| minHeight | number | Нет | Минимальная высота редактора в пикселях. По умолчанию 300. |
| onChange | (data: EditorData) => void | Нет | Обратный вызов, срабатывающий при каждом изменении документа. Получает полный снимок EditorData. |
| onReady | () => void | Нет | Обратный вызов, срабатывающий после полной инициализации редактора и готовности принимать вызовы API. |
| placeholder | string | Нет | Замещающий текст, отображаемый когда редактор пуст. По умолчанию 'Start writing...'. |
| initialData | EditorData | Нет | Предварительно заполненный EditorData для загрузки при монтировании редактора. |
| initialView | 'edit' | 'preview' | 'json' | Нет | Начальный режим просмотра. Одно из: edit, preview, json. По умолчанию 'edit'. |
| allowJsonViewEditing | boolean | Нет | Если true, представление JSON доступно для редактирования, а изменения распространяются обратно в документ. По умолчанию false. |
| hasViewSwitcher | boolean | Нет | Если false, кнопки редактирования, предпросмотра и JSON убираются с панели действий. По умолчанию true. |
| hasDocumentActions | boolean | Нет | Если false, кнопки копирования, скачивания и очистки убираются с панели действий. Если hasViewSwitcher тоже false, панель действий не отображается. По умолчанию true. |
| onClearRequest | () => Promise<boolean> | Нет | Вызывается при нажатии «Очистить». Страница очищается, только если результат равен true; отказ оставляет страницу как есть. Если не задан, очистка происходит сразу. |
| margins | BlockMargins | Нет | Глобальные верхний и нижний отступы (в пикселях), применяемые к каждому блоку. Конфигурации на уровне блока имеют приоритет. |
| styles | EditorStyles | Нет | Объект EditorStyles для тонкой CSS-настройки интерфейса редактора (панели инструментов, диалоги, элементы управления). |
| classNames | EditorClassNames | Нет | Объект EditorClassNames для прикрепления имён CSS-классов к элементам интерфейса редактора. |
| imageUploader | UploadFunction | Нет | Асинхронная функция, загружающая файл изображения и возвращающая строку с публичным URL. |
| audioUploader | UploadFunction | Нет | Асинхронная функция, загружающая аудиофайл и возвращающая строку с публичным URL. |
| videoUploader | UploadFunction | Нет | Асинхронная функция, загружающая видеофайл и возвращающая строку с публичным URL. |
| fileUploader | UploadFunction | Нет | Функция загрузки, переносящая вложения файлового блока в ваше хранилище. |
| locale | string | Нет | Единственная локаль, которую редактирует редактор. Многоязычные блоки сводятся к этой локали. |
| defaultLocale | string | Нет | Запасная локаль, если у блока нет содержимого для запрошенной локали. |
| onLocaleFallback | (info: { blockId: string; locale: string }) => void | Нет | Вызывается, когда блок откатывается к другой локали, чтобы хост показал индикатор. |
| onInlineRewrite | (selection: string, action: InlineRewriteAction) => Promise<string | null> | Нет | Функция, переписывающая выделенный текст с помощью ИИ; если задана, панель показывает кнопку переписывания. |
| inlineRewriteLabels | Partial<Record<InlineRewriteAction, string>> | Нет | Переопределяет подписи действий меню переписывания, для локализации. |
| inlineRewriteTooltip | string | Нет | Переопределяет подсказку волшебной палочки переписывания на встроенной панели инструментов, для локализации. |
| blockToolLabels | Partial<Record<BlockToolType, string>> | Нет | Переопределяет подписи блочных инструментов в панели и слэш-меню, для локализации. |
| blockToolbarLabels | Partial<Record<BlockToolbarLabel, string>> | Нет | Переопределяет тексты панели блока (добавить, переместить, удалить и прочие) и подсказки в пустых полях блоков, для локализации. |
| controlLabels | Partial<Record<ControlLabel, string>> | Нет | Переопределяет названия кнопок панели действий (редактировать, предпросмотр, JSON, копировать, скачать, очистить), которые служат их доступными именами и подсказками, для локализации. |
| dialogLabels | Partial<Record<DialogLabel, string>> | Нет | Слова диалогов ссылки, подсказки и статуса по именам: заголовки, подписи полей, подсказки в полях, стили статуса, «Отмена» и «Применить». Если не заданы, на английском. |
| resolveLink | (url: string) => Promise<Partial<EmbedData>> | Нет | Заполняет снимок вставленного встраивания с вашего сервера: заголовок, файл Drive, файлы gist или причина, по которой живой просмотр невозможен. Запрос, завершившийся ошибкой, рисует карточку как «инструмент не ответил» с кнопкой Повторить рядом. |
| onEmbedAction | (action: EmbedAction, blockId: string) => void | Нет | Действие рядом с причиной на карточке, которое может выполнить только хост: connectGoogle отправляет участника подключить аккаунт Google; retry редактор обрабатывает сам. |
| disabledEmbedProviders | readonly string[] | Нет | Отключённые рабочим пространством инструменты встраивания по ключу (figma, miro, loom, google_drive, github_gist); их ссылки рисуются карточками с указанием причины. |
| pasteEmbeds | 'live' | 'offer' | 'card' | Нет | Что делает вставка поддерживаемой ссылки: показать вживую (по умолчанию), предложить это или показать карточку. |
| embedLabels | Partial<Record<EmbedLabel, string>> | Нет | Переведённые слова для строк причин, действий и подписей gist блока встраивания, по ключу EmbedLabel; иначе английский. |
| resolveIssues | (urls: string[]) => Promise<Record<string, IssueSnapshot>> | Нет | Отвечает на ссылки задач страницы их снимками по ключу URL. Если не задано, чипы и карточки хранят то, что сохранил документ, и ничего не обновляется. |
| onIssueAction | (action: IssueAction, tool: string) => void | Нет | Исправление рядом с причиной задачи, которое может выполнить только хост: подключить инструмент, что ведёт на страницу интеграций хоста. |
| issueCards | 'off' | 'on' | Нет | Становится ли ссылка задачи, вставленная на отдельной строке, карточкой; off, если не задано. Чип во фразе всегда остаётся чипом. |
| issueChip | { assignee: boolean; status: boolean } | Нет | Два переключателя чипа участника: индикатор статуса и исполнитель. Оба включены, если не задано. |
| issueLabels | Partial<Record<IssueLabel, string>> | Нет | Переведённые слова для чипа задачи, карточки и таблицы связанных задач, по ключу IssueLabel; иначе английский. |
| jiraSites | readonly string[] | Нет | URL сайтов Jira, доступных подключениям рабочего пространства, чтобы ссылка на собственном домене сайта распознавалась как задача. |
| allowedBlockTools | readonly BlockToolType[] | Нет | Типы блоков, которые редактор предлагает в меню блоков, его поиске, меню преобразования и при вставке. Без указания все зарегистрированные блоки; сохранённый блок вне списка по-прежнему отображается. |
| allowedInlineTools | readonly InlineToolType[] | Нет | Пометки, которые предлагает встроенная панель инструментов. Без указания все зарегистрированные пометки. |
| theme | 'auto' | 'light' | 'dark' | Нет | Цветовая схема. Одно из: auto (следует системе), light, dark. По умолчанию auto. |
| themeOverrides | { light?: ThemeTokens; dark?: ThemeTokens } | Нет | Переопределения токенов по режиму. Предоставьте карты токенов light и/или dark для настройки цветов без замены всей темы. |
TypeScript
import { Editor } from '@clepit/core';
const editor = Editor.create({
containerId: 'editor',
minHeight: 400,
placeholder: 'Start writing...',
theme: 'auto',
onChange: data => console.log(data),
onReady: () => console.log('Editor ready'),
imageUploader: async file => {
const form = new FormData();
form.append('file', file);
const res = await fetch('/api/upload', { body: form, method: 'POST' });
const { url } = await res.json();
return url;
},
});RendererConfig
Передайте RendererConfig как единственный аргумент в Renderer.render(). Требуются оба: containerId и data.
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| containerId | string | Да | ID DOM-элемента, в который будет инжектирован отрендеренный вывод. |
| data | EditorData | Да | Документ EditorData для рендеринга. Обязателен. |
| margins | BlockMargins | Нет | Глобальные верхний и нижний отступы (в пикселях), применяемые к каждому отрендеренному блоку. |
| styles | BlockStyles | Нет | Карта BlockStyles для CSS-настройки по типам блоков в отрендеренном выводе. |
| classNames | BlockClassNames | Нет | Карта BlockClassNames для имён CSS-классов по типам блоков в отрендеренном выводе. |
| editorClassNames | EditorClassNames | Нет | EditorClassNames, передаваемые блокам, отрисовывающим интерактивные компоненты (например, classNames подсказок для абзацев). |
| configs | Partial<BlockTypeOutputConfigs> | Нет | Частичная карта объектов OutputConfig для каждого блока. Каждая запись может задавать отступы на уровне блока и имена классов подсказок. |
| theme | 'auto' | 'light' | 'dark' | Нет | Цветовая схема. Одно из: auto, light, dark. |
| themeOverrides | { light?: ThemeTokens; dark?: ThemeTokens } | Нет | Переопределения токенов по режиму для отрендеренного вывода. |
TypeScript
import { Renderer } from '@clepit/core';
import type { EditorData } from '@clepit/core';
const data: EditorData = await fetch('/api/content/123').then(r => r.json());
Renderer.render({
containerId: 'output',
data,
theme: 'auto',
margins: { bottom: 16, top: 16 },
});Стилизация на уровне блока
И EditorConfig, и RendererConfig принимают styles, classNames и configs с ключом по типу блока. Используйте их для целевых переопределений; полную справку по токенам смотрите на странице Themes.
TypeScript
import { Editor, Renderer } from '@clepit/core';
import type { BlockStyles, BlockClassNames, EditorStyles } from '@clepit/core';
const editorStyles: EditorStyles = {
blockToolbar: { container: { borderRadius: '8px' } },
};
const blockStyles: BlockStyles = {
header: { h1: { fontFamily: 'Georgia, serif' } },
paragraph: { lineHeight: '1.75' },
table: { cell: { padding: '8px 12px' } },
};
const blockClassNames: BlockClassNames = {
paragraph: 'prose-paragraph',
header: { h1: 'prose-h1', h2: 'prose-h2' },
alert: { info: 'alert-info', error: 'alert-error' },
};
Editor.create({
containerId: 'editor',
styles: editorStyles,
});
Renderer.render({
containerId: 'output',
data,
styles: blockStyles,
classNames: blockClassNames,
});