Справочник
Словарь Редактора
Термины RichTextEditor и RichTextView (@olddevs/ui/editor). В документации, ADR и
комментариях кода они пишутся с большой буквы — так видно, что слово значит ровно то, что
в таблице, а не обиходное «блок» или «метка». Одно понятие — одно слово: синоним из
соседнего редактора (плагин, сервис, нода) заводит второй смысл, и разойдутся они молча.
Новый термин Редактора попадает сюда в том же изменении, где появился.
| Термин | Значение | Не путать с |
|---|---|---|
| Редактор | RichTextEditor — поле ввода форматированного текста | Редактором кода: его в ките нет, показ кода — CodeView |
| Просмотр | RichTextView — только чтение сохранённого Документа | readOnly-режимом Редактора: тот держит движок, Просмотр — нет |
| Документ | Значение Редактора: HTML-строка, ограниченная Схемой | JSON-деревом ProseMirror — оно внутреннее и наружу не выходит |
| Схема | Белый список Блоков, Меток и атрибутов, которые Редактор принимает и отдаёт | Санитизацией на сервере — её делает потребитель (sanitizeRichText) |
| Блок | Структурный элемент Документа: абзац, заголовок, список, таблица, картинка… | Меткой |
| Метка | Строчное форматирование внутри Блока: жирный, ссылка, цвет… | Блоком |
| Атом | Блок или строчный элемент, который выделяется, переносится и удаляется целиком: картинка (подпись внутри неё правится), разделитель, мягкий перенос, упоминание. Всегда делает поле непустым | Пустым Блоком: абзац без текста — не атом и содержимым не считается |
| Текст атома | Строка, которой атом представлен в тексте Документа: её отдают getText и getSelectedText, её длина — вес атома в maxLength, ею атом выгружается в Markdown без своих правил. У картинки — текст подписи, у разделителя — пустая строка | Атрибутом Блока |
| Панель | Набор кнопок форматирования. Фиксированная — над полем, липнет при прокрутке; плавающая — над выделением | Toolbar кита — примитивом, из которого Панель собрана |
| Меню вставки | Список «Добавить» и «Превратить в»: открывается по / в тексте и по кнопке «+» | Контекстным меню браузера |
| Меню выделения | Короткая плашка над непустым выделением: «¶», частые Метки, «…», ссылка | Плавающей Панелью: у той полный набор кнопок |
| Ручка Блока | «⋮» у Блока с кареткой и её меню действий над Блоком целиком: «Добавить ›», «Формат ›», «Вверх», «Вниз», «Дублировать», «Удалить» | Панелью: та работает с выделением, а не с Блоком |
| Пункт вставки | Строка Меню вставки: вставляет Блок или превращает текущий. Один пункт виден и по /, и по «+», и в Ручке Блока | Кнопкой Панели |
| Действие над Блоком | Пункт меню Ручки Блока, который работает с Блоком целиком, например «Дублировать» | Кнопкой: та работает с выделением |
| UI-запись | Элемент интерфейса своего Инструмента, описанный данными: кнопка, Пункт вставки, Действие над Блоком или Карточка у текста. Рисует её кит в Отведённом месте; выключенный Инструмент убирает и свои записи | React-узлом в интерфейсе: произвольный React допускается только в содержимом поповера кнопки и Карточки у текста |
| Отведённое место | Одно место на поверхности, где стоят записи своих Инструментов, в порядке tools: группа Панели перед «Отменить», конец раздела Меню вставки, секция Ручки Блока перед «Удалить» | Позицией относительно встроенной кнопки: id встроенных публичным API не являются |
| Пресет | Готовый набор встроенных Инструментов: full или basic (RICH_TEXT_PRESETS). Не замороженный список: новый встроенный приходит в него minor-версией | Точным списком tools: его состав меняет только экран |
| Инструмент | Одна возможность Редактора: её Блоки и Метки, их правила в Схеме и место в интерфейсе, например table. Встроенный задаётся именем, свой — описанием | Кнопкой: выключенный Инструмент убирает и Блок из Схемы. Плагином Redactor: тот — класс поведения над DOM без Схемы |
| Свой Инструмент | Инструмент, который описывает потребитель (CustomTool): правила Схемы данными, Часть для движка и UI-записи. Передаётся в tools вперемешку с именами кита | Внутренним описанием кита: то — надмножество публичной формы для встроенных, наружу не экспортируется |
| Префикс потребителя | Начало имени всего своего — Инструмента, его Блоков, Меток и атрибутов — до подчёркивания: acme_mergeTag, data-acme_size. В именах кита подчёркивания нет, поэтому своё и встроенное не совпадают ни в наборе, ни в Документе | Пресетом: тот — набор встроенных Инструментов, а не пространство имён |
| HTML-соглашение | Форма своего в Документе: Блок — div или span с data-block, Метка — span с data-mark, атрибуты — data-<префикс>_<имя>. Заморожено: расширяется только добавлением | Тегами Схемы кита (p, table, img): свой Блок их занять не может |
| Признак Блока | Свойство Блока, которое понимает только кит, а не движок: «контейнер» (детям своя Ручка), «можно превратить в», «атом без меню форматирования» | Атрибутом Блока: тот хранится в Документе |
| Часть для движка | То в описании Инструмента, что нужно только живому Редактору: расширения Tiptap и вид узла. Подаётся сразу или Загрузчиком | Правилами Схемы: те — данные, их читают сервер и Просмотр без движка |
| Загрузчик | Функция с динамическим импортом вместо Части для движка: engine: () => import(…). Так же грузятся тяжёлые встроенные вне basic — блок кода и таблица | Предзагрузкой (modulepreload): её кит не публикует, ставит потребитель |
| Хэндл | Императивный доступ кода экрана к Редактору через ref: вставка у каретки, чтение, фокус, история | Сервисами Redactor: те — внутренности движка, а не API экрана |
| Готовность | Момент, когда движок создан и Загрузчики всех включённых Инструментов, своих и встроенных, отработали: с него методы Хэндла действуют, а не молчат. Наступает один раз за монтаж, о нём сообщает onReady | Гидратацией: после неё движок может ещё ждать Загрузчики |
| Фокус поля | Фокус внутри Редактора целиком: Документ, Панель, поповеры кита, поле HTML. Переход между ними Фокус поля не теряет; onFocus и onBlur — о нём | Фокусом Документа (focus и blur движка): клик в Панель его снимает |
| Правка автора | Изменение Документа, равное набору с клавиатуры: шаг истории, onChange после задержки, предел символов действует. Сюда же вставка, отмена и повтор из Хэндла | Заменой снаружи |
| Замена снаружи | Подмена Документа целиком (value, clear(), setMarkdown()): onChange сразу, предел символов не режет | Правкой автора |
| Скелет | Вид Редактора до Готовности: рамка поля, место Панели и Документ, очищенный Схемой, статичным HTML с ритмом Просмотра, без ввода. На сервере — рамка без Документа. Сбой Загрузчика превращает Скелет в ошибку поля с «Повторить» | Просмотром: тот — отдельный компонент только для чтения, а Скелет — состояние Редактора, которое сменяется движком. Компонентом Skeleton кита — заглушкой загрузки |
| Строка статуса | Строка внутри рамки поля под Документом: слева содержимое экрана (status: число слов, «Сохранено», соавтор), справа счётчик символов кита | Сообщением поля: строка показывает длительное состояние экрана, а не событие |
| Сообщение поля | Одно событие, привязанное к полю (showNotice): тон status (только озвучивается) или error (видимая строка под полем до следующей Правки автора). Новое заменяет прежнее | Тостом кита: тот глобален и к полю не привязан |
| Карточка у текста | Немодальная карточка под диапазоном Документа, который объявил свой Инструмент (callouts): комментарий, подсказка проверки. Открывается кареткой или щелчком, фокус остаётся в тексте | Поповером кнопки: тот открывает кнопка, а Карточку — место Документа |
| Остров | Клиентский кусок Просмотра, который после монтирования оживляет Блок в уже показанном HTML: кнопка «Копировать» у блока кода, island своего Блока | Видом узла: тот живёт только в движке Редактора |