127 lines
6.4 KiB
Markdown
127 lines
6.4 KiB
Markdown
# Привязки клавиш — `api.keymap`
|
||
|
||
Привязки живут у трёх видов объектов:
|
||
|
||
- у приложения — `api.keymap` (глобальные привязки);
|
||
- у редактора — `api.editor` (срабатывают, когда фокус в редакторе);
|
||
- у каждого блока панели — `tree` (срабатывают, когда фокус на этом блоке).
|
||
|
||
Встроенные сочетания можно заменить или удалить: обработчиком принимается
|
||
Lua-функция, имя встроенной команды или `nil`.
|
||
|
||
```lua
|
||
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()`.
|
||
Режимы у приложения, редактора и каждого блока независимы.
|
||
|
||
```lua
|
||
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`
|
||
→ команды слоя автодополнения.
|
||
|
||
## Примеры
|
||
|
||
```lua
|
||
-- Переопределить сохранение своей функцией во всех режимах.
|
||
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+↑` продолжает
|
||
выделять текст.
|