useBlocks(): работа с блоками из React

Блок с данным id как снимок-узел, или null для неизвестного id.

const node = blocks.getById('x9k2f1');
// → { id: 'x9k2f1', type: 'paragraph', parentId: null, contentIds: [] }

Прямые дети родительского блока в порядке документа. Передайте null для корневых блоков.

const rootBlocks = blocks.getChildren(null);
const rowBlocks = blocks.getChildren(databaseBlockId);

Вставить один блок (type, data, parentId, position, focus/caret). Возвращает созданный узел или null при отклонении (неизвестный инструмент, несуществующий parentId). Явный уже существующий id — insert-if-absent. Атомарно — один шаг отмены.

const node = blocks.insert({
  type: 'header',
  data: { text: 'New section', level: 2 },
  position: 'end',
  focus: true,
});
// → node.id is the new block's id (or null if rejected)

Вставить несколько блоков атомарно, в порядке массива, ОДНИМ шагом отмены. Неудачные спецификации отбрасываются; возвращаются успешно созданные узлы.

const nodes = blocks.insertMany([
  { type: 'header', data: { text: 'Title' } },
  { type: 'paragraph', data: { text: 'Body' } },
]);

Вставить готовое ВЛОЖЕННОЕ поддерево одной атомарной операцией. Дети вставляются под свой узел рекурсивно; параметры размещения применяются только к корню. Возвращает корневой узел или null при отклонённом/конфликтующем id.

const root = blocks.insertTree({
  type: 'toggle',
  data: { text: 'Details' },
  children: [
    { type: 'paragraph', data: { text: 'Hidden content' } },
  ],
});

Преобразовать Markdown-строку в блоки и вставить их АДДИТИВНО (без очистки документа). Асинхронно — конвертер загружается лениво. Возвращает все созданные узлы в порядке документа; пустой ввод или несуществующий parentId возвращает [].

const nodes = await blocks.insertMarkdown(
  '# Title\n\n- one\n- two',
  { position: 'end' },
);

Сериализовать ВЕСЬ документ в Markdown (асинхронно, ленивый сериализатор). Структура, невыразимая в Markdown (например, объединённые ячейки таблиц), отбрасывается.

const md = await blocks.exportMarkdown();

Переместить блок в плоский слот: { before }, { after } или { toIndex }. Блок принимает родителя места назначения — используйте nest/unnest, чтобы сменить родителя без выбора соседнего слота.

blocks.move(nodeId, { after: otherId });
blocks.move(nodeId, { toIndex: 0 });

Сделать блок ребёнком другого блока.

blocks.nest(childId, toggleId);

Поднять вложенный блок на уровень выше (из его родителя).

blocks.unnest(childId);

Удалить блок (и его поддерево).

blocks.remove(nodeId);

Обновить data и/или tunes блока по id. Делегирует асинхронному blocks.update ядра (собственный шаг отмены); неизвестные id — тихий no-op.

blocks.update(nodeId, { text: 'Edited' });

Преобразовать блок в другой тип («turn into»). Оба инструмента должны определять conversionConfig; непреобразуемый блок — корректный no-op. options.caret ставит каретку в преобразованный блок.

blocks.convert(nodeId, 'header', { level: 2 });

Выполнить несколько мутаций как ОДИН атомарный шаг отмены.

blocks.transact(() => {
  blocks.remove(oldId);
  blocks.insert({ type: 'paragraph', data: { text: 'Replacement' } });
});

Как transact, но операция НЕ попадает в историю отмены — для тихой авто-починки/нормализации, через которую CMD+Z не должен проходить.

blocks.transactWithoutCapture(() => {
  blocks.update(nodeId, { text: normalized });
});

Атомарно разделить блок: обновить текущий блок и вставить новый по абсолютному плоскому индексу — ОДНИМ шагом отмены.

const newNode = blocks.splitBlock(
  nodeId, { text: 'First half' },
  'paragraph', { text: 'Second half' },
  blocks.getBlockIndex(nodeId)! + 1,
);

Вставить одного ребёнка под родителя по плоскому индексу атомарно (создание И назначение родителя ОДНИМ шагом отмены) — предпочтительнее insert() + nest(), которые дают два шага.

const child = blocks.insertInsideParent(toggleId, 3);

Вставить плоский массив уже сериализованных OutputBlockData (форма save()) напрямую, с учётом связей parent/content. Один атомарный шаг отмены.

const nodes = blocks.insertOutputData(savedFragment.blocks);

Заменить ВЕСЬ документ блоками из сохранённых OutputData — примитив ЗАГРУЗКИ документа, который сначала очищает содержимое (в отличие от аддитивных вставок).

await blocks.render(savedData);

Заменить ВЕСЬ документ блоками, разобранными из HTML-строки (сначала очищает содержимое).

await blocks.renderFromHTML('<h1>Imported</h1><p>Body</p>');

Удалить все блоки из документа.

await blocks.clear();

Текущее количество блоков (реактивно).

const count = blocks.getBlocksCount();

Плоский индекс блока с кареткой, или -1, если каретки нет.

const index = blocks.getCurrentBlockIndex();

Блок по плоскому индексу как снимок-узел, или null.

const first = blocks.getBlockByIndex(0);

Абсолютный плоский индекс блока по id, или null для неизвестного.

const index = blocks.getBlockIndex(nodeId);

Прочитать текущие data и tunes блока по id без каких-либо мутаций — дубликат блока собирается прямо из хука: прочитать узел, затем insert({ type, data, tunes }).

const saved = blocks.getBlockData(nodeId);
if (saved) {
  blocks.insert({ type: 'paragraph', data: saved.data, position: { after: nodeId } });
}

Блок, чей holder содержит/равен DOM-элементу — сопоставляет цель события обратно с блоком.

const node = blocks.getBlockByElement(event.target as HTMLElement);

A reactive snapshot of the block tree plus a full manipulation API, from the framework adapters: the useBlocks(editor) hook in @bloklabs/react, the useBlocks(editor) composable in @bloklabs/vue, and injectBlocks() in @bloklabs/angular. Reads re-render reactively as the document changes; writers are atomic (one undo step) and safe to call before the editor is ready (they no-op). Returned BlockNode objects ({ id, type, parentId, contentIds }) are fresh-snapshot volatile — read them now, don't stash them in dep arrays.

blocks.scrollToBlock(nodeId);

Прочитать пустые данные инструмента по умолчанию без вставки. Отклоняется для неизвестного инструмента.

const defaults = await blocks.composeBlockData('header');

Идёт ли сейчас синхронизация Yjs (undo/redo) — используйте, чтобы пропустить очистку, которая конфликтовала бы с состоянием отмены.

if (!blocks.isSyncingFromYjs()) {
  blocks.update(nodeId, { text: cleaned });
}