Blocks API: вставка, перенос и удаление блоков

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

await editor.blocks.clear();
// All content removed; editor keeps one empty paragraph

Отрисовать переданные JSON-данные как блоки, заменив текущий документ. Устойчив к эху: когда входящий документ структурно равен текущему сохранённому содержимому (`time`/`version` игнорируются), вызов оказывается no-op с сохранением курсора — круговому пути `data → render → onSave → setState → data` не нужна дедупликация на стороне потребителя. Принимает нестрогий формат (`LooseOutputData`); редактор делает глубокую копию данных, поэтому переданный объект никогда не мутируется и не удерживается — замороженное состояние хранилища (Redux, Immer) можно передавать напрямую.

const data = {
  blocks: [
    { id: '1', type: 'paragraph', data: { text: 'Hello World' } },
    { id: '2', type: 'header', data: { text: 'Title', level: 1 } }
  ]
};
await editor.blocks.render(data);

Отрисовать HTML-строку как блоки, преобразовав её в формат блоков.

const html = '<h1>Title</h1><p>Hello World</p>';
await editor.blocks.renderFromHTML(html);
// HTML is converted to appropriate blocks

Преобразовать Markdown-строку в блоки и отрисовать их, ЗАМЕНИВ текущий документ, — внутри вызывается `blocks.render()`. Конвертер загружается лениво при первом вызове, а OutputData, которым резолвится промис, — это отрисованный документ. `options` — это `MarkdownImportConfig` (сопоставление инструментов, переключатель GFM, расширения micromark/mdast). Для аддитивной вставки используйте `markdownToBlocks()` из отдельного подпути `@bloklabs/core/markdown` вместе с `blocks.insertMany()`.

const data = await editor.blocks.importMarkdown('# Title\n\n- one\n- two');
// The whole document is replaced; data is the rendered OutputData

Сериализовать текущий документ в Markdown — исходящий близнец `importMarkdown`. Блоки читаются через Saver, поэтому вывод отражает сохранённый (провалидированный) документ, а не сырой DOM, и промис резолвится в '', когда сохранять нечего. Блоки, принадлежащие ячейке таблицы, сериализуются внутри pipe-таблицы, а не повторяются как отдельные строки. То, что Markdown выразить не может, деградирует: `colspan`/`rowspan` таблицы и столбцы заголовков отбрасываются, а таблица без строки заголовков получает пустую строку заголовка, поскольку GFM её требует.

const md = await editor.blocks.exportMarkdown();
// → '# Title\n\n- one\n- two'

Удалить блок по указанному индексу или текущий блок, если индекс не передан.

// Delete current block
await editor.blocks.delete();

// Delete block at index 0
await editor.blocks.delete(0);

// Delete without moving the user's caret (programmatic deletion)
await editor.blocks.delete(0, false);

Перемещает блок на новую позицию. Если fromIndex не передан, перемещает текущий блок.

// Move current block to top
editor.blocks.move(0);

// Move block from index 2 to index 0
editor.blocks.move(0, 2);

Получить объект BlockAPI для блока по указанному индексу.

const block = editor.blocks.getBlockByIndex(0);
if (block) {
  console.log(block.id, block.name);
}

Получить объект BlockAPI для блока с указанным ID.

const block = editor.blocks.getById('block-123');
if (block) {
  await editor.blocks.update(block.id, { text: 'New content' });
}

Получить индекс блока, который сейчас в фокусе.

const index = editor.blocks.getCurrentBlockIndex();
console.log('Current block index:', index);

Получить индекс блока по его ID.

const index = editor.blocks.getBlockIndex('block-123');
if (index !== undefined) {
  console.log('Block is at index:', index);
}

Получить объект BlockAPI для блока, который содержит переданный HTML-элемент.

document.addEventListener('click', (e) => {
  const block = editor.blocks.getBlockByElement(e.target);
  if (block) {
    console.log('Clicked on block:', block.id);
  }
});

Прокрутить страницу к блоку, выбрать его, мигнуть подсветкой прибытия и объявить переход вспомогательным технологиям — публичный аналог прокрутки по хешу URL при загрузке. No-op, когда в документе нет блока с таким id. Адаптеры фреймворков, монтирующиеся в отсоединённый холдер (React/Vue/Angular), отрисовывают засеянный контент до того, как он попадёт на страницу, поэтому загрузочная прокрутка по хешу откладывается; @bloklabs/react выполняет её автоматически, как только холдер подключается, — для глубоких ссылок вызывайте этот метод сами после готовности редактора.

