164 lines
10 KiB
Markdown
164 lines
10 KiB
Markdown
# Редактор — `api.editor`
|
|
|
|
Группа `api.editor` управляет вкладками, текстом, gutter, подсветкой и
|
|
сохранением. LSP-серверы описаны отдельно в [lsp.md](lsp.md), привязки
|
|
клавиш редактора — в [keymap.md](keymap.md).
|
|
|
|
Номера вкладок нумеруются с нуля.
|
|
|
|
## Вкладки
|
|
|
|
| Метод | Описание |
|
|
| --- | --- |
|
|
| `api.editor:tabs()` | Список вкладок: `{{ index = 0, title = "main.rs", icon = "file" }, ...}` |
|
|
| `api.editor:active_tab()` | Индекс активной вкладки |
|
|
| `api.editor:set_active_tab(index)` | Сделать вкладку активной; `true`, если вкладка существует |
|
|
| `api.editor:next_tab()` | Переключить на следующую вкладку, вернуть индекс |
|
|
| `api.editor:previous_tab()` | Переключить на предыдущую вкладку, вернуть индекс |
|
|
| `api.editor:open_tab()` | Открыть пустую вкладку, вернуть индекс |
|
|
| `api.editor:open(path, position)` | Открыть файл с диска, вернуть индекс вкладки |
|
|
| `api.editor:close_tab(index)` | Закрыть вкладку; `true`, если вкладка закрыта |
|
|
| `api.editor:focus()` | Перевести фокус в редактор, не меняя вкладку и курсор |
|
|
|
|
Если файла нет, `open` создаёт пустой буфер с таким именем — как в vim.
|
|
Язык подсветки определяется по расширению, если для него есть грамматика.
|
|
Первый аргумент принимает и строку `"src/main.rs"`, и массив сегментов
|
|
`{ "src", "main.rs" }`.
|
|
|
|
Второй аргумент `open` необязателен:
|
|
|
|
| Значение | Поведение |
|
|
| --- | --- |
|
|
| нет аргумента / `nil` | Открыть вкладку, не трогая фокус |
|
|
| `{}` | Перевести фокус в редактор, курсор оставить на месте |
|
|
| `{line, column}` | Перевести фокус и поставить курсор (с нуля) |
|
|
|
|
```lua
|
|
api.editor:open("src/main.rs") -- открыть, не трогая фокус
|
|
api.editor:open("src/main.rs", {}) -- фокус в редактор, курсор на месте
|
|
api.editor:open("src/main.rs", {4, 2}) -- фокус в редактор, курсор на строку 4, столбец 2
|
|
```
|
|
|
|
Строка и столбец нумеруются с нуля, как в диагностике LSP; столбец считается
|
|
в UTF-16.
|
|
|
|
## Иконки вкладок
|
|
|
|
Слева от названия вкладки показывается иконка; по умолчанию это `file`.
|
|
Имя — название иконки [Lucide](https://lucide.dev/icons/), регистр не важен.
|
|
Подчёркивания и пробелы считаются дефисом, а `icons/` и `.svg` можно не
|
|
писать: `file_code`, `file-code` и `icons/file-code.svg` равнозначны.
|
|
|
|
| Метод | Описание |
|
|
| --- | --- |
|
|
| `api.editor:set_tab_icon(index, name)` | Назначить иконку вкладке; `false`, если вкладки нет или иконка неизвестна |
|
|
| `api.editor:clear_tab_icon(index)` | Вернуть иконку по умолчанию (`file`) |
|
|
| `api.editor:tab_icon(index)` | Имя иконки вкладки или `nil`, если вкладки нет |
|
|
|
|
```lua
|
|
api.editor:set_tab_icon(0, "file-code")
|
|
api.editor:set_tab_icon(1, "book-open")
|
|
api.editor:clear_tab_icon(1) -- снова "file"
|
|
```
|
|
|
|
## Иконки на полях редактора (gutter)
|
|
|
|
Слева от редактора есть узкая колонка с иконками. Методы действуют на
|
|
активную вкладку, а номера строк нумеруются с нуля, как в LSP.
|
|
|
|
У каждой иконки есть тип (`kind`), который задаёт сценарий: например,
|
|
`diagnostics` или `breakpoint`. На строке может жить по одной иконке каждого
|
|
типа, поэтому диагностика и другие сценарии не затирают иконки друг друга.
|
|
Повторная установка иконки того же типа заменяет её. Колонка расширяется под
|
|
самую насыщенную строку, чтобы иконки разных типов не накладывались.
|
|
|
|
| Метод | Описание |
|
|
| --- | --- |
|
|
| `api.editor:set_gutter_icon(line, icon, kind[, options])` | Поставить иконку типа `kind` на строку. `options = { color = "#RRGGBB", hover_color = "#RRGGBB" }` задаёт цвет и цвет при наведении; оба необязательны. Без цвета иконка рисуется цветом темы. `false` — иконка или цвет неизвестны либо тип пуст |
|
|
| `api.editor:gutter_icon(line, kind)` | Имя иконки этого типа на строке или `nil` |
|
|
| `api.editor:gutter_color(line, kind)` | Цвет иконки или `nil`, если цвет не задан |
|
|
| `api.editor:gutter_hover_color(line, kind)` | Цвет иконки при наведении или `nil` |
|
|
| `api.editor:clear_gutter_icon(line, kind)` | Убрать иконку этого типа со строки; `false`, если её не было |
|
|
| `api.editor:clear_gutter_line(line)` | Убрать все иконки строки |
|
|
| `api.editor:clear_gutter_kind(kind)` | Убрать иконки типа во всех строках активной вкладки; возвращает число удалённых |
|
|
| `api.editor:clear_gutter()` | Убрать все иконки активной вкладки |
|
|
| `api.editor:on_gutter_click(kind, callback)` | Назначить обработчик клика по иконке типа `kind`; `callback(line, icon, kind)`. `nil` вместо функции снимает обработчик |
|
|
| `api.editor:on_gutter_shift(kind, callback)` | Назначить обработчик переноса иконки типа `kind`; `callback(kind, old_line, new_line)`. Вызывается для каждой иконки, чья строка съехала после правки текста. `nil` снимает обработчик |
|
|
|
|
```lua
|
|
api.editor:set_gutter_icon(4, "circle", "diagnostics", { color = "#e5484d" })
|
|
api.editor:set_gutter_icon(4, "play", "breakpoint") -- вторая иконка на той же строке
|
|
api.editor:set_gutter_icon(9, "play", "breakpoint", {
|
|
color = "#888888",
|
|
hover_color = "#ffffff",
|
|
})
|
|
|
|
api.editor:on_gutter_click("breakpoint", function(line, icon, kind)
|
|
print("клик", line, icon, kind)
|
|
end)
|
|
|
|
api.editor:on_gutter_shift("breakpoint", function(kind, old_line, new_line)
|
|
print("иконка уехала", kind, old_line, new_line)
|
|
end)
|
|
|
|
api.editor:clear_gutter_icon(4, "diagnostics") -- только один тип строки
|
|
api.editor:clear_gutter_kind("diagnostics") -- перерисовать только диагностику
|
|
api.editor:clear_gutter_line(4) -- все иконки строки
|
|
api.editor:clear_gutter() -- все иконки вкладки
|
|
```
|
|
|
|
Иконки привязаны к началу своей строки и едут вместе с ней: если правка
|
|
вставила или удалила строки выше иконки, она сдвигается на столько же строк.
|
|
Правка внутри строки без изменения их числа номера не меняет. Вставка ровно
|
|
в начало строки относится к её содержимому — иконка едет вместе с текстом.
|
|
Чтобы узнать о переносе, сценарий назначает `on_gutter_shift`. При прокрутке
|
|
колонка двигается вместе с редактором. Внешняя замена всего текста через
|
|
`api.editor:set_active_text` сбрасывает иконки активной вкладки: их номера
|
|
строк относятся к старому тексту.
|
|
|
|
## Текст
|
|
|
|
| Метод | Описание |
|
|
| --- | --- |
|
|
| `api.editor:active_text()` | Текст активной вкладки |
|
|
| `api.editor:set_active_text(text)` | Заменить текст активной вкладки |
|
|
|
|
## Сохранение
|
|
|
|
| Метод | Описание |
|
|
| --- | --- |
|
|
| `api.editor:save()` | Сохранить активную вкладку в её файл |
|
|
|
|
Путь считается относительно текущего рабочего каталога процесса. При успешной
|
|
записи с вкладки снимается маркер несохранённых изменений.
|
|
|
|
## Подсветка синтаксиса
|
|
|
|
Подсветка по умолчанию выключена. Поддерживаемые языки: `rust`, `go`, `js`,
|
|
`json`, `python`, `lua`, `bash`, `yaml`, `make`, `dockerfile`, `sql`,
|
|
`markdown`, `css`, `c`, `cpp`, `html`, `xml`. Для `set_language` принимаются
|
|
и короткие имена (`rs`, `golang`, `javascript`, `py`, `sh`, `yml`, `makefile`,
|
|
`md`, `c++`…).
|
|
|
|
| Метод | Описание |
|
|
| --- | --- |
|
|
| `api.editor:set_language(index, "rust")` | Включить подсветку для вкладки; `false`, если вкладки нет или язык не поддерживается |
|
|
| `api.editor:language(index)` | Язык подсветки вкладки или `nil` |
|
|
| `api.editor:clear_language(index)` | Выключить подсветку для вкладки |
|
|
|
|
```lua
|
|
api.editor:set_language(0, "rust")
|
|
```
|
|
|
|
## Привязки редактора
|
|
|
|
`api.editor:map_key`, `api.editor:set_mode` и `api.editor:mode` работают так
|
|
же, как глобальные привязки из [keymap.md](keymap.md), но срабатывают
|
|
дополнительно к глобальным и только когда фокус находится в редакторе.
|
|
|
|
```lua
|
|
api.editor:map_key("", "<A-r>", function()
|
|
api.editor:set_active_text("editor mode")
|
|
end)
|
|
```
|