Перейти к содержимому
ФреймворкJavaScript

Caret API: перемещение и фокус курсора

Управление позицией курсора и выделением внутри редактора.

Обновлено 8 сент. 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');

Методы

caret.setToFirstBlock(position?, offset?)

boolean

Поставить курсор в первый блок с необязательными позицией и смещением.

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

position принимает 'start'/'end'/'default'. Возвращает false, если приземляться некуда.

TypeScript
// Set to start of first block
editor.caret.setToFirstBlock('start');

// Set to end of first block
editor.caret.setToFirstBlock('end');

// Offset applies only to the 'default' position —
// 'start' and 'end' place the caret at the boundary and ignore it
editor.caret.setToFirstBlock('default', 5);

caret.setToLastBlock(position?, offset?)

boolean

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

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

Часто нужно после добавления контента. Ставит курсор в конец нового последнего блока через 'end'.

TypeScript
// Focus last block at end
editor.caret.setToLastBlock('end');

// Focus last block at start
editor.caret.setToLastBlock('start');

caret.setToPreviousBlock(position?, offset?)

boolean

Переместить курсор в предыдущий блок.

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

Перемещает относительно блока в фокусе. Возвращает false у верхнего края, поэтому используйте результат для определения границ.

TypeScript
editor.caret.setToPreviousBlock('end');
// Caret now at end of previous block

caret.setToNextBlock(position?, offset?)

boolean

Переместить курсор в следующий блок.

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

Зеркало setToPreviousBlock(). Возвращает false у нижнего края.

TypeScript
editor.caret.setToNextBlock('start');
// Caret now at start of next block

caret.setToBlock(blockOrIdOrIndex, position?, offset?)

boolean

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

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

Самый гибкий метод: цель задаётся через BlockAPI, id или индекс. Предпочитайте id/BlockAPI индексу, потому что индекс смещается при перемещении блоков.

Параметры

ПараметрТипОбязательныйПо умолчаниюОписание
blockOrIdOrIndexBlockAPI | string | numberОбязательный—

Целевой блок: экземпляр BlockAPI, id блока или числовой индекс.

position'start' | 'end' | 'default'—'default'

Куда внутри блока поставить курсор.

offsetnumber—0

Абсолютное смещение в символах от начала текущего поля ввода блока. Учитывается, только когда position равен 'default'. Значения 'start' и 'end' ставят курсор на границу и смещение игнорируют.

Ошибки

  • blockOrIdOrIndex это корректный id или индекс, который не указывает на существующий блок (неизвестный id или индекс вне диапазона).

    Для id и индекса проверяйте булево возвращаемое значение. Только ложный результат говорит, что блок не найден. Передача null вместо BlockAPI (например, непроверенного результата getById()) считается некорректным вводом и приводит к исключению, поэтому проверяйте на null перед вызовом.

TypeScript
// By index
editor.caret.setToBlock(0, 'end');
// → true if the caret moved, false if the target block doesn't exist

// By ID
editor.caret.setToBlock('block-123', 'start');

// By BlockAPI (getById can return null, so guard it)
const block = editor.blocks.getById('block-123');
if (block) {
  editor.caret.setToBlock(block);
}

caret.focus(atEnd?)

boolean

Установить фокус в редакторе, при необходимости в конце содержимого.

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

Лёгкий способ сфокусировать редактор без выбора блока. Передайте true, чтобы встать в конец. То же, что focus() верхнего уровня.

TypeScript
// Focus at start
editor.caret.focus();

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

caret.updateLastCaretAfterPosition()

void

Обновить позицию «после» у последней записи отмены для курсора. Использовать после асинхронных перемещений курсора.

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

Вызывайте после асинхронного перемещения курсора. Тогда отмена поставит курсор туда, где оказался пользователь, а не туда, где началась операция.

TypeScript
// After moving caret asynchronously
requestAnimationFrame(() => {
  editor.caret.setToBlock(0);
  editor.caret.updateLastCaretAfterPosition();
});