editor.blocks.scrollToBlock(nodeId);

Получить все дочерние блоки родительского блока-контейнера.

const children = editor.blocks.getChildren('parent-block-id');
children.forEach(child => {
  console.log('Child:', child.id);
});

Сменить родителя блока: обновляет `parentId` блока и `contentIds` родителя через единственную в ядре точку смены родителя. Передайте `null`, чтобы вернуть блок на корневой уровень. Неизвестный `blockId` — это no-op с записью предупреждения в лог; `parentId`, который сделал бы блок потомком самого себя, выбрасывает ошибку.

// Move a block into a container block
editor.blocks.setBlockParent('child-block-id', 'parent-block-id');

// Move it back to the root level
editor.blocks.setBlockParent('child-block-id', null);

Вставить блок как дочерний для `parentId` атомарно: создание и назначение родителя объединяются в ОДИН шаг отмены, поэтому одно нажатие Cmd+Z убирает его полностью (предпочтительнее, чем `insert()` с последующей сменой родителя, где шага два). `insertIndex` — это ПЛОСКИЙ индекс документа, по которому должен появиться дочерний блок. `toolName` выбирает блочный инструмент дочернего блока и по умолчанию равен `config.defaultBlock`; инструмент, запрещённый внутри ячеек таблицы, понижается до блока по умолчанию, когда новый дочерний блок оказался бы внутри такой ячейки, а незарегистрированное имя выбрасывает ошибку до того, как что-либо будет записано. `childData` по умолчанию равен `{ text: '' }` для блока по умолчанию и `{}` — позволяя инструменту применить собственные значения по умолчанию — всякий раз, когда `toolName` называет другой инструмент.

const parentIndex = editor.blocks.getBlockIndex('parent-block-id') ?? 0;
const child = editor.blocks.insertInsideParent(
  'parent-block-id',
  parentIndex + 1,
  { text: 'Nested content' },
);

// A TYPED child in the same single undo entry — no insert-then-reparent
editor.blocks.insertInsideParent(
  'parent-block-id',
  parentIndex + 1,
  { text: 'Nested heading', level: 2 },
  'header',
);

Получить общее количество блоков в редакторе.

const count = editor.blocks.getBlocksCount();
console.log('Total blocks:', count);

Вставить новый блок с полным контролем над его свойствами и позицией.

// Insert after the current block with the default type
const block = editor.blocks.insert();
// → BlockAPI { id: 'kP3xQ...', name: 'paragraph', ... }

// Insert paragraph with data at index 0
const block = editor.blocks.insert('paragraph', { text: 'Hello' }, undefined, 0);

// Insert with custom ID
const block = editor.blocks.insert('header', { text: 'Title' }, undefined, undefined, undefined, undefined, 'custom-id');

// From your own slash menu / toolbar: declare the user gesture so a container
// tool seeds its default children (see BlockOrigin on the tool contract)
const block = editor.blocks.insert('column_list', undefined, undefined, index, undefined, undefined, undefined, undefined, 'user');

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

const blocksToInsert = [
  { id: '1', type: 'paragraph', data: { text: 'First' } },
  { id: '2', type: 'paragraph', data: { text: 'Second' } }
];
const inserted = editor.blocks.insertMany(blocksToInsert, 0);
console.log('Inserted:', inserted.length, 'blocks');

Создать пустые данные блока для указанного типа инструмента.

const emptyData = await editor.blocks.composeBlockData('paragraph');
// Returns: { text: '' } or appropriate empty state for the tool

Обновить данные и/или тюны блока. Когда инструмент блока реализует `setData(newData)` в своём прототипе — так делает каждый React/Vue/Angular-блок, а также встроенные инструменты заголовка, списка, кода, тоггла и таблицы, — обновление данных применяется НА МЕСТЕ: тот же экземпляр блока, тот же DOM-холдер, тот же смонтированный компонент продолжают жить, поэтому эфемерное состояние инструмента, принятые дочерние блоки и курсор сохраняются. Именно поэтому `update()` безопасно вызывать на каждое нажатие клавиши (переименование карточки, пока пользователь печатает). Инструменты без `setData`, инструмент, чей `setData` возвращает `false` (ему нужна другая форма DOM), и любой вызов, передающий `tunes`, откатываются к пересборке блока: новый экземпляр инструмента заменяет старый, а старый уничтожается.

