Vim 插件开发指南

• 作者： wsdjeg
• LICENSE： CC BY-SA 4.0.

• 简介
• 基本语法
  • 注释
  • 变量
  • 作用域
• Vim 插件的项目结构
• Vim 自定义命令
• 推荐阅读

简介

Vim 插件开发中文指南，主要包括 Vim 脚本语法、插件开发技巧等。

基本语法

注释

在写脚本时，经常需要在源码里面添加一些注释信息，辅助阅读源码，Vim 脚本注释比较简单，是以 " 开头的，只存在行注释，不存在块注释。因此，对于多行注释，需要再每行开头添加 "。

示例：

" 这是一行注释，
let g:helloworld = 1  " 这是在行尾注释

变量

在 Vim 脚本里，可以使用关键字 let 来申明变量，最基本的方式为：

" 定义一个类型是字符串的变量 g:helloworld
let g:helloworl = "sss"

前面的例子中，是定义一个字符串，Vim 脚本中支持以下几种数据类型：

作用域

Vim 变量存在三种作用域，全局变量、局部变量、和脚本变量。通常，我们以不同的前缀来区别作用域，比如使用 g: 表示全局变量，s: 表示脚本变量。 在一些特殊情况下，前缀是可以省略的，Vim 会为该变量选择默认的作用域。不同的情况下，默认的作用域是不一样的，在函数内部，默认作用域是局部变量， 而在函数外部，默认作用域是全局变量：

let g:helloworld = 1  " 这是一个全局变量， g: 前缀未省略
let helloworld = 1    " 这也是一个全局变量，在函数外部，默认的作用域是全局的

function! HelloWorld()
  let g:helloworld = 1    " 这是函数内部全局变量
  let helloworld = 1      " 这是一个函数内部的局部变量，在函数内部，默认的作用域为局部变量
endfunction

此外，在开发 Vim 插件之前，你还需要了解 vimrc 和 Vim 插件的区别。

Vim 插件的项目结构

在开发 Vim 插件之前，需要了解一下，一个 Vim 插件项目的目录结构是怎样的，以及每一个目录里文件的意义是什么。 Vim 插件标准的目录结构为：

autoload/               自动载入脚本
colors/                 颜色主题
plugin/                 在 Vim 启动时将被载入的脚本
ftdetect/               文件类型识别脚本
syntax/                 语法高亮文件
ftplugin/               文件类型相关插件
compiler/	              编译器
indent/                 语法对齐

下面，我们来逐一说明下每一个目录的用途：

autoload/

顾名思义，该文件夹下的脚本会在特点条件下自动被载入。这里的特定条件指的是当某一个 autoload 类型的函数被调用，并且 Vim 当前环境下并未定义该函数时。 比如调用 call helloworld#init() 时，Vim 会先检测当前环境下是否定义了该函数，若没有，则在 autoload/ 目录下找 helloworld.vim 这一文件， 并将其载入，载入完成后执行 call helloworld#init().

plugin/

该目录里的文件将在 Vim 启动时被运行，作为一个优秀的 Vim 插件，应当尽量该目录下的脚本内容。通常，可以将插件的快捷键、命令的定义保留在这个文件里。

ftdetect/

ftdetect 目录里通常存放的是文件类型检测脚本，该目录下的文件也是在 Vim 启动时被载入的。在这一目录里的文件内容，通常比较简单，比如：

autocmd BufNewFile,BufRead *.helloworld set filetype=helloworld

以上脚本使得 Vim 在打开以 .helloworld 为后缀的文件时，将文件类型设置为 helloworld。通常，这个脚本的文件名是和所需要设置的文件类型一样的，上面的例子中文件的名称就是 helloworld.vim。

syntax/

这一目录下的文件，主要是定义语法高亮的。通常文件名前缀和对应的语言类型相同，比如 Java 的语法文件文件名为 java.vim。 关于如何写语法文件，将在后面详细介绍。

colors/

colors 目录下主要存储一些颜色主题脚本，当执行 :colorscheme + 主题名 命令时，对应的颜色主题脚本将被载入。比如执行 :colorscheme helloworld 时，colors/helloworld.vim 这一脚本将被载入。

