Neovim 自动配对插件 nvim-autopairs 完全指南

Neovim 自动配对插件 nvim-autopairs 完全指南

nvim-autopairs autopairs for neovim written by lua 项目地址: https://gitcode.com/gh_mirrors/nv/nvim-autopairs

什么是 nvim-autopairs

nvim-autopairs 是一个专为 Neovim 设计的高级自动配对插件，它能够智能地处理各种括号、引号等符号的自动配对。相比传统自动配对工具，它提供了更精细的控制和更丰富的功能特性。

安装与基本配置

安装方法

根据你使用的插件管理器，选择以下任一方式进行安装：

对于 Lazy.nvim 用户：

{
    'windwp/nvim-autopairs',
    event = "InsertEnter",
    config = true
}

对于 Vim-plug 用户：

Plug 'windwp/nvim-autopairs'
lua << EOF
require("nvim-autopairs").setup {}
EOF

对于 Packer 用户：

use {
    "windwp/nvim-autopairs",
    event = "InsertEnter",
    config = function()
        require("nvim-autopairs").setup {}
    end
}

默认配置解析

nvim-autopairs 提供了丰富的配置选项，以下是主要配置项的说明：

{
    enabled = true,  -- 是否启用自动配对
    disable_filetype = { "TelescopePrompt" },  -- 在这些文件类型中禁用
    disable_in_macro = true,  -- 录制宏时禁用
    disable_in_visualblock = false,  -- 可视块模式后插入时是否禁用
    disable_in_replace_mode = true,  -- 替换模式中禁用
    ignored_next_char = "[%w%%%'%[%\"%.%`%$]",  -- 遇到这些字符时不自动配对
    enable_moveright = true,  -- 输入右括号时是否移动光标
    enable_afterquote = true,  -- 引号后是否添加括号对
    enable_check_bracket_line = true,  -- 检查同一行中是否已有配对的括号
    break_undo = true,  -- 基本规则是否中断撤销序列
    check_ts = false,  -- 是否使用 treesitter 检查
    map_cr = true,  -- 映射回车键
    map_bs = true,  -- 映射退格键
}

核心功能详解

智能回车映射

当你在花括号中间按下回车时，nvim-autopairs 会自动格式化代码：

{|}           <回车>          {
                                  |
                              }

与补全插件的集成

与 nvim-cmp 补全插件集成时，需要额外配置：

local cmp_autopairs = require('nvim-autopairs.completion.cmp')
local cmp = require('cmp')
cmp.event:on('confirm_done', cmp_autopairs.on_confirm_done())

可以进一步自定义不同文件类型的补全行为：

local handlers = require('nvim-autopairs.completion.handlers')
cmp.event:on('confirm_done', cmp_autopairs.on_confirm_done({
    filetypes = {
        ["*"] = {
            ["("] = {
                kind = {
                    cmp.lsp.CompletionItemKind.Function,
                    cmp.lsp.CompletionItemKind.Method,
                },
                handler = handlers["*"]
            }
        },
        lua = {
            ["("] = {
                kind = {
                    cmp.lsp.CompletionItemKind.Function,
                    cmp.lsp.CompletionItemKind.Method
                },
                handler = function(char, item, bufnr, rules, commit_character)
                    -- 自定义处理函数
                end
            }
        },
        tex = false  -- 在 tex 文件中禁用
    }
}))

高级规则系统

nvim-autopairs 提供了强大的规则系统，可以创建复杂的自动配对行为：

local Rule = require('nvim-autopairs.rule')
local npairs = require('nvim-autopairs')
local cond = require('nvim-autopairs.conds')

-- 添加基本规则
npairs.add_rule(Rule("$$","$$","tex"))

-- 带条件的规则
npairs.add_rules({
    Rule("$", "$",{"tex", "latex"})
        :with_pair(cond.not_after_regex("%%"))  -- 下一个字符不是%时才配对
        :with_pair(cond.not_before_regex("xxx", 3))  -- 前三个字符不是xxx时才配对
        :with_move(cond.none())  -- 不移动光标
        :with_del(cond.not_after_regex("xx"))  -- 下一个字符不是xx时才删除
        :with_cr(cond.none())  -- 不添加新行
})

Treesitter 集成

结合 Treesitter 可以实现更精确的自动配对控制：

npairs.setup({
    check_ts = true,
    ts_config = {
        lua = {'string'},  -- 在字符串节点中不添加配对
        javascript = {'template_string'},
        java = false,  -- 在 Java 中不检查 Treesitter
    }
})

local ts_conds = require('nvim-autopairs.ts-conds')
npairs.add_rules({
    Rule("%", "%", "lua")
        :with_pair(ts_conds.is_ts_node({'string','comment'})),  -- 仅在字符串或注释中添加%%
    Rule("$", "$", "lua")
        :with_pair(ts_conds.is_not_ts_node({'function'}))  -- 不在函数节点中添加$$
})

实用技巧

快速包裹功能

Fastwrap 功能可以快速为选中的文本添加括号：

npairs.setup({
    fast_wrap = {
        map = '<M-e>',  -- 快捷键
        chars = { '{', '[', '(', '"', "'" },  -- 支持的字符
        pattern = "[%'\"%>%]%)%}%,]",  -- 结束字符模式
        end_key = '$',  -- 结束键
        before_key = 'h',  -- 向前移动键
        after_key = 'l',  -- 向后移动键
        highlight = 'Search',  -- 高亮颜色
    },
})

使用示例：

(|foobar)     按 Alt+e 然后按 $     变为 (|foobar)
(|)(foobar)   按 Alt+e 然后按 q     变为 (|(foobar))

动态禁用与启用

可以在需要时动态控制插件：

require('nvim-autopairs').disable()  -- 禁用自动配对
require('nvim-autopairs').enable()   -- 启用自动配对
require('nvim-autopairs').toggle()   -- 切换状态

常见问题解决

1. 回车后缩进不正确：检查你的 Treesitter 缩进设置或安装针对该文件类型的缩进插件。

2. 在某些文件类型中不想自动配对：使用 disable_filetype 配置项：

require('nvim-autopairs').setup({
    disable_filetype = { "TelescopePrompt", "vim" },
})

3. 不想在特定字符后自动配对：调整 ignored_next_char 配置：

require('nvim-autopairs').setup({
    ignored_next_char = "[%w%.]"  -- 忽略字母数字和点符号
})

nvim-autopairs 通过其丰富的配置选项和灵活的规则系统，为 Neovim 用户提供了高度可定制的自动配对体验。无论是简单的括号配对还是复杂的上下文相关行为，都能通过适当的配置实现。

nvim-autopairs autopairs for neovim written by lua 项目地址: https://gitcode.com/gh_mirrors/nv/nvim-autopairs