// Update block data
const block = await editor.blocks.update('block-123', { text: 'New text' });

// Update with tunes
const block = await editor.blocks.update('block-123', undefined, { alignment: 'center' });

// Guard against an id that no longer exists (e.g. the block was deleted
// concurrently) instead of letting the rejection surface unhandled
try {
  await editor.blocks.update(staleId, { text: 'New text' });
} catch {
  console.warn('Block was already removed, skipping update');
}

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

// Convert paragraph to header
const headerBlock = await editor.blocks.convert('block-123', 'header', { level: 2 });

// Convert with data overrides
const headerBlock = await editor.blocks.convert('block-123', 'header', { text: 'New Title', level: 1 });

// Not every pair of tools supports conversion — guard it rather than
// assuming the target type is always convertible
try {
  await editor.blocks.convert('block-123', 'table');
} catch (error) {
  console.warn('Conversion not supported between these tools:', error);
}

Атомарно разделить блок, обновив текущий блок и вставив новый. Обе операции объединяются в один шаг отмены.

// Split a paragraph at cursor position
const newBlock = editor.blocks.splitBlock(
  'current-block-id',
  { text: 'First part' },
  'paragraph',
  { text: 'Second part' },
  1
);

Остановить наблюдение за мутациями блока по указанному индексу. Используйте это, чтобы предотвратить ложные события block-changed при операциях замены блока.

// Replace a block without triggering change events
editor.blocks.stopBlockMutationWatching(0);
// Perform block replacement...
// Mutation observer will not fire for this block

Снова включить наблюдение за мутациями блока, ранее заглушённого через `stopBlockMutationWatching`. Метод принимает **id**, а не индекс, потому что вставки и замены между двумя вызовами сдвигают индексы; несуществующий id молча пропускается — блок, заменённый на месте, был создан с собственным наблюдателем.

const blockId = editor.blocks.getBlockByIndex(0)?.id;
editor.blocks.stopBlockMutationWatching(0);
// Perform block replacement...
if (blockId) {
  editor.blocks.startBlockMutationWatching(blockId);
}

Объединить каждую операцию с блоками, выполненную внутри `fn`, в один шаг отмены. `fn` должна быть СИНХРОННОЙ — операции, попадающие туда после await, в группу уже не входят. Используйте это, чтобы структурные правки нельзя было отменить частично.

editor.blocks.transact(() => {
  editor.blocks.insert('paragraph', { text: 'One' });
  editor.blocks.insert('paragraph', { text: 'Two' });
});
// A single Cmd+Z removes both blocks

Открыть группу отмены, которая остаётся открытой через асинхронные границы. Каждая операция с блоками до `endTransaction()` попадает в один шаг отмены. Используйте это для жестов указателя, непрерывно меняющих документ (перетаскивание угла таблицы для добавления строк), где `transact()` не помогает, потому что оборачивает только синхронную функцию. Каждый вызов должен быть сопряжён с `endTransaction()`.

editor.blocks.beginTransaction();
// ... continuous mutations across async boundaries ...
editor.blocks.endTransaction();

Закрыть группу отмены, открытую через `beginTransaction()`.

editor.blocks.beginTransaction();
// ... continuous mutations across async boundaries ...
editor.blocks.endTransaction();

Выполнить операции с блоками, ничего не записывая в историю отмен. Используйте это для автопочинки и нормализации (например, чтобы в пустой ячейке всегда был блок), через которые Cmd+Z никогда не должен проходить.

editor.blocks.transactWithoutCapture(() => {
  editor.blocks.insert('paragraph', {}, undefined, 0);
});
// Nothing was added to the undo history

Сообщить ядру, что перетаскивание указателем началось или закончилось. Пока оно активно, синхронизации Yjs, запускаемые мутациями DOM, подавляются, чтобы непрерывные изменения DOM в браузере во время перетаскивания не могли испортить состояние Yjs.

editor.blocks.setPointerDragActive(true);
// ... run the drag gesture ...
editor.blocks.setPointerDragActive(false);