compiler/

这一名录里是一些预设的编译器参数，主要给 :make 命令使用的。在最新版的 Vim 中可以使用 :compiler! 编译器名 来为当前缓冲区设定编译器。比如当执行 :compiler! helloworld 时，compiler/helloworld.vim 这一脚本将被载入。

indent/

在 indent 目录里，主要是一些语法对齐相关的脚本。

Vim 自定义命令

Vim 的自定义命令可以通过 command 命令来定义，比如：

command! -nargs=* -complete=custom,helloworld#complete HelloWorld call helloworld#test()

紧接 command 命令其后的 ! 表示强制定义该命令，即使前面已经定义过了同样名称的命令，也将其覆盖掉。 -nargs=* 表示，该命令可接受任意个数的参数， 包括 0 个。-nargs 的取值有以下几种情况：

-complete=custom,helloworld#complete 表示，改命令的补全方式采用的是自定义函数 helloworld#complete。-complete 可以接受的参数包括如下内容：

这里主要解释一些自定义的补全函数，从上面的表格可以看出，有两种定义自定义命令补全函数的方式。 -complete=custom,{func} 和 -complete=customlist,{func}。这两种区别在与函数的返回值， 前者要求是一个 string 而后者要求补全函数的返回值是 list. 自定义命令补全函数接受三个参数。

:function {func}(ArgLead, CmdLine, CursorPos)

我们以实际的例子来解释这三个参数的含义，比如在命令行是如下内容时，| 表示光标位置，我按下了 <Tab> 键调用了补全函数，那么传递给补全函数的三个参数分别是：

:HelloWorld hello|

下面，我们来看下定义的函数具体内容：

function! helloworld#complete(ArgLead, CmdLine, CursorPos) abort
    return join(['hellolily', 'hellojeky', 'hellofoo', 'world']
            \ "\n")
endfunction

在上面的函数里，返回的实际上是一个有四行的字符串，Vim 会自动根据 ArgLead 来筛选出可以用来补全的选项，并展示在状态栏上。 此时，四行里最后一个 world 因为开头不匹配 ArgLead 所以不会被展示在状态栏上，因此补全效果只有三个可选项。

-complete=customlist,{func} 这一参数所对应的补全函数，也是接受相同的三个参数，但该函数返回的是一个 list。

下面，我们来测试这个函数：

function! helloworld#complete(ArgLead, CmdLine, CursorPos) abort
    return ['hellolily', 'hellojeky', 'hellofoo', 'world']
endfunction

区别很明显，customlist 补全时不会自动根据 ArgLead 进行筛选，并且直接补全整个返回的 list，即使列表中有一个 world 完全与 ArgLead(hello) 不同， 也会将其直接覆盖。因此，当使用 customlist 时，需要在函数内根据 ArgLead 进行筛选，将函数该为如下，就可以得到相同效果了：

function! helloworld#complete(ArgLead, CmdLine, CursorPos) abort
    return filter(['hellolily', 'hellojeky', 'hellofoo', 'world'], 'v:val =~ "^" . a:ArgLead')
endfunction

• -bang 参数：

在定义 Vim 自定义命令时，可以通过 -bang 参数来申明这个命令接受感叹号。比如 :q 与 :q!。 下面是一个实例：

fu! s:hello(bang)
  if a:bang
    echom "带有叹号"
  else
    echom "不带有叹号"
  endif
endf
command! -bang Hello call s:hello(<bang>0)

在上面的实例里，函数的参数写法为 <bang>0, 当执行:Hello! 时，传递给 s:hello 这一函数的参数是 !0 即为 1，因此，此时看到打印了”带有叹号“。

其实除了写成 <bang>0, 还可以写 <bang>1, 甚至是 <bang> + 一个全局变量。比如：

let g:hello = 0
fu! s:hello(bang)
  if a:bang
    echom "带有叹号"
  else
    echom "不带有叹号"
  endif
endf
command! -bang Hello call s:hello(<bang>g:hello)

推荐阅读

• Vim 中文简明使用教程
• Vim 脚本语法指北