Comandos e mapas de teclas

Comandos do usuário são comandos precedidos por dois-pontos que o seu plugin expõe, como :Format ou :Telescope. Eles devem começar com uma letra maiúscula.

nvim_create_user_command os define em Lua, recebendo um nome, uma função de retorno ou uma cadeia de caracteres e uma tabela de opções. Isso substitui o :command do Vimscript.

Defina nargs para aceitar argumentos: '0', '1', '*', '?' ou '+'. A função de retorno recebe uma tabela opts com args, fargs e bang.

fargs é a lista de argumentos já separada pelos espaços em branco, que normalmente é o que você deseja.

Passe range = true para aceitar intervalos de linhas; a função de retorno então lê opts.line1 e opts.line2. Adicione bang = true para permitir :Cmd!, detectado por meio de opts.bang.

Esses sinalizadores permitem que um comando se comporte de maneiras diferentes para seleções visuais ou variantes forçadas.

Forneça conclusão por tabulação com a opção complete. Use opções integradas como 'file' ou 'buffer', ou uma função Lua personalizada.

Uma função personalizada de conclusão recebe o argumento parcial e a linha de comando e retorna uma lista de cadeias de caracteres candidatas.

Para limitar um comando a um único buffer, use nvim_buf_create_user_command com o identificador do buffer. Isso é comum em plugins de tipo de arquivo.

Por exemplo, um plugin de Markdown pode definir :Preview somente dentro de buffers Markdown, mantendo limpo o espaço de nomes global.

vim.keymap.set é a API moderna de mapeamento. Ela recebe um modo, as teclas do lado esquerdo, uma cadeia de caracteres ou função Lua do lado direito e uma tabela de opções.

Ao contrário do antigo nvim_set_keymap, ela aceita diretamente uma função de retorno Lua no lado direito, sem necessidade de envolver o código em <cmd>lua.

O argumento de modo pode ser uma única cadeia de caracteres, como 'n', ou uma tabela, como { 'n', 'v' }, para mapear vários modos de uma só vez.

Modos comuns: n normal, i inserção, v visual, x somente visual, t terminal. Uma cadeia vazia '' significa normal, visual e pendente de operador.

A tabela opts controla o comportamento. silent = true suprime o eco do comando, noremap é true por padrão para maior segurança e buffer = 0 limita o mapeamento ao buffer atual.

Sempre adicione um desc para que a saída de which-key e de :map continue legível.

Com expr = true, a função do lado direito retorna as teclas a serem inseridas. Isso permite mapeamentos inteligentes, como fazer <Tab> se comportar de maneira diferente quando um menu de conclusão está visível.

Retorne uma cadeia vazia para não fazer nada ou as teclas literais a serem inseridas.

Remova um mapeamento com vim.keymap.del, passando o mesmo modo e as mesmas teclas, além de um campo buffer se ele for específico do buffer.

Isso é útil em rotinas de limpeza ou quando um plugin desativa uma funcionalidade e precisa restaurar os mapeamentos originais do usuário.

Um padrão organizado é definir a lógica uma vez, expô-la como um comando do usuário e associar a ele uma tecla que o chame. Assim, você mantém uma única fonte de verdade.

Mapear para <cmd>Hello<cr> evita sair do modo visual e é mais previsível do que :Hello<cr>.

Verifique sua compreensão dos comandos e dos mapeamentos de teclas.

Agora você pode criar comandos com nvim_create_user_command, controlá-los por meio de nargs, range, bang e complete e limitar o escopo deles por buffer.

Para mapeamentos, vim.keymap.set aceita funções de retorno Lua, vários modos e opções como desc, silent, buffer e expr, enquanto vim.keymap.del permite fazer a limpeza.