用约定方式编写的脚本能够被除作者外的很多人使用。这样的脚本叫做插件。Vim 用户只
要把你写的脚本放在 plugin 目录下就可以立即使用了: add-plugin 。
实际上有两种插件:
全局插件: 适用于所有类型的文件。
文件类型插件: 仅适用于某种类型的文件。
这一节将介绍第一种。很多的东西也同样适用于编写文件类型插件。仅适用于编写文件类
型插件的知识将在下一节 write-filetype-plugin 做介绍。
这里我们用 Vim9 语法，编写新插件的推荐方式。请确保文件以 vim9script 命令开
始。
插 件 名
首先你得给你的插件起个名字。这个名字应该很清楚地表示该插件的用途。同时应该避免
同别的插件用同样的名字而用途不同。
一个纠正打字错误的插件可能被命名为 "typecorrect.vim"。我们将用这个名字来举例。
为了使一个插件能被所有人使用，要注意一些事项。下面我们将一步步的讲解。最后会给
出这个插件的完整示例。
插 件 体
让我们从做实际工作的插件体开始:
12 iabbrev teh the
13 iabbrev otehr other
14 iabbrev wnat want
15 iabbrev synchronisation
16 \ synchronization
1 vim9script noclear
finish 命令在第二次载入时立即退出。使用 "noclear" 参数可
以避免脚本定义的项目丢失。更多细节可见 vim9-reload 。
插 件 头
你很可能对这个插件做新的修改并很快就有了好几个版本。并且当你发布文件的时候，别
人也想知道是谁编写了这样好的插件或者给作者提点意见。所以，在你的插件头部加上一
些描述性的注释是很必要的:
2 # Vim global plugin for correcting typing mistakes
3 # Last Change: 2021 Dec 30
4 # Maintainer: Bram Moolenaar <Bram@vim.org>
5 # License: This file is placed in the public domain.
7 if exists("g:loaded_typecorrect")
8 finish
9 endif
10 g:loaded_typecorrect = 1
finish 阻止 Vim 继续读入文件的其余部分，这比用 if-endif 包围整个文件要快得
多，因为 Vim 会需要解析所有这些命令以找到 endif 。
映 射
现在让我们把这个插件变得更有趣些: 我们将加入一个映射用来校正当前光标下的单词。
我们当然可以任意选一个键组合，但是用户可能已经将其定义为其它的什么功能了。为了
使用户能够自己定义在插件中的键盘映射使用的键，我们可以使用 <Leader> 标识:
20 map <unique> <Leader>a <Plug>TypecorrAdd;
<Plug>TypecorrAdd;" 会做实际的工作，后面我们还会做更多解释。
用户可以将 "g:mapleader" 变量设为他所希望的开始插件映射的键组合。比如假设用户
这样做:
g:mapleader = "_"
注意 其中用到了 <unique>，这会使得 Vim 在映射已经存在时给出错误信息。
:map-<unique>
但是如果用户希望定义自己的键操作呢？我们可以用下面的方法来解决:
19 if !hasmapto('<Plug>TypecorrAdd;')
20 map <unique> <Leader>a <Plug>TypecorrAdd;
21 endif
<Plug>TypecorrAdd;" 的映射是否存在。仅当不存在时我们才定义映射
"<Leader>a"。这样用户就可以在他自己的 vimrc 文件中加入:
map ,c <Plug>TypecorrAdd;
28 def Add(from: string, correct: bool)
29 var to = input($"type the correction for {from}: ")
30 exe $":iabbrev {from} {to}"
...
34 enddef
<SID>。它产生一个脚本 ID。在我们的错误更正插件中我们可以做以下的定
义:
22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
...
26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
\a -> <Plug>TypecorrAdd; -> <SID>Add -> :call <SID>Add(...)
<SID>Add，该脚本将产生另一个脚本 ID。所以它定义的映
射也与前面定义的不同。
注意 在这里我们用了 <SID>Add() 而不是 Add()。这是因为该映射将被用户键入，因
此是从脚本上下文的外部调用的。<SID> 被翻译成该脚本的 ID。这样 Vim 就知道在哪个
脚本里寻找相应的 Add() 函数了。
这的确是有点复杂，但又是使多个插件一起工作所必需的。基本规则是: 在映射中使用
<SID>Add()；在其它地方 (该脚本内部，自动命令，用户命令) 使用 Add()。
我们还可以增加菜单项目来完成映射同样的功能:
24 noremenu <script> Plugin.Add\ Correction <SID>Add
注意 为了避免其它映射引起麻烦，在第 28 行使用了 ":noremap"。比如有人可能重新映
射了 ":call"。在第 24 也用到了 ":noremap"，但我们又希望重新映射 "<SID>Add"。这
就是为什么在这儿要用 "<script>"。它允许只执行局部于脚本的映射。
:map-<script> 同样的道理也适用于第 26 行的 ":noremenu"。 :menu-<script>
<SID> 和 <Plug> using-<Plug>
<SID> 和 <Plug> 都是用来避免映射的键序列和那些仅仅用于其它映射的映射起冲突。
注意 <SID> 和 <Plug> 的区别:
<Plug> 在脚本外部是可见的。它被用来定义那些用户可能定义映射的映射。<Plug> 是
无法用键盘输入的特殊代码。
使用结构: <Plug> 脚本名 映射名，可以使得其它插件使用同样次序的字符来定
义映射的几率变得非常小。
在我们上面的例子中，脚本名是 "Typecorr"，映射名是 "Add"。我们加上一个
分号作为终止符。结果是 "<Plug>TypecorrAdd;"。只有脚本名和映射名的第一
个字符是大写的，所以我们可以清楚地看到映射名从什么地方开始。
<SID> 是脚本的 ID，用来唯一的代表一个脚本。Vim 在内部将 <SID> 翻译为
"<SNR>123_"，其中 "123" 可以是任何数字。这样一个函数 "<SID>Add()" 可能
在一个脚本中被命名为 "<SNR>11_Add()"，而在另一个脚本中被命名为
"<SNR>22_Add()"。如果你用 ":function" 命令来获得系统中的函数列表你就可
以看到了。映射中对 <SID> 的翻译是完全一样的。这样你才有可能通过一个映
射来调用某个脚本中的局部函数。
用 户 命 令
现在让我们来定义一个用来添加更正的用户命令:
36 if !exists(":Correct")
37 command -nargs=1 Correct :call Add(<q-args>, false)
38 endif
verbose command Correct
17 var count = 4
...
28 def Add(from: string, correct: bool)
...
32 count += 1
33 echo "you now have " .. count .. " corrections"
34 enddef
1 vim9script noclear
2 # Vim global plugin for correcting typing mistakes
3 # Last Change: 2021 Dec 30
4 # Maintainer: Bram Moolenaar <Bram@vim.org>
5 # License: This file is placed in the public domain.
6
7 if exists("g:loaded_typecorrect")
8 finish
9 endif
10 g:loaded_typecorrect = 1
11
12 iabbrev teh the
13 iabbrev otehr other
14 iabbrev wnat want
15 iabbrev synchronisation
16 \ synchronization
17 var count = 4
18
19 if !hasmapto('<Plug>TypecorrAdd;')
20 map <unique> <Leader>a <Plug>TypecorrAdd;
21 endif
22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
23
24 noremenu <script> Plugin.Add\ Correction <SID>Add
25
26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
27
28 def Add(from: string, correct: bool)
29 var to = input("type the correction for " .. from .. ": ")
30 exe ":iabbrev " .. from .. " " .. to
31 if correct | exe "normal viws\<C-R>\" \b\e" | endif
32 count += 1
33 echo "you now have " .. count .. " corrections"
34 enddef
35
36 if !exists(":Correct")
37 command -nargs=1 Correct call Add(<q-args>, false)
38 endif
注意 虽然这个函数是被一个以 ":noremap" 定义的映射调用的，这里的
映射和缩写还是被展开使用了。
文 档 write-local-help
给你的插件写一些文档是个好主意。特别是当用户可以自定义其中的某些功能时尤为必
要。关于如何安装文档，请查阅 add-local-help 。
下面是一个插件帮助文档的简单例子，名叫 "typecorrect.txt":
1 *typecorrect.txt* Plugin for correcting typing mistakes
2
3 If you make typing mistakes, this plugin will have them corrected
4 automatically.
5
6 There are currently only a few corrections. Add your own if you like.
7
8 Mappings:
9 <Leader>a or <Plug>TypecorrAdd;
10 Add a correction for the word under the cursor.
11
12 Commands:
13 :Correct {word}
14 Add a correction for {word}.
15
16 *typecorrect-settings*
17 This plugin doesn't have any settings.
local-additions (本地附加文档) 一节中。第一个
"*" 一定要在第一行的第一列。加入你的帮助文件之后用 ":help" 来检查一下各项是否
很好的对齐了。
你可以为你的帮助文档在 ** 之间加入更多的标签。但请注意不要使用现存的帮助标签。
你最好能在标签内使用插件名用以区别，比如上例中的 "typecorrect-settings"。
建议使用 || 来引用帮助系统中的其它部分。这可以使用户很容易得找到相关联的帮助。
小 结 plugin-special
关于插件的小结:
var name 脚本的局部变量。
<SID> 脚本 ID，用于局部于脚本的映射和函数。
hasmapto() 用来检测插件定义的映射是否已经存在的函数。
<Leader> "mapleader" 的值。用户可以通过该变量定义插件所定义映射
的起始字符。
map <unique> 如果一个映射已经存在的话，给出警告信息。
noremap <script> 在映射右边仅执行脚本的局部映射，而不检查全局映射。
exists(":Cmd") 检查一个用户命令是否存在。
文件类型插件和全局插件其实很相似。但是它的选项设置和映射等仅对当前缓冲区有效。
这类插件的用法请参阅 add-filetype-plugin 。
请先阅读上面 51.1 关于全局插件的叙述。其中所讲的对文件类型插件也都适用。这
里只讲述一些不同之处。最根本的区别是文件类型插件只应该对当前缓冲区生效。
禁 用
如果你在编写一个提供很多人使用的文件类型插件，这些用户应该有机会选择不加载该插
件。你应该在插件的顶端加上:
# Only do this when not done yet for this buffer
if exists("b:did_ftplugin")
finish
endif
b:did_ftplugin = 1
vim9script
b:did_ftplugin = 1
set textwidth=70
注意 缺省的插件设置了 "b:did_ftplugin"，而此
脚本忽略之。
选 项
为了确保文件类型插件仅仅影响当前缓冲区，应该使用
setlocal
注意只设定缓冲区的局部选项 (查查有关选项的帮助)。当
:setlocal 被用于设置全局选项或者某窗口的局部选项时，会影响到多个缓冲区，这是
文件类型插件应该避免的。
当一个选项的值是多个标志位或项目的 "合" 时，考虑使用 "+=" 和 "-="，这样可以保
留现有的值。注意 用户可能已经改变了该选项的值了。通常先将选项的值复位成缺省值
再做改动是个好主意。例:
setlocal formatoptions& formatoptions+=ro
map <buffer>
if !hasmapto('<Plug>JavaImport;')
map <buffer> <unique> <LocalLeader>i <Plug>JavaImport;
endif
noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc>
<Plug>JavaImport; 的映射。如果
没有，该文件类型插件就定义缺省的映射。因为缺省映射是以 <LocalLeader> 开始，
就使得用户可以自己定义映射的起始字符。缺省的是反斜杠。
"<unique>" 的用途是当已经存在的了这样的映射或者和已经存在的映射有重叠的时候给
出错误信息。
:noremap 被用来防止其他用户定义的映射干扰。不过，":noremap <script>" 仍然可
以允许进行脚本中以 <SID> 开头的映射。
一定要给用户保留禁止一个文件类型插件内的映射而不影响其它功能的能力。下面通过
一个邮件文件类型插件来演示如何做到这一点:
# 增加映射，除非用户反对。
if !exists("g:no_plugin_maps") && !exists("g:no_mail_maps")
# Quote text by inserting "> "
if !hasmapto('<Plug>MailQuote;')
vmap <buffer> <LocalLeader>q <Plug>MailQuote;
nmap <buffer> <LocalLeader>q <Plug>MailQuote;
endif
vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR>
nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR>
endif
command -buffer Make make %:r.s
if !exists("*Func")
def Func(arg)
...
enddef
endif
不要忘记 vim9script 命令要用 "noclear"，以免脚本再次载入时删除函数。
撤 销 undo_indent undo_ftplugin
当用户执行 ":setfiletype xyz" 时，之前的文件类型命令应该被撤销。在你的文件类型
插件中设定 b:undo_ftplugin 变量，用来撤销该插件的各种设置。例如:
b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
\ .. "| unlet b:match_ignorecase b:match_words b:match_skip"
au BufNewFile,BufRead *.foo set filetype=foofoo
<LocalLeader> "maplocalleader" 的值，用户可以通过它来自定义文件类型
插件中映射的起始字符。
map <buffer> 定义一个仅对缓冲区有效的局部映射。
noremap <script> 仅重映射脚本中以 <SID> 开始的映射。
setlocal 设定仅对当前缓冲区有效的选项。
command -buffer 定义一个仅对缓冲区有效的局部命令。
exists("*s:Func") 查看是否已经定义了某个函数。
参阅所有插件的特殊环节 plugin-special 。
编译器插件可以用来设定于某一特定编译器相关的选项。用户可以使用 :compiler 命
令来加载之。主要是用以设定 'errorformat' 及 'makeprg' 选项。
最简单的方法就是学习一个例子。下面的命令将编辑所有缺省安装的编译器插件:
next $VIMRUNTIME/compiler/*.vim
vim9script
if exists("g:current_compiler")
finish
endif
g:current_compiler = "mine"
if exists(":CompilerSet") != 2
command -nargs=* CompilerSet setlocal <args>
endif
CompilerSet errorformat& " use the default 'errorformat'
CompilerSet makeprg=nmake
Vim 用户可以在 Vim 网站上寻找脚本: http://www.vim.org。如果你实现了对别人也有
用的功能，让大家一起分享！
另一个地方是 github。但那里你需要知道怎么去找。优点是绝大多数插件管理员都从
github 获取插件。用你喜欢的搜索引擎去找找吧。
Vim 脚本应该可以用于任何系统。不过，它们不一定有 tar 或 gzip 命令。如果你想把
文件打包和/或进行压缩，建议使用 "zip" 工具。
最理想的可移植方法是让 Vim 自己给脚本打包，用 Vimball 工具。见 vimball 。
最好你能加入一行内容，实现自动更新。见 glvs-plugins 。