Lexical: редактор текста без React — мастерская и 9 живых задач
Собираем редактор заметок для CRM и базы знаний: девять живых задач, настоящий Lexical, история, локальные черновики, JSON и Markdown. Исходники Windows/Linux.

Lexical: редактор текста как часть рабочего интерфейса
Почти в каждом сервисе наступает момент, когда одного текстового поля становится мало. В карточке клиента нужно выделить договорённость, в инструкции — отделить шаги, в базе знаний — добавить заголовок и ссылку, а в отчёте — сохранить понятную структуру. Пользователь хочет написать документ, а разработчик должен обеспечить предсказуемое редактирование, восстановление и обмен данными.
Lexical — библиотека для построения таких редакторов. Она даёт модель документа, команды, выделение и механизм согласования состояния с DOM. Вокруг этого можно собрать собственную панель, форму и правила хранения. Ниже находится настоящий редактор с девятью связанными задачами: его можно менять прямо на странице, сохранять локальный черновик и скачивать результат.
Материал рассчитан на практическое применение. Мы соберём заметку для карточки клиента, разберём форматирование, списки, ссылки и историю, затем подготовим данные для будущего API. Весь проект доступен с исходниками, тестами, закреплёнными зависимостями и отдельными инструкциями Windows и Linux. React для этого примера не требуется.
Где применять: CRM, база знаний, заявки и внутренние кабинеты
В CRM редактор полезен для заметок менеджера: важная фраза выделена, договорённости разделены абзацами, ссылки ведут к документам проекта. В базе знаний структура становится основой чтения: заголовки помогают найти ответ, цитата отделяет правило, список показывает последовательность. В форме обращения удобно дать человеку небольшое форматирование без десятков лишних кнопок.
Для каждого сценария нужен свой набор возможностей. Комментарий к заказу обычно не требует таблиц и вложенных редакторов, а полноценная статья может требовать изображений и блоков кода. Если включать все функции заранее, интерфейс становится сложнее, а формат документов — труднее поддерживать. Начните с того, что помогает закончить конкретную работу пользователя.
Наша мастерская использует один документ и девять способов взаимодействия с ним. Смена учебной задачи сохраняет текст. Отдельная кнопка загружает подходящий пример и явно заменяет содержимое. Это похоже на настоящий рабочий кабинет: человек видит свой результат и понимает, какое действие меняет данные, а какое только открывает следующий инструмент.
Lexical, textarea и contenteditable: что выбрать
Для короткого обычного текста textarea остаётся хорошим решением. У него понятное поведение, готовые браузерные механизмы ввода и небольшой объём собственного кода. Если достаточно имени, описания без оформления или сообщения в одну строку, сложный редактор не добавляет полезности. Выбирать библиотеку стоит после определения структуры будущего документа.
Один contenteditable позволяет вводить форматированный текст, но сам по себе не задаёт устойчивую модель хранения и прикладные правила. Разработчику приходится разбираться с выделением, вставкой, историей, сериализацией и различиями DOM. Lexical помогает работать с документом через узлы и состояние, оставляя оформление панели и бизнес-логику приложению.
Это также не готовый офисный пакет. Библиотека не создаёт автоматически систему прав, облачное хранение, согласование или совместное редактирование. Эти возможности нужно проектировать отдельно. В демонстрации есть два настоящих экземпляра Lexical: редактируемый документ и просмотр для читателя. Сеть используется для загрузки ресурсов мастерской, а не для отправки написанного текста.
Версия 0.53.0 и одинаковые пакеты Lexical
На момент подготовки примера npm latest указывает на Lexical 0.53.0. Все пакеты семейства @lexical закреплены той же версией, Bootstrap используется в версии 5.3.9, сборка выполняется esbuild 0.28.2. Точный набор транзитивных зависимостей находится в package-lock.json, поэтому повторение начинается с npm ci, а не со случайного обновления всего проекта.
Современный официальный быстрый старт строится вокруг extensions: расширение описывает узлы, настройки, поведение и зависимости. В проекте используются RichTextExtension, HistoryExtension, ListExtension, CheckListExtension и LinkExtension. Это позволяет собрать редактор без React и не регистрировать вручную одну и ту же возможность в нескольких местах.
Сверяйте API с официальным Vanilla JS quick start и выпуском 0.53.0. Смешивание разных версий core и расширений может дать труднообъяснимое поведение. Обновление редактора рассматривайте как изменение формата и взаимодействия с документами: повторите импорт старых заметок, списки, ссылки и историю.
Фрагмент файла package.json
{
"name": "aen-lexical-workshop", "version": "1.0.0", "private": true,
"type": "module", "license": "MIT", "engines": {"node": ">=24.15.0"},
"scripts": {"build":"node tools/build.mjs","test":"node --test tests/*.test.mjs","serve":"node tools/serve.mjs","capture":"node tools/capture.mjs"},
"dependencies": {"lexical":"0.53.0","@lexical/extension":"0.53.0","@lexical/rich-text":"0.53.0","@lexical/history":"0.53.0","@lexical/list":"0.53.0","@lexical/link":"0.53.0","@lexical/selection":"0.53.0","@lexical/markdown":"0.53.0","@lexical/headless":"0.53.0","bootstrap":"5.3.9"},
"devDependencies": {"esbuild":"0.28.2"}
}
Мини-мастерская: девять задач одного редактора
Выберите задачу, прочитайте короткую инструкцию и попробуйте действие в документе. Начать можно с кнопки загрузки учебного текста. На первом экране доступно обычное редактирование, затем — оформление, структура, списки, ссылки и история. Последние задачи посвящены локальному черновику, переносу JSON/Markdown и подготовке запроса для приложения.
Кнопка «Выделить всё» помогает проверить форматирование, особенно на узком экране. Панель показывает активные текстовые форматы. Справа на широком экране, а ниже на мобильном, находится отдельный просмотр для читателя. Это реальный readonly-редактор, который получает новое состояние после изменения основного документа.
На странице нет скрытого сохранения заметок на сервере. Локальный черновик появляется только после явного нажатия, а действие подготовки API выводит JSON без отправки. Для копирования исходников предусмотрен отказ браузера и возможность скачать файл. Полный проект можно открыть отдельной страницей или загрузить одним архивом.
Быстрый запуск в Windows и PowerShell
Распакуйте проект и откройте PowerShell в его корне. Нужен установленный Node.js 24 с npm. Сначала проверьте версию, затем восстановите зависимости из lock-файла, выполните тесты и сборку. Команда serve открывает только локальный HTTP-сервер на 127.0.0.1, поэтому учебная страница не становится доступной всей локальной сети.
После запуска откройте адрес http://127.0.0.1:8573/. Не запускайте index.html двойным щелчком через file://: модули и загрузка sources.json рассчитаны на HTTP. Если порт уже занят, задайте другое значение PORT перед командой serve. Остановить процесс можно Ctrl+C в той же консоли.
Готовый каталог public уже включён в архив. Он нужен читателю, который хочет сначала посмотреть пример. Для изменения кода работайте с src и пересобирайте проект: изменение только минифицированного app.js быстро создаёт расхождение между исходниками, просмотрщиком кода и опубликованной версией. Сборка выполняет необходимые копирования автоматически.
node --version
npm ci --ignore-scripts
npm test
npm run build
npm run capture
npm run serve
$env:PORT='8574'
npm run serve
Linux: сборка, локальная проверка и отличие от VPS
В Linux выполняются те же npm-команды и используется тот же package-lock.json. Проверьте установленный Node: версия из системного репозитория может отличаться от выбранной для проекта. Не нужно переносить node_modules с Windows. Восстановите зависимости на целевой системе, чтобы платформа получила подходящий исполняемый файл сборщика.
Локальный сервер проекта удобен для разработки и проверки поведения, но не заменяет настройку публичного сайта. Для размещения достаточно содержимого public под Nginx, Caddy или другим статическим веб-сервером. Постоянно держать npm serve на открытом сетевом порту ради этой мастерской не требуется.
В наших проверках настоящий Node в Linux запускался внутри отдельного локального контейнера. Он выполнил тесты Lexical и собрал файлы, затем результаты сравнивались с Windows. Это подтверждает воспроизводимость проекта в этих средах. Настройка TLS, прав каталогов и реального production VPS остаётся отдельным этапом, описанным далее.
node --version
npm ci --ignore-scripts
npm test
npm run build
PORT=8573 npm run serve
Создание редактора: расширения, тема и корневой элемент
Редактор собирается функцией makeEditor. В ней находится единое описание зависимостей, тема CSS и начальный документ. RichTextExtension обеспечивает базовое редактирование, расширения списков добавляют соответствующие узлы и команды, история отвечает за отмену и повтор, а LinkExtension подключает ссылки. Ограничение URL задаётся рядом с этой конфигурацией.
После создания экземпляра setRootElement связывает его с конкретным элементом страницы. У основного поля есть роль textbox, доступное название и признак многострочного ввода. У readonly-предпросмотра другой экземпляр и namespace: данные можно копировать между состояниями, но пользователь не должен случайно редактировать область просмотра.
Оформление узлов задаётся классами темы. Например, жирный текст получает text-bold, цитата — editor-quote, а чек-лист — классы состояния пункта. Не храните в каждом документе случайный набор inline-стилей только ради внешнего вида. Согласованная тема делает заметки предсказуемыми и позволяет менять оформление сайта без переписывания всех документов.
Фрагмент файла src/editor.mjs
export function makeEditor({headless=false,name='AENLexical',editable=true,onError=(e)=>{throw e;}}={}) {
return buildEditorFromExtensions(defineExtension({
name,namespace:name,editable,theme,onError,
dependencies:[RichTextExtension,configExtension(HistoryExtension,{delay:300,disabled:false,maxDepth:100}),ListExtension,CheckListExtension,configExtension(LinkExtension,{validateUrl:(value)=>{try{safeUrl(value);return true;}catch{return false;}}}),...(headless?[HeadlessExtension]:[])],
$initialEditorState(){ $getRoot().append($createParagraphNode().append($createTextNode(initialText))); }
}));
}
EditorState: почему данные документа важнее innerHTML
Источником состояния Lexical служит EditorState с деревом узлов и выделением. DOM отображает это состояние, но прикладное сохранение не обязано собирать случайную HTML-строку из contenteditable. В проекте сериализация берёт toJSON, а восстановление проходит через parseEditorState и setEditorState после проверки нашего контракта.
Функции с префиксом доллара вызываются внутри синхронного read или update контекста Lexical. Не выносите $getRoot в произвольный обработчик вне этого контекста и не вставляйте await внутрь изменения дерева. Если перед изменением нужны данные API, сначала дождитесь их, затем выполните короткую синхронную операцию над редактором.
Обычные обновления могут объединяться до фиксации DOM. В инструментах экспорта нам требуется уже согласованный результат, поэтому helper snapshot использует force-commit read. Это осознанная граница получения снимка, а не инструкция принудительно фиксировать каждое нажатие клавиши. Подробности жизненного цикла описаны в документации Editor State.
Фрагмент файла src/editor.mjs
export function snapshot(editor) {return editor.read('force-commit',()=>JSON.parse(JSON.stringify(editor.getEditorState().toJSON())));}
export function plainText(editor) {return editor.read('force-commit',()=>$getRoot().getTextContent());}
// Call inside editor.update. A document replacement creates fresh node keys.
export function restoreBookmark(bookmark) {
if(!bookmark || !$getNodeByKey(bookmark.anchor.key) || !$getNodeByKey(bookmark.focus.key))return false;
$setSelection(bookmark.clone());return true;
}
Пример 1. Заметка клиента и режим чтения
Откройте первую задачу, измените одну фразу и посмотрите, как обновился предпросмотр. У основного документа свой фокус и полоса прокрутки для длинного содержимого. Пустая заметка показывает подсказку, а счётчик меняется по фактическому тексту дерева, а не по длине HTML с тегами.
Переключатель «Только чтение» вызывает setEditable. Одновременно недоступными становятся кнопки изменения документа, а aria-readonly отражает режим для вспомогательных технологий. Сам текст остаётся видимым и пригодным для выделения. Такой режим полезен в карточке завершённого обращения или при просмотре документа без разрешения на изменение.
Клиентский readonly не является защитой серверных данных. Пользователь может изменить код своей страницы или отправить запрос напрямую. Настоящее право редактирования проверяется API при каждом сохранении. В мастерской режим нужен для демонстрации поведения интерфейса; он не выдаётся за серверную авторизацию.
Фрагмент файла src/app.mjs
$('readonly').addEventListener('change',()=>{
editor.setEditable(!$('readonly').checked);for(const e of document.querySelectorAll('[data-edit]'))e.disabled=$('readonly').checked;
$('editor').setAttribute('contenteditable',String(!$('readonly').checked));
$('editor').setAttribute('aria-readonly',String($('readonly').checked));$('undo').disabled=!canUndo||$('readonly').checked;$('redo').disabled=!canRedo||$('readonly').checked;
status($('readonly').checked?'Режим чтения: документ нельзя изменить.':'Редактирование включено. История изменений сохранена.');
});
Пример 2. Жирный текст, курсив и зачёркивание
Выделите несколько слов и нажмите кнопку формата. Можно использовать собственную кнопку полного выделения, чтобы быстро увидеть результат на всём документе. Если выделение свёрнуто в курсор, формат применяется к дальнейшему вводу. Это стандартное для редактора различие стоит объяснять рядом с панелью, иначе пользователь ожидает изменение уже существующей фразы.
Кнопки отражают формат текущего выделения через aria-pressed и цвет. Состояние читается из настоящей RangeSelection. Мы не запоминаем отдельную переменную «жирный включён», которая легко расходится с документом после перехода курсора. Когда выделение меняется, панель заново получает актуальную информацию.
Обработчик pointerdown на кнопках оформления сохраняет фокус редактирования при работе мышью. Для операций после ввода URL используется сохранённое выделение. Такие детали важнее количества иконок: если пользователь выделил текст, а панель потеряла выделение, внешне красивая кнопка не выполняет ожидаемую работу. Клавиатурный сценарий проверяется отдельно.
Фрагмент файла src/app.mjs
for(const button of document.querySelectorAll('[data-format]')){
button.addEventListener('pointerdown',event=>event.preventDefault());
button.addEventListener('click',()=>{if(edit(()=>{const s=$getSelection();if(!$isRangeSelection(s))return false;s.formatText(button.dataset.format);}))status('Форматирование применено к выделению или следующему вводимому тексту.');});
}
Пример 3. Заголовки, цитаты и очистка оформления
Третий пример работает со структурой выбранного блока. Поставьте курсор в абзац или выделите несколько строк, затем выберите заголовок или цитату. В проекте доступны уровни h1–h3 и обычный абзац. Это сознательно небольшой набор, достаточный для рабочих заметок и инструкций без сложной вёрстки.
Команда $setBlocksType заменяет тип блоков через фабрику соответствующего узла. Она не делает заголовок простым увеличением шрифта у части текста. Такая структура лучше подходит для последующего экспорта, анализа и единообразного отображения документа. Тема редактора определяет, как именно заголовок или цитата выглядят на сайте.
Кнопка очистки сбрасывает текстовые форматы и style у выделенных текстовых узлов. Тип блока при этом сохраняется: заголовок остаётся заголовком. Такое поведение явно написано в сообщении результата. В продукте лучше разделить очистку оформления текста и превращение всей структуры в обычные абзацы, потому что это разные пользовательские действия.
Фрагмент файла src/app.mjs
$('block').addEventListener('change',()=>edit(()=>{const s=$getSelection();if($isRangeSelection(s))$setBlocksType(s,()=>$('block').value==='quote'?$createQuoteNode():$('block').value==='paragraph'?$createParagraphNode():$createHeadingNode($('block').value));}));
$('clear-format').addEventListener('click',()=>{if(edit(()=>{const s=$getSelection();if(!$isRangeSelection(s))return false;for(const n of s.extract())if(n.getType()==='text'){n.setFormat(0);n.setStyle('');}s.setFormat(0);}))status('Оформление выделенного текста очищено; типы блоков сохранены.');});
Пример 4. Маркеры, нумерация и чек-лист
Загрузите учебные строки четвёртой задачи, выделите их и выберите вид списка. Маркеры подходят для набора требований, нумерация — для последовательности, чек-лист — для действий с состоянием выполнения. В последнем случае нажатие на квадрат слева меняет checked настоящего ListItemNode.
ListExtension и CheckListExtension дают поведение списков, а собственные кнопки вызывают $insertList или $removeList. Состояние готовности пункта принадлежит документу и попадает в JSON. Это отличается от случайно нарисованного HTML-checkbox рядом с текстом, который можно забыть сохранить вместе с заметкой.
Не превращайте редакторский чек-лист в систему задач без дополнительной модели. В нём нет автоматически назначенного исполнителя, срока, уведомления или журнала изменения статуса. Для небольшой инструкции это удобно, но управляемая задача CRM должна иметь отдельную сущность. Текстовый документ может ссылаться на неё и объяснять контекст.
Фрагмент файла src/app.mjs
for(const type of ['bullet','number','check'])$('list-'+type).addEventListener('click',()=>edit(()=>$insertList(type)));
$('list-remove').addEventListener('click',()=>edit(()=>$removeList()));
Пример 5. Добавление и удаление ссылки
Сначала выделите текст в документе, затем введите адрес в поле и примените ссылку. В этой мастерской допускаются полные HTTP- и HTTPS-адреса без логина и пароля. Относительные адреса специально не входят в контракт: это делает перенос примера между отдельной страницей и iframe однозначным.
Попробуйте javascript:alert(1) или data URL. Проверка откажет до изменения документа, а понятное сообщение останется в статусе. Та же проверка вызывается при импорте JSON, чтобы пользователь не обходил правила простой вставкой подготовленного состояния. Не достаточно ограничить только текстовое поле на панели.
Кнопка удаления снимает ссылку с выбранной области, сохраняя текст. В режиме редактирования клик по ссылке не открывает постороннюю страницу, поэтому курсором можно работать внутри неё. Если продукту нужен кликабельный просмотр, это следует включать отдельно и проверять target, rel и правила допустимых адресов на стороне приложения.
Фрагмент файла src/contract.mjs
export function safeUrl(input) {
const raw=String(input).trim();
if(!raw || /[\u0000-\u0020\u007f]/.test(raw)) throw new Error('Введите полный HTTPS- или HTTP-адрес без пробелов.');
let url;try{url=new URL(raw);}catch{throw new Error('Не удалось распознать адрес. Пример: https://example.com/help');}
if(!['https:','http:'].includes(url.protocol)||url.username||url.password)throw new Error('Разрешены только HTTP и HTTPS без логина и пароля в адресе.');
return url.href;
}
Пример 6. История: отмена, повтор и границы документа
Измените фразу, добавьте оформление и нажмите «Отменить». Затем верните действие кнопкой повтора. Доступность этих команд отражает состояние реальной истории Lexical. Несколько близких по времени нажатий при наборе могут объединяться в один шаг, поэтому история не обязана считать каждый символ самостоятельной операцией.
В конфигурации выбрана задержка объединения 300 миллисекунд и предел истории 100 записей. Программные действия панели отмечаются тегом HISTORY_PUSH_TAG, чтобы ожидаемое изменение имело отдельную границу. При загрузке нового учебного документа прежняя история очищается: отмена не должна внезапно вернуть содержание другого примера.
История в памяти редактора не заменяет версии на сервере. После закрытия вкладки она не превращается в журнал аудита, а сохранённый JSON не содержит всех предыдущих состояний. Если важно знать, кто изменил договорённость и когда, храните версии или события отдельно. Пользовательская кнопка отмены и серверная история решают разные задачи.
Фрагмент файла src/app.mjs
$('undo').addEventListener('click',()=>{editor.dispatchCommand(UNDO_COMMAND,undefined);status('Отмена последнего изменения.');});
$('redo').addEventListener('click',()=>{editor.dispatchCommand(REDO_COMMAND,undefined);status('Повтор изменения.');});
Пример 7. Локальный черновик и отказ хранилища
Нажмите «Сохранить черновик», измените текст и восстановите сохранённое состояние. Данные находятся в localStorage текущего origin. Они не переходят автоматически на другой компьютер, другой браузер или другой домен. Поэтому интерфейс прямо сообщает место хранения и не показывает обещание облачного сохранения.
Удаление локального черновика не очищает документ, который сейчас открыт. Это полезное различие: человек может убрать сохранённую копию, продолжая работать с текстом в памяти. Если черновика ещё нет, восстановление выдаёт объяснение. Если браузер запрещает storage или исчерпана квота, ошибка не маскируется сообщением об успехе.
Для настоящего сервиса подумайте о смене пользователя на общем устройстве. Один постоянный ключ без учёта аккаунта может показать чужой черновик следующему человеку. В учебном примере нет входа и используются вымышленные данные. В приложении ключ связывают с аккаунтом и документом, а удаление данных при выходе определяется явной политикой продукта.
Фрагмент файла src/contract.mjs
export function storageAction(storage,action,value) {
const key='aen-lexical-draft-v1';
try{if(action==='save'){storage.setItem(key,JSON.stringify(value));return 'Черновик сохранён в этом браузере.';}
if(action==='delete'){storage.removeItem(key);return 'Локальный черновик удалён. Текущий текст оставлен в редакторе.';}
const raw=storage.getItem(key);if(raw===null)throw new Error('Сохранённого черновика пока нет.');return validateState(raw).state;
}catch(error){throw new Error('Черновик: '+error.message);}
}
Пример 8. JSON: полный перенос состояния
В восьмой задаче можно поместить текущий JSON в поле, скачать его и применить обратно. Это полезно для изучения структуры: после форматирования меняется поле format, после создания списка появляются list и listitem, у ссылки хранится URL. Читатель видит связь между действием в интерфейсе и данными документа.
Перед parseEditorState работает собственная проверка. Она ограничивает размер, число узлов, глубину, поддерживаемые типы, версии и адреса ссылок. Произвольные стили отключены. Если JSON повреждён или содержит неизвестный узел, текущий документ сохраняется. Ошибка импорта не должна уничтожать уже набранный пользователем текст.
Этот контракт относится к конкретному набору расширений мастерской. Нельзя обещать, что он примет любой документ из чужого редактора Lexical. Например, изображение или таблица требуют зарегистрированных узлов и согласованных правил. Для обмена между сервисами заранее определите поддерживаемую схему и способ миграции, а не только расширение файла .json.
Фрагмент файла src/editor.mjs
export function replaceJson(editor,input) {
const {state}=validateState(input);const parsed=editor.parseEditorState(state);if(parsed.isEmpty())throw new Error('Пустое состояние нельзя применить.');editor.setEditorState(parsed);
}
Markdown: удобный обмен с ограниченной выразительностью
Markdown удобен для заметок, документации и обмена с другими инструментами, но его возможности не равны всему дереву Lexical. В проекте выбран набор трансформеров для заголовков, цитат, списков, checklist, текстового оформления и ссылок. Таблицы, изображения и блоки кода не подключены к этой мастерской.
Порядок трансформеров имеет значение. Обработка checklist стоит перед обычным маркированным списком, иначе строка с квадратными скобками может быть распознана как простой пункт. Это проверяется настоящим тестом: после импорта первый узел должен оставаться списком типа check, а выполненный пункт — хранить checked: true.
Импорт сначала выполняется во временном headless-редакторе. Затем полученное дерево проходит тот же контракт и только после этого заменяет основной документ. Опасная ссылка в Markdown тоже отклоняется. Экспорт может терять свойства, для которых в выбранном наборе нет представления; для точного хранения нашего документа используйте JSON. Подробнее — справочник Markdown-пакета.
Фрагмент файла src/editor.mjs
export function exportMarkdown(editor) {return editor.read('force-commit',()=>$convertToMarkdownString(MARKDOWN_TRANSFORMERS));}
Фрагмент файла src/editor.mjs
export function importMarkdown(editor,text) {
if(new TextEncoder().encode(text).length>65536)throw new Error('Markdown больше 64 КиБ.');
const scratch=makeEditor({headless:true,name:'MarkdownImport'});
try{scratch.update(()=>$convertFromMarkdownString(text,MARKDOWN_TRANSFORMERS),{discrete:true});const checked=validateState(snapshot(scratch));replaceJson(editor,checked.state);}
finally{scratch.dispose();}
}
Пример 9. Подготовка запроса к API
Последняя задача добавляет заголовок заметки и проверяет документ перед будущей отправкой. Заголовок должен содержать от трёх до 120 символов, а основной текст — хотя бы десять содержательных символов. При успехе появляется объект с schema, title и document. При ошибке старый payload очищается, чтобы он не выглядел результатом текущей проверки.
Здесь нет вызова fetch к серверному endpoint. Это честно написано рядом с кнопкой: пользователь получает подготовленные данные и может посмотреть контракт, но не получает ложное уведомление о сохранении. Такой этап полезен при разработке интерфейса до подключения backend и при объяснении структуры запроса коллегам.
В реальном приложении после успешной клиентской проверки появятся состояния отправки, принятого результата, ошибки сети и конфликта версии. Кнопка не должна допускать случайную двойную отправку. Сохранение признаётся завершённым по ответу сервера, а не по тому, что JSON удалось создать в браузере.
Фрагмент файла src/contract.mjs
export function makePayload(title,state) {
const checked=validateState(state);const name=String(title).trim();
if(name.length<3||name.length>120)throw new Error('Заголовок должен содержать от 3 до 120 символов.');
if(checked.text.trim().length<10)throw new Error('Добавьте хотя бы 10 символов содержательного текста.');
return {schema:1,title:name,document:checked.state};
}
Как связать редактор с PHP и базой данных
Для PHP API сохраняйте структуру документа как JSON в подходящем поле базы. Запрос должен проходить аутентификацию, проверку права изменения конкретной записи, ограничения размера и валидацию схемы. ID текущего пользователя берётся из проверенной сессии или токена, а не из произвольного поля JSON, которое прислал клиент.
Если используется cookie-аутентификация, отдельно учитывайте CSRF. Сам текст заметки передавайте в параметризованный SQL, а не собирайте запрос конкатенацией. Не превращайте содержимое JSON в исполняемый PHP-файл и не выводите его через innerHTML. Формат документа и правила его безопасного отображения должны быть определены на серверной границе.
Для параллельного редактирования полезна версия записи. Клиент отправляет версию, которую прочитал, сервер обновляет данные только при её совпадении, иначе возвращает конфликт. Это помогает избежать тихого перезаписывания чужой заметки. Полный серверный сервис в архив не включён; практический контракт и необходимые проверки подробно перечислены в VPS.md.
Ошибки API: что показать пользователю
Разные сбои требуют разных действий. При ошибках полей интерфейс оставляет текст и подсвечивает исправляемые значения. При отсутствии сессии предлагает повторный вход, при запрете изменения объясняет режим чтения, а при конфликте версии предлагает загрузить актуальный документ. Одна общая надпись «что-то пошло не так» не помогает продолжить работу.
Сеть может оборваться уже после того, как сервер сохранил данные. Повтор запроса без продуманной семантики способен создать дубликат заметки или повторное событие. Для создания новых сущностей можно использовать идентификатор операции, а для изменения существующей — версию и идемпотентный контракт. Конкретная схема зависит от приложения, а не от редактора.
Не очищайте содержимое формы до подтверждённого результата. Локальный черновик может помочь восстановлению, но его нельзя незаметно считать последней серверной версией. В интерфейсе полезно различать «изменения только в браузере», «отправляется» и «сохранено сервером». Пользователь должен понимать, можно ли безопасно закрывать вкладку.
Сериализация, HTML и вставка из других программ
JSON Lexical описывает узлы конкретного редактора. HTML описывает представление, которое может содержать стили, ссылки и дополнительные атрибуты. Эти форматы нельзя автоматически считать взаимозаменяемыми или одинаково безопасными. Серверная проверка должна соответствовать тому формату, который действительно сохраняется и затем выводится в интерфейс.
В мастерской внешняя HTML-вставка специальным extension не подключена. Это уменьшает набор преобразований, который требуется объяснить и проверить. Если продукту нужна вставка из Word или другого редактора, добавьте соответствующий механизм отдельно, определите разрешённые узлы и проверьте реальные документы с лишними стилями, таблицами и ссылками.
Санитарная обработка HTML не заменяет права доступа, а проверка URL на клиенте не заменяет серверное правило. Для readonly-вывода можно использовать Lexical с тем же набором узлов либо отдельный согласованный renderer. При смене renderer повторите проверку потенциально опасных входов. О возможностях форматов и преобразований читайте в официальном разделе Serialization.
Мобильный интерфейс: выделение, кнопки и прокрутка
Редактор на телефоне предъявляет другие требования к панели. Кнопки должны переноситься по строкам и оставаться достаточно крупными, а форма ссылки — помещаться в ширину документа. В мастерской нет широкой таблицы инструментов: группы действий используют перенос, поле редактирования имеет собственную прокрутку, а предпросмотр уходит вниз.
Системные маркеры выделения текста не всегда удобны для первого знакомства. Поэтому есть явная кнопка полного выделения и отдельный учебный текст каждого примера. Это не заменяет обычное выделение фразы, но позволяет быстро попробовать форматирование и списки. В реальном продукте также проверьте появление экранной клавиатуры и положение активной кнопки относительно поля.
Браузерная проверка ширины помогает найти горизонтальное расширение и обрезанные подписи, но не равна испытанию на всех физических устройствах. IME, автозамена, системный clipboard и жесты зависят от платформы. Для рабочего сервиса добавьте ручные сценарии на тех устройствах и языках ввода, которыми действительно пользуется ваша аудитория.
Доступность: подписи, состояние и клавиатура
Основное поле имеет доступное название и роль многострочного textbox. Кнопки подписаны словами, активные форматы отражаются через aria-pressed, а сообщения результата находятся в области status. Состояние readonly передаётся не только цветом. Такие детали позволяют понять действие без знания внутренних названий команд библиотеки.
Не делайте всю панель доступной только по наведению мыши. Человек должен дойти до нужного инструмента клавиатурой и вернуться к тексту, сохранив понятный контекст. В мастерской используются стандартные элементы button, select, input и textarea, заметная рамка фокуса и достаточно крупные цели нажатия.
Наличие ARIA-атрибутов само по себе не означает полную сертификацию доступности. Проверяйте последовательность фокуса, чтение сообщений, структуру заголовков и редактор с выбранными вспомогательными технологиями. Если добавляется всплывающее меню или диалог, отдельно проектируются закрытие Escape, возврат фокуса и поведение при масштабировании страницы.
Ограничения импорта и размер документов
В учебном контракте JSON ограничен 64 КиБ, числом узлов 500 и глубиной 12. Текст ограничен 12 000 символов UTF-16. Эти значения описывают конкретную мастерскую и не являются максимальной производительностью Lexical. Они нужны, чтобы опыт оставался предсказуемым и ошибка проверялась до применения большого или неподдерживаемого состояния.
Размер текста, количество узлов и глубина — разные характеристики. Небольшой видимый текст может иметь сложное дерево, а длинный обычный абзац — состоять из одного текстового узла. Поэтому один лимит длины строки не охватывает все формы входа. Ограничения нужно повторять на сервере, если документ можно отправить через API.
Для больших баз знаний измеряйте реальные операции на своих документах: набор, выделение, импорт, сериализацию и отображение readonly. Не делайте вывод о быстродействии по короткой учебной заметке. Разделение статьи на документы, отложенное открытие редактора и подходящая структура данных часто полезнее неограниченного роста одного поля.
Фрагмент файла src/contract.mjs
export function validateState(input) {
const raw=typeof input==='string'?input:JSON.stringify(input);
if(new TextEncoder().encode(raw).length>LIMITS.bytes)throw new Error('Документ больше 64 КиБ.');
let state;try{state=JSON.parse(raw);}catch{throw new Error('Некорректный JSON: проверьте скобки, кавычки и запятые.');}
if(!state||state.root?.type!=='root'||!Array.isArray(state.root.children)||!state.root.children.length)throw new Error('Нужен непустой корневой узел Lexical root с children.');
let count=0,text='';
function visit(node,depth){
if(!node||typeof node!=='object'||Array.isArray(node)||!types.has(node.type))throw new Error('Документ содержит неподдерживаемый тип узла.');
if(++count>LIMITS.nodes||depth>LIMITS.depth)throw new Error('Слишком много узлов или уровней вложенности.');
if(node.version!==1)throw new Error('Поддерживается версия узла 1.');
if(node.style || node.textStyle)throw new Error('Произвольные CSS-стили в импортируемом документе отключены.');
if(node.type==='text'){if(typeof node.text!=='string')throw new Error('У текстового узла должно быть строковое поле text.');text+=node.text;if(node.format!==undefined&&(!Number.isInteger(node.format)||node.format<0||node.format>2047))throw new Error('Неверное форматирование текста.');}
if(node.type==='heading'&&!['h1','h2','h3'].includes(node.tag))throw new Error('В мастерской доступны заголовки h1–h3.');
if(node.type==='list'&&!['bullet','number','check'].includes(node.listType))throw new Error('Неподдерживаемый тип списка.');
if(node.type==='link')safeUrl(node.url);
if(node.children!==undefined){if(!Array.isArray(node.children))throw new Error('children должен быть массивом.');for(const child of node.children)visit(child,depth+1);}
}
visit(state.root,0);if(text.length>LIMITS.text)throw new Error('Текст длиннее 12 000 символов UTF-16.');
return {state,count,text};
}
Linux/VPS: опубликовать готовый каталог через Nginx
После сборки перенесите только public в отдельный каталог сайта. В VPS.md приведён пример для учебного hostname и каталога /var/www/lexical-demo. Перед копированием замените значения под свой сервер и проверьте существующую конфигурацию. Команды не предназначены для запуска на корне чужого или уже работающего приложения.
Веб-сервер должен отдавать JavaScript с корректным MIME, существующие файлы без подмены HTML-страницей и ожидаемый 404 для отсутствующего ресурса. Это особенно важно при включённом nosniff. После изменения конфигурации сначала выполните nginx -t, затем штатную перезагрузку конфигурации и проверку HTTP-заголовков.
Настройте HTTPS механизмом вашего хостинга или выбранного веб-сервера. На сайте уже есть подробные материалы про повседневные настройки Nginx и Caddy, HTTPS и reverse proxy. Для этой статической мастерской proxy к Node не требуется. Если добавляете PHP API, его конфигурация, права и лимиты проверяются отдельно.
server {
listen 80;
server_name editor.example.com;
root /var/www/lexical-demo;
index index.html;
include /etc/nginx/mime.types;
add_header X-Content-Type-Options nosniff always;
location / { try_files $uri $uri/ =404; }
}
sudo nginx -t
sudo systemctl reload nginx
curl -I http://editor.example.com/
curl -I http://editor.example.com/app.js
Обновления: версия приложения, документы и откат
Версия JSON-контракта приложения не обязана совпадать с версией пакета Lexical. Поле schema в подготовленном payload описывает правила нашего API. Когда меняется набор узлов или обязательные поля, нужно решить, как читаются старые документы, как они преобразуются и какие версии принимает сервер.
Перед обновлением зависимостей сохраните небольшой набор собственных тестовых заметок: простой текст, несколько форматов, списки, checklist, ссылки и длинные абзацы. Новый набор пакетов должен прочитать их и дать ожидаемый результат. Проверяйте не только отсутствие ошибки парсинга, но и смысловое сохранение структуры, текста и состояния пунктов.
Frontend можно выпускать отдельными каталогами и переключать после проверки. Однако возврат старых JS-файлов не отменяет уже выполненную миграцию документов в базе. План отката должен учитывать данные и совместимость renderer. Для небольшой интеграции полезнее заранее сохранить резервную копию и тестовый набор, чем пытаться восстановить формат по жалобам пользователей.
Что проверяют исполняемые тесты проекта
В архиве находятся 20 тестов настоящего Lexical в headless-режиме Node. Они проверяют форматы текста, заголовок и цитату, три вида списка, ссылку, историю, JSON-цикл, Markdown и подготовку payload. Отдельный опыт не позволяет восстановить выделение со старыми ключами после замены документа. Отрицательные случаи подтверждают отказ при повреждённом JSON, опасном URL, неизвестном узле, лишнем CSS, превышении размеров и недоступном локальном хранилище.
Скрипт capture дополнительно выполняет девять реальных операций и сохраняет состояния, текст, Markdown и payload. Вместе с ними записываются версии среды и SHA исходников и публичных ресурсов. Это позволяет сравнить результаты двух платформ и понять, к каким именно файлам относятся проверки.
Headless не рисует интерфейс и не управляет системным выделением. Поэтому тесты документа дополняются отдельной браузерной приёмкой: редактирование, кнопки, readonly, отмена, сохранение черновика, импорт, экспорт, отказ загрузки исходников и узкая раскладка. Успешный npm test не подменяет проверку страницы после публикации.
npm test
npm run build
npm run capture
Как перенести мастерскую в свой продукт
Начните с одной завершённой задачи: заметка в карточке клиента или короткая инструкция. Оставьте только нужные типы блоков, подпишите действия словами и определите формат сохранения. Затем подключите настоящую серверную проверку и явно покажите состояние сохранения. Только после этого расширяйте редактор изображениями, таблицами или совместной работой.
Отделите библиотечную часть от прикладного контракта. В нашем проекте editor.mjs отвечает за Lexical, contract.mjs — за ограничения и данные, app.mjs — за конкретный интерфейс. Такой разрез помогает заменить внешний вид, добавить API и протестировать правила, не превращая один большой обработчик кнопки в единственное место хранения всей логики.
Исходники доступны по MIT вместе с лицензиями зависимостей. Для дальнейшей работы используйте каталог расширений, headless-пакет и описание сериализации. Практическая цель — редактор, в котором человек понимает, что изменено, где сохранено и как восстановить результат, а разработчик может проверить эти обещания.


