Comandos y mapas de teclas

Los comandos de usuario son comandos con dos puntos que expone su plugin, como :Format o :Telescope. Deben comenzar por una letra mayúscula.

nvim_create_user_command los define en Lua y recibe un nombre, una devolución de llamada o una cadena, y una tabla de opciones. Esto sustituye a :command de Vimscript.

Establezca nargs para aceptar argumentos: '0', '1', '*', '?' o '+'. La devolución de llamada recibe una tabla opts con args, fargs y bang.

fargs es la lista de argumentos ya separada por espacios en blanco, que normalmente es lo que necesita.

Pase range = true para aceptar rangos de líneas; la devolución de llamada leerá entonces opts.line1 y opts.line2. Añada bang = true para permitir :Cmd!, que se detecta mediante opts.bang.

Estas opciones permiten que un mismo comando se comporte de forma diferente para selecciones visuales o variantes forzadas.

Ofrezca autocompletado mediante la opción complete. Use opciones integradas como 'file' o 'buffer', o una función personalizada de Lua.

Una función de autocompletado personalizada recibe el argumento parcial y la línea de comandos, y devuelve una lista de cadenas candidatas.

Para limitar un comando a un solo búfer, use nvim_buf_create_user_command con el identificador del búfer. Esto es habitual en los plugins de tipo de archivo.

Por ejemplo, un plugin de Markdown podría definir :Preview únicamente dentro de los búferes de Markdown, manteniendo limpio el espacio de nombres global.

vim.keymap.set es la API moderna de mapeos. Recibe un modo, las teclas del lado izquierdo, una cadena o función de Lua para el lado derecho y una tabla de opciones.

A diferencia del antiguo nvim_set_keymap, acepta directamente una devolución de llamada de Lua como lado derecho; no hace falta envolverla en <cmd>lua.

El argumento de modo puede ser una sola cadena, como 'n', o una tabla, como { 'n', 'v' }, para asignar varios modos a la vez.

Modos comunes: n normal, i inserción, v visual, x solo visual y t terminal. Una cadena vacía '' significa normal, visual y espera de operador.

La tabla opts controla el comportamiento. silent = true suprime el eco del comando, noremap es true de forma predeterminada por seguridad, y buffer = 0 limita el mapeo al búfer actual.

Añada siempre un desc para que which-key y la salida de :map sigan siendo legibles.

Con expr = true, la función del lado derecho devuelve las teclas que se introducirán. Esto permite crear mapeos inteligentes, como hacer que <Tab> se comporte de forma diferente cuando hay un menú de autocompletado visible.

Devuelva una cadena vacía para no hacer nada o las teclas literales que se deben insertar.

Elimine un mapeo con vim.keymap.del, pasando el mismo modo y las mismas teclas, además de un campo buffer si era local al búfer.

Esto resulta útil en rutinas de limpieza o cuando un plugin desactiva una función y debe restaurar las asignaciones originales del usuario.

Una práctica clara consiste en definir la lógica una sola vez, exponerla como un comando de usuario y vincular una tecla que invoque ese comando. Así se mantiene una única fuente de verdad.

Asignar <cmd>Hello<cr> evita salir del modo visual y resulta más predecible que :Hello<cr>.

Compruebe cuánto domina los comandos y los mapeos de teclas.

Ahora puede crear comandos con nvim_create_user_command, controlarlos mediante nargs, range, bang y complete, y limitar su ámbito a cada búfer.

Para los mapeos, vim.keymap.set acepta devoluciones de llamada de Lua, varios modos y opciones como desc, silent, buffer y expr, mientras que vim.keymap.del permite limpiarlos.