Skip to content

Справочник по миграции

Все переименования кодмода, карта CSS и совместимость по каждому тулзу.

Запустите codemod

Сначала предпросмотр, затем применение.

1ПросмотрПросмотреть изменения
npx -p @bloklabs/core migrate-from-editorjs ./src --dry-run
2ПрименитьПрименить изменения к файлам
npx -p @bloklabs/core migrate-from-editorjs ./src

Параметры

--dry-run
Предпросмотр изменений без модификации файлов
--verbose
Подробный вывод для каждого обработанного файла
--use-library-i18n
Использовать встроенные переводы Blok (69 локалей)

Что изменится

Каждое переименование, которое выполняет codemod, — до и после.

Импорты

−import EditorJS from '@editorjs/editorjs';
+import { Blok } from '@bloklabs/core';

Импорты инструментов

−import Header from '@editorjs/header';
+import { Header } from '@bloklabs/core/tools';

Типы

−import type { EditorConfig } from '@editorjs/editorjs';
+import type { BlokConfig } from '@bloklabs/core';

CSS-селекторы

−.ce-block
+[data-blok-element]

Контейнер по умолчанию

−<div id="editorjs"></div>
+<div id="blok"></div>

Data-атрибуты

−data-id
+data-blok-id

Обновите CSS

Blok заменяет классы Editor.js на data-атрибуты. Перенесите свои стили по этой таблице.

С EditorJSBlok
.codex-editor[data-blok-editor]
.ce-block[data-blok-element]
.ce-block--selected[data-blok-selected="true"]
.ce-toolbar[data-blok-toolbar]
.ce-inline-toolbar[data-blok-testid="inline-toolbar"]
.ce-toolbar__settings-btn[data-blok-settings-toggler]
.ce-popover[data-blok-popover]
data-placeholderdata-blok-placeholder

Перенесите свои инструменты

Блочные инструменты переносятся без изменений. Инлайн-инструменты возвращают MenuConfig — или оберните старый класс и обойдитесь без переписывания.

Инлайн-инструмент render() → MenuConfig

−render() { /* returns an HTMLElement button */ }
+render() { return { icon, name, onActivate, isActive }; }

Быстрый путь — wrapLegacyInlineTool

Оберните класс существующего инлайн-инструмента EditorJS вместо переработки. Обёртка отображает старый API на MenuConfig и сохраняет title, shortcut, sanitize и иконку инструмента. Без неё Blok пропускает устаревший render(), возвращающий HTMLElement, и инструмент молча исчезает.

marker: wrapLegacyInlineTool(MarkerTool)

Блочные инструменты переносятся без изменений

Blok читает те же ключи — render, save, validate, renderSettings, merge, onPaste и статические toolbox/conversionConfig. При желании добавьте setReadOnly(state) для более дешёвого переключения режима только для чтения.

Отбрасываемые поля и предупреждения о миграции

Когда миграция отбрасывает поле без эквивалента в Blok, она выводит console.warn с именем блока и поля — потеря никогда не проходит молча. Если какое-то из этих полей вам нужно, сверьтесь с таблицей до миграции.

БлокОтбрасываемые поля
quotealignment (caption автоматически переносится в следующий параграф)
imagewithBackground
linkToolmeta.site_name
list itemmeta (отбрасывается молча — без console.warn)

Проверьте контент

Совместимость зависит от инструментов, которые использует ваш контент, а не от версии Editor.js.

Работают без изменений

Эти инструменты загружают сохранённые данные как есть.

  • paragraph
  • header
  • code
  • embed
  • marker
  • inlineCode
  • audio

Мигрируются автоматически

Конвертируются на лету, кодмодом или обоими способами.

  • list
  • checklist
  • toggleList
  • callout
  • image
  • simple-image
  • linkTool
  • delimiter
  • quote
  • table
  • raw
  • warning
  • attaches

Не входят в комплект

У Blok нет эквивалента — зарегистрируйте свой инструмент или оставьте инструмент Editor.js.

  • personality
  • button

Неизвестные типы блоков отображаются как заглушки с предупреждением "Tool «name» is not found" в консоли. Их данные сохраняются — зарегистрируйте инструмент позже, и блок вернётся.