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 with offset
editor.caret.setToFirstBlock('end', 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 внутри целевого поля ввода.

Ошибки

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

    (no error thrown — the call returns false)

    Проверяйте булево значение результата — setToBlock() никогда не выбрасывает ошибку, и false единственный признак того, что блок не найден.

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();
});