Перейти к содержимому
Фреймворк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

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

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

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