qode/docs/keymap.md

Привязки клавиш — api.keymap

Привязки живут у трёх видов объектов:

• у приложения — api.keymap (глобальные привязки);
• у редактора — api.editor (срабатывают, когда фокус в редакторе);
• у каждого блока панели — tree (срабатывают, когда фокус на этом блоке).

Встроенные сочетания можно заменить или удалить: обработчиком принимается Lua-функция, имя встроенной команды или nil.

api.keymap:map_key(modes, keys, handler)          -- глобальные
api.editor:map_key(modes, keys, handler)          -- только когда фокус в редакторе
api.keymap:map_completion_key(keys, handler)      -- список автодополнения

Слой автодополнения режимами не управляется: map_completion_key принимает только клавишу и обработчик.

Порядок обработки всегда такой: сначала глобальные привязки, затем — если фокус в редакторе — привязки редактора, а если фокус на блоке панели — привязки этого блока. Привязки неактивного объекта не срабатывают.

Запись клавиши

Запись	Значение
"a"	нажатие A
"1"	нажатие 1
"!a"	отпускание A
"<S-c>"	C при зажатом Shift
"<C-z>"	Z при зажатом Ctrl
"<A-!r>"	отпускание R при зажатом Alt
"<D-s>"	S при зажатом Cmd на macOS или Super на Linux

Клавиша сравнивается с именем клавиши от GPUI. Caps Lock не важен. На Linux и Windows буквы берутся по аппаратному keycode, поэтому <C-q> работает и на русской раскладке.

Режимы

У каждого объекта своя текущая режимная метка: один символ (n, i, v, r или любой другой) либо - — режим по умолчанию. Режимы динамические: заранее создавать их не нужно, достаточно переключить метку.

Значение modes	Когда срабатывает
""	во всех режимах
"-"	только в режиме по умолчанию
"niv"	в режимах n, i, v
"-iv"	в режиме по умолчанию, а также i и v

Текущий режим меняется методами set_mode(mode) и читается методом mode(). Режимы у приложения, редактора и каждого блока независимы.

api.keymap:set_mode("n")
api.editor:set_mode("i")

api.keymap:map_key("n", "<C-n>", "next_tab")       -- только в режиме n
api.editor:map_key("i", "<C-s>", "save")           -- только в режиме i редактора
api.editor:map_key("", "<C-space>", function() end) -- в любом режиме

Встроенные команды

Имя	Действие
"save"	Сохранить активную вкладку
"next_tab"	Следующая вкладка
"previous_tab"	Предыдущая вкладка
"open_tab"	Новая пустая вкладка
"close_tab"	Закрыть активную вкладку
"toggle_left_panel"	Переключить левую панель
"toggle_right_panel"	Переключить правую панель
"toggle_bottom_panel"	Переключить нижнюю панель

Встроенные команды списка автодополнения:

Имя	Действие
"completion_trigger"	Открыть список
"completion_next" / "completion_previous"	Сдвинуть выделение
"completion_page_down" / "completion_page_up"	Пролистать список
"completion_accept"	Вставить выбранный элемент
"completion_cancel"	Закрыть список
"completion_dismiss"	Закрыть список и передать клавишу редактору

При запуске уже назначены:

• Ctrl/Cmd+S → save во всех режимах;
• Ctrl/Cmd+Space → completion_trigger;
• Enter/Tab, Esc, ↑/↓, PageUp/PageDown, ←/→, Home/End → команды слоя автодополнения.

Примеры

-- Переопределить сохранение своей функцией во всех режимах.
api.keymap:map_key("", "<C-s>", function() api.editor:save() end)

-- Убрать встроенную привязку.
api.keymap:map_key("", "<C-s>", nil)

-- Назначить встроенную команду на другую клавишу.
api.keymap:map_key("", "<C-n>", "next_tab")
api.keymap:map_key("", "<C-b>", "toggle_left_panel")

-- Навигация по списку автодополнения на Ctrl+N / Ctrl+P.
api.keymap:map_completion_key("<C-n>", "completion_next")
api.keymap:map_completion_key("<C-p>", "completion_previous")

-- Привязка, которая срабатывает только при фокусе в редакторе.
api.editor:map_key("", "<A-r>", function()
  api.editor:set_active_text("editor mode")
end)

-- Привязка блока дерева: работает, когда фокус на этом дереве.
tree:map_key("v", "<A-f>", function() print("tree v") end)

Пока список автодополнения открыт, его слой проверяется раньше действий редактора. Сочетания с модификаторами и горизонтальные стрелки закрывают список, даже если для них нет своей привязки, — так Shift+↑ продолжает выделять текст.