Skip to content
ФреймворкJavaScript

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

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

Редактировать на 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

Set caret to the first block with optional position and offset.

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

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

Set caret to the last block with optional position and offset.

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

Часто после добавления контента — ставит курсор в конец нового последнего блока через '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

Move caret to the previous block.

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

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

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

caret.setToNextBlock(position?, offset?)

boolean

Move caret to the next block.

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

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

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

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

boolean

Set caret to a specific block by BlockAPI, ID, or index.

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

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

Параметры

ПараметрТипОбязательныйПо умолчаниюОписание
blockOrIdOrIndexBlockAPI | string | numberОбязательный—Целевой блок: экземпляр BlockAPI, id блока или числовой индекс.
position'start' | 'end' | 'default'—'default'Куда внутри блока поставить курсор.
offsetnumber—0Абсолютное смещение в символах от начала текущего поля ввода блока. Учитывается, только когда position равен 'default' — 'start' и 'end' ставят каретку на границу и игнорируют его.

Ошибки

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

    (no error thrown — the call returns false)

    Для 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

Set focus to the editor, optionally at the end of content.

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

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

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

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

caret.updateLastCaretAfterPosition()

void

Update the "after" position of the most recent caret undo entry. Use after async caret movements.

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

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

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