ФреймворкJavaScript

Класс Blok: создание и уничтожение редактора

Основной класс редактора, который инициализирует и управляет экземпляром редактора Blok.

Обновлено 30 июн. 2026 г.Редактировать на GitHub

Как получить экземпляр редактора

Методы ниже вызываются на редакторе, созданном через new Blok(). Они доступны после того, как разрешится editor.isReady.

TypeScript

// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');

Методы

save()

Promise<OutputData>

Извлекает содержимое редактора в виде JSON-данных. Основной метод для сохранения контента.

Когда использовать

Вызывайте после await editor.isReady. Возвращённый JSON — ваш источник истины: сохраните его и передайте обратно в render().

TypeScript

// Save editor content
const data = await editor.save();
console.log(data.blocks); // Array of block data

render(data)

Promise<void>

Отображает содержимое редактора из ранее сохранённых JSON-данных. Принимает нестрогий формат (`LooseOutputData`) — значения `null` для `data`, `id` или `time` блока из backend-DTO нормализуются на границе.

Когда использовать

Загружает сохранённый контент и заменяет текущий документ. Чтобы добавить, а не заменить, используйте blocks.insertMany().

TypeScript

// Load saved content
const savedData = {
  blocks: [
    { id: '1', type: 'paragraph', data: { text: 'Hello' } }
  ]
};
await editor.render(savedData);

focus(atEnd?)

boolean

Устанавливает фокус на редактор. Опционально позиционирует курсор в конце содержимого.

Когда использовать

Передайте true, чтобы поставить курсор в самый конец. Для конкретного блока или смещения используйте API caret.

TypeScript

// Focus at start
editor.focus();

// Focus at end
editor.focus(true);

clear()

Promise<void>

Удаляет все блоки из редактора.

Когда использовать

Удаляет все блоки и оставляет один пустой параграф. Действие отменяемо — в отличие от destroy(), уничтожающего экземпляр.

TypeScript

// Clear all content
await editor.clear();

destroy()

void

Уничтожает экземпляр редактора и удаляет все DOM-элементы и обработчики событий.

Когда использовать

Вызывайте из хука размонтирования вашего фреймворка, чтобы не утекли слушатели. После этого экземпляр непригоден — создайте новый Blok.

TypeScript

// Clean up on component unmount
editor.destroy();

whenAllReady(options?)

Promise<void>

Статический метод — резолвится, когда каждый экземпляр Blok в заданной области завершил загрузку (его `isReady` завершился; отклонения тоже считаются завершением). Коллективный сигнал готовности для страниц с несколькими экземплярами — заменяет ручную агрегацию колбэков `onReady` по каждому экземпляру. Передайте `within` (Element), чтобы учитывать только экземпляры внутри вашего поддерева: посторонний редактор на странице больше не сможет держать проверку закрытой. Передайте `settleOn: 'rendered'`, чтобы готовность означала не завершение конструктора, а наличие контента в DOM — это покрывает и повторные рендеры через `render(data)`. Пустая область резолвится сразу. Экземпляры, созданные пока промис в ожидании, продлевают ожидание; созданные после его резолва не учитываются — вызовите метод снова или используйте `subscribeReady()` для живого сигнала.

Когда использовать

Вызывайте как Blok.whenAllReady() на классе, а не на экземпляре. Экземпляр, который ещё загружается и чья обёртка не добавлена в документ, учитывается в любой области — лишнее ожидание безопасно, недостаточное является ошибкой.

TypeScript

// A comments list: N read-only bodies + a composer.
// Wait only for the editors inside this list.
await Blok.whenAllReady({
  within: listElement,
  settleOn: 'rendered',
});
composer.focus();

readyState(options?)

{ total: number; pending: number; ready: boolean }

Статический метод — синхронный снимок готовности для области: сколько экземпляров попадает в `within`, сколько из них ещё не готовы на запрошенном уровне `settleOn` и готова ли область целиком. Пустая область возвращает `ready: true`, поэтому отдельная проверка «ждать нечего» не нужна.

Когда использовать

Достаточно дёшев, чтобы вызывать его на каждое уведомление из subscribeReady(): метод обходит зарегистрированные экземпляры и проверяет вложенность в DOM.

TypeScript

const { pending, ready } = Blok.readyState({ within: listElement });

if (!ready) {
  showSkeleton(pending);
}

subscribeReady(listener)

() => void

Статический метод — подписка на изменения готовности всех экземпляров (создание, загрузка, смена состояния рендера, уничтожение); возвращает функцию отписки. Слушатель вызывается без аргументов: перечитайте `Blok.readyState(scope)`, когда он сработает. Подходит для `useSyncExternalStore` и других адаптеров хранилищ — живой сигнал вместо одноразовой защёлки.

Когда использовать

В фреймворках лучше использовать обёртки адаптеров: useBlokReady() в @bloklabs/react и @bloklabs/vue, injectBlokReady() в @bloklabs/angular — они оборачивают эту подписку и поиск области видимости.

TypeScript

const unsubscribe = Blok.subscribeReady(() => {
  setReady(Blok.readyState({ within: listElement }).ready);
});

// later
unsubscribe();

Свойства

Свойство	Тип	Описание
`isReady`	`Promise<Blok>`	Promise, который разрешается готовым экземпляром редактора
`isRendered`	`boolean`	Синхронный флаг готовности рендера — true, когда текущая партия рендера попала в DOM (отражает атрибут `data-blok-rendered` на обёртке); false до первого рендера и во время повторного. Дополняет асинхронные `isReady`/`onReady`: не нужны await или колбэк, состояние монтирования можно опрашивать синхронно.
`blocks`	`Blocks`	Модуль API для работы с блоками
`caret`	`Caret`	Модуль API для управления курсором
`history`	`History`	Модуль API истории
`saver`	`Saver`	Модуль API сохранения
`toolbar`	`Toolbar`	Модуль API панели инструментов
`inlineToolbar`	`InlineToolbar`	Модуль API строчной панели