Когда в Sports.ru понадобился свой WYSIWYG-редактор, мы решили сделать его на основе библиотеки ProseMirror. Одной из ключевых особенностей этого инструмента является модульность и широкие возможности кастомизации, поэтому с его помощью можно очень тонко подогнать редактор под любой проект. В частности, ProseMirror уже используют в The New York Times и The Guardian. В этой статье мы расскажем о том, как с помощью ProseMirror написать свой WYSIWYG-редактор.
Обзор ProseMirror
Автор ProseMirror – Marijn Haverbeke, который известен в сообществе фронтенд-разработчиков в первую очередь как автор популярной книги Eloquent Javascript. На момент начала нашей работы (осень 2018 года), никаких материалов по работе с этой библиотеке не было, кроме официальной документации и туториалов от автора. В пакет документации от автора входят несколько разделов, самые полезные из них — это ProseMirror Guide (описание базовых концепций) и Reference Manual (спека библиотеки). Ниже будет пересказ ключевых идей из ProseMirror Guide.
ProseMirror всегда хранит состояние документа в своей собственной структуре данных. И уже из этой структуры в рантайме генерируются соответствующие DOM-элементы на странице, с которыми взаимодействует конечный пользователь. Причем ProseMirror хранит не только текущее состояние (state), но и историю предыдущих изменений, к которым можно при необходимости откатиться. Любое изменение состояния должно происходить через транзакции (transactions), привычные манипуляции с DOM-деревом напрямую тут не сработают. Транзакция – это абстракция, которая описывает логику пошагового изменения состояния. Суть их работы напоминает отправку и исполнение экшнов в библиотеках для управления состоянием, например, Redux и Vuex.
Сама библиотека построена на независимых модулях, которые можно отключать или добавлять в зависимости от потребностей. Список основных модулей, которые, как нам показалось, нужны будут практически всем:
- prosemirror-model – модель документа, описывающая все компоненты документа, их свойства и действия, которые можно совершить над ними;
- prosemirror-state – структура данных, которая описывает состояние созданного документа в определенный момент времени, включая выделенные фрагменты и транзакции для перехода от одного состояния в другое;
- prosemirror-view – представление документа в браузере и инструменты для того, чтобы пользователь мог взаимодействовать с документом;
- prosemirror-transform – функционал для хранения истории транзакций, с помощью которого реализованы транзакции и который позволяет откатываться до предыдущих состояний или вести совместную разработку одного документа.
Помимо этого минимального набора также полезными могут оказаться следующие модули:
- prosemirror-commands – набор уже готовых команд для редактирования. Как правило, что-то более сложное или индивидуальное нужно писать самому, но некоторые вещи Marijn Haverbeke уже сделал за нас, например, удаление выделенного фрагмента текста;
- prosemirror-keymap – модуль из двух методов для задания быстрых клавиш;
- prosemirror-history – реализация хранения истории изменений работает примерно как система контроля версий, т.е. можно откатить одни изменения, при этом сохранить другие, более поздние, что имеет особенное значение при совместной разработке;
- prosemirror-schema-list – набор команд для работы с элементами, имеющими отношение к списку (под элементом имеются в виду не DOM-элементы, а элементы контента, которые описаны в схеме нашего редактора).
Редактор с помощью ProseMirror
Начнем с создания схемы редактора. Схема в ProseMirror задает список элементов, которые в нашем документе могут быть, и их свойства. У каждого элемента есть метод toDOM, который определяет, как этот элемент будет представлен в DOM-дереве на веб-странице.
Принцип WYSIWYG реализуется именно в том, что у нас при создании схемы есть полный контроль над тем, как отображается редактируемый контент на странице, и, соответственно, мы можем задать каждому элементу такую HTML-структуру и задать стили так же, как контенту для просмотра. Ноды можно создавать и настраивать под свои требования, в частности, скорее всего вам могут понадобиться абзацы, заголовки, списки, картинки, абзацы, медиа.
Допустим, у нас каждый абзац текста должен оборачиваться в тег «p» с классом «paragraph», который определяет необходимые по макету правила стилей абзаца. Тогда схема ProseMirror в этом случае может выглядеть так:
import { Schema } from "prosemirror-model";
const mySchema = new Schema({
nodes: {
doc: {
content: 'block'
},
text: {},
paragraph: {
content: 'inline',
group: 'block',
toDOM: function toDOM(node) {
return ['p', {class: 'paragraph'}, 0];
},
},
},
});
Для начала импортируем конструктор для создания своей схемы и передаем в него объект, описывающий nodes (далее – ноды) в будущем редакторе. Ноды – это абстракции, описывающие типы создаваемого контента. Например, с такой схемой в редакторе могут быть только ноды типов text и paragraph. Doc – это имя ноды верхнего уровня, которая будет состоять только из блочных элементов, т.е. в данном случае только из параграфов (потому что другие мы не описали).
Text – это текстовые ноды, чем-то похожие на текстовые DOM-ноды. С помощью свойства group мы можем разными способами группировать наши ноды, чтобы к ним можно было проще обращаться в коде. Группы можно задать любым удобным нам способом. В нашем случае мы разделили ноды только на блочные и инлайные. Text является инлайновым по умолчанию, поэтому это можно явно не указывать.
Совсем другое дело paragraph (абзац). Мы объявили, что абзацы состоят из инлайновых текстовых элементов, а также имеют свое представление в DOM. Абзац будет являться блочным элементом, примерно в том смысле, в каком являются блочными элементы DOM. По этой схеме абзацы на странице будут представлены в онлайн-редакторе следующим образом:
<p class="paragraph">Content of the paragraph</p>
Теперь можно создать сам редактор:
import { EditorState } from "prosemirror-state";
import { EditorView } from "prosemirror-view";
import { Schema } from "prosemirror-model";
const mySchema = new Schema({
nodes: {
doc: {
content: 'block+'
},
text: {
group: 'inline',
inline: true
},
paragraph: {
content: 'inline*',
group: 'block',
toDOM: function toDOM(node) {
return ['p', {class: 'paragraph'}, 0];
},
},
},
});
/**
* @classdesc объект редактора
* @param {Object} el DOM-нода, в которую помещается редактор
*/
export default class Wysiwyg {
constructor(el) {
this.el = el;
}
/**
* @description генерирует стейт и вью редактора
* @param {Object} content объект, содержащий массив с элементами
*/
setArticle(content) {
const state = EditorState.fromJSON(
{schema: mySchema},
content,
);
const view = new EditorView(this.el, {state: state});
}
}
В начале, как обычно, импортируем все необходимые конструкторы из соответствующих модулей и берем уже описанную выше схему. Редактор создаем в виде класса с набором необходимых методов. Для того чтобы на веб-странице появилась возможность редактировать и создавать контент, нужно создать состояние – state, – используя схему и контент статьи, и представление контента из текущего состояния в заданном корневом элементе. Мы поместили эти действия в метод setArticle, кроме которого пока ничего не нужно.
При этом контент передавать необязательно. Если его нет, то получится пустой редактор, и контент уже можно будет создать непосредственно на месте. Допустим, у нас есть HTML-файл с такой разметкой:
<div id="editor"></div>
Для создания на странице пустого WYSIWYG-редактора понадобится всего несколько строк в скрипте, который выполняется на странице с такой разметкой:
// импортируем конструктор редактора из пакета
import Wysiwyg from 'wysiwyg';
const root = document.getElementById('editor');
const myWysiwyg = new Wysiwyg(root);
myWysiwyg.setArticle();
С помощью такого кода можно написать с нуля любой текст. На этом этапе уже можно посмотреть, как работает ProseMirror.
Когда пользователь печатает текст в этом редакторе, возникают транзакции состояния. Например, если в редакторе с описанной выше схемой напечатать фразу «Это мой новый классный WYSIWYG-редактор», ProseMirror отреагирует на ввод с клавиатуры тем, что вызовет соответствующий набор транзакций, и после окончания ввода в состоянии документа обновится контент, который будет выглядет так:
content: [
{
type: 'paragraph',
value: 'Это мой новый классный WYSIWYG-редактор',
},
]
Если же мы хотим, чтобы в редакторе сразу открывался для редактирования какой-нибудь текст, например, контент уже созданной ранее статьи, то необходимо, чтобы этот контент соответствовал созданной ранее схеме. Тогда код инициализации редактора будет выглядеть немного по-другому:
// импортируем конструктор редактора из пакета
import Wysiwyg from 'wysiwyg';
const root = document.getElementById('editor');
const myWysiwyg = new Wysiwyg(root);
const content = {
type: 'doc',
content: [
{
type: 'paragraph',
value: 'Hello, world!',
},
{
type: 'paragraph',
value: 'This is my first wysiwyg-editor',
}
],
};
myWysiwyg.setArticle(content);
Ура! Мы сделали наш первый редактор, который умеет создавать чистую страницу для создания нового контента и открывать для редактирования существующий.
Что делать с редактором дальше
Но даже с полным набором нод в нашем редакторе все еще отсутствуют важные функции — форматирование текста, абзацев. Для этого помимо нод в схему надо еще передать объект с настройками для форматирования – marks. Для простоты мы их так и называем – марками. А для управления добавлением, удалением и форматированием всех этих элементов пользователям нужно будет меню. Меню можно добавить с помощью кастомных плагинов, которые стилизуют объекты меню и описывают изменение состояния документа при выборе тех или иных действий.
С помощью плагинов можно создавать любые конструкции, расширяющие встроенные возможности редактора. Основная идея плагинов заключается в том, что они обрабатывают определенные действия пользователя, чтобы генерировать соответствующие им транзакции. Например, если нужно, чтобы клик по иконке списка в меню создавал новый пустой список и переводил курсор в начало первого элемента, то нам точно понадобится описать эту транзакцию в соответствующем плагине.
Подробнее про настройки форматирования и плагины можно почитать в официальной документации, также очень полезными могут быть наглядные небольшие примеры использования возможностей ProseMirror.
P.S.Скоро мы также расскажем, как мы интегрировали новый текстовый редактор в действующий проект и запустили его в бета-тестирование.
Автор: Валерия Токарева
