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, tunes, id, focus/caret, replace). `replace: true` вместе с `position`, указывающим на существующий блок, заменяет этот блок, а не вставляет рядом — программный «turn into». Возвращает созданный узел или null при отклонении (неизвестный тип инструмента, несуществующий parentId или `replace`, чья цель отсутствует). Явный уже существующий 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();

Преобразовать Markdown в блоки БЕЗ экземпляра редактора — это отдельный подпуть `@bloklabs/core/markdown`, а не метод хука. Ему не нужны ни DOM, ни смонтированный Blok, поэтому он закрывает серверный сценарий, недоступный insertMarkdown/exportMarkdown: импорт Markdown в Node-задаче, наполнение документа или предвычисление `data` до монтирования редактора. `config` — это `MarkdownImportConfig` (сопоставление инструментов, GFM, расширения). Результат готов для `blocks.render()` или `blocks.insertMany()`.

import { markdownToBlocks } from '@bloklabs/core/markdown';

// No editor instance required — this also runs on the server
const parsed = await markdownToBlocks('# Title\n\n- one\n- two');

// -> OutputBlockData[]; store it, or hand it to a live editor
await blocks.render({ blocks: parsed });

Те же блоки плюс то, что Markdown не смог в них перенести. В Blok нет блока для сырого HTML, поэтому разметка, записанная в Markdown, экранируется и сохраняется как литеральный текст — безопасно, но молча. Берите этот метод, когда импорт идёт без присмотра (инструмент MCP, агент, массовая миграция) и кому-то нужно сообщить, что изменилось. Его исходящий близнец — blocksToMarkdownWithReport в @bloklabs/core/view.

import { markdownToBlocksWithReport } from '@bloklabs/core/markdown';

const { blocks: parsed, warnings } = await markdownToBlocksWithReport(source);
// warnings: [{ construct: 'html', action: 'degraded', detail: 'HTML is escaped and stored as literal text…' }]

if (warnings.length === 0) {
  await blocks.render({ blocks: parsed });
}

Переместить блок в плоский слот: { 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);

Обновить данные и/или тюны блока по 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);

Прочитать текущие данные и тюны блока по 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);

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

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

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

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