Быстрый старт

Rector — браузерный блочный редактор. Он хранит содержимое в виде версионированного документа JSON, поддерживает блочное и внутристрочное редактирование и умеет отображать тот же документ без запуска редактора. Пакет поставляется только в формате ESM и не зависит от интерфейсного фреймворка.

На этой странице собрана минимальная полноценная интеграция. Следующие разделы подробно описывают каждый параметр и каждую точку расширения.

Требования

• современный браузер с поддержкой модулей ES;
• Node.js 20 или новее для установки и сборки;
• приложение, способное импортировать CSS и пакеты ESM.

Установка

npm install @shelamkoff/rector

Обязательные рабочие зависимости устанавливаются вместе с Rector. Некоторым мультимедийным плагинам нужны дополнительные пакеты из peerDependencies, которые устанавливает использующее Rector приложение. Они перечислены на странице соответствующего плагина до первого примера.

Контейнер редактора

Rector управляет содержимым контейнера, пока существует экземпляр редактора. Передавайте сам элемент, а не строку с CSS-селектором.

<div id="editor"></div>

#editor {
  max-width: 760px;
  margin-inline: auto;
}

Создание редактора

Зарегистрируйте все типы блоков, которые могут встретиться в документе. Режим injectStyles: true, включённый по умолчанию, автоматически загружает стили редактора, плагинов и их зависимостей.

import { createEditor } from '@shelamkoff/rector'
import { Paragraph } from '@shelamkoff/rector/plugins/paragraph'
import { Heading } from '@shelamkoff/rector/plugins/heading'

const holder = document.querySelector('#editor')

const editor = createEditor({
  holder,
  plugins: [new Paragraph(), new Heading()],
  data: {
    version: '1.0.0',
    blocks: [
      {
        id: 'intro',
        type: 'heading',
        data: { text: 'Структурированный документ', level: 2 },
      },
      {
        id: 'body',
        type: 'paragraph',
        data: { text: 'Начните редактировать этот текст.' },
      },
    ],
  },
  onChange(document) {
    console.log(document)
  },
})

Для Vite, Nuxt или другого сборщика с поддержкой CSS укажите injectStyles: false и импортируйте базовый CSS вместе с subpath выбранных плагинов либо единую точку @shelamkoff/rector/styles.css. Оба варианта описаны в руководстве по стилям.

createEditor() синхронно возвращает дескриптор редактора. К этому моменту editor.isReady равен true. Обработчик onReady нужен, если об окончании инициализации следует уведомить другую часть приложения.

Сохранение

В прикладном коде используйте save(). Метод синхронно возвращает отделённый объект документа, принадлежащий вызывающей стороне. Ошибка сериализации блока или строгой проверки выбрасывается сразу.

const documentData = editor.save()
const json = JSON.stringify(documentData)

Rector не отправляет содержимое на сервер и не выбирает способ хранения сверх описанного контракта JSON. Сохраняйте documentData в собственной подсистеме хранения.

Загрузка другого документа

render() заменяет текущий документ редактора после проверки и нормализации переданного объекта.

editor.render({
  version: '1.0.0',
  blocks: [
    { id: 'loaded', type: 'paragraph', data: { text: 'Загруженное содержимое' } },
  ],
})

Для каждого значения type во входном документе должен быть зарегистрирован плагин. Поведение при ошибочных данных блока определяется режимом проверки; он описан в разделе Конфигурация.

Освобождение ресурсов

Вызовите destroy() до удаления контейнера или представления, в котором он находится. Rector удалит свои обработчики, наблюдатели, всплывающие элементы, экземпляры плагинов и принадлежащие этому редактору подключённые стили плагинов.

editor.destroy()

Повторный вызов destroy() безопасен. После уничтожения свойство isReady остаётся доступным и возвращает false; обращение к любому другому свойству или методу завершится ошибкой, поэтому неправильное использование уже уничтоженного экземпляра не останется незаметным.

Что читать дальше

1. Архитектура объясняет границы документа, редактора, плагинов и рендерера.
2. В разделе Конфигурация перечислены все параметры.
3. Перед расширением поведения текста прочитайте Внутристрочные инструменты и плагины.
4. Перед созданием интерактивных плагинов изучите Команды и историю.
5. Для интеграции с приложением используйте API редактора.
6. При выборе возможностей документа откройте каталог блочных плагинов.