Sublime插件开发API手册

Sublime插件开发API手册[中文版]

本文为Sublime插件API手册的中文翻译版本，英文版地址：http://www.sublimetext.com/docs/2/api_reference.html

翻译和理解水平有限，有不当的地方欢迎指正。部分方法描述里添加了些我的的注解，但愿有助于理解方法的使用。

后期若是有更多实践经验的话再回过头来修正可能解释有误的地方，或加些注解。

 

Sublime插件开发API手册

插件示例

在sublime的插件目录下Packages/Default里有几个预置的插件，能够做为参考看看:

• Packages/Default/delete_word.py 删除光标左边或者右边的一个单词

• Packages/Default/duplicate_line.py 复制当前行

• Packages/Default/goto_line.py 提示用户输入，而后更新选择点

• Packages/Default/font.py 展现了如何使用settings

• Packages/Default/mark.py 用了add_regions() 往行头槽里插入图标

• Packages/Default/trim_trailing_whitespace.py 保存前修改缓冲区

sublime模块

方法	返回值	描述
set_timeout(callback, delay)	None	延时调用 (毫秒). 回调的顺序会按添加的顺序依次执行. 多线程调用setTimeout也是安全的.
status_message(string)	None	设置状态栏消息.
error_message(string)	None	显示一个error对话框.
message_dialog(string)	None	显示一个message对话框.
ok_cancel_dialog(string, <ok_button>)	bool	显示一个"确认/取消"的对话框。若是有"确认"按钮，点击确认返回True.
load_settings(base_name)	Settings	载入一个配置，name参数要包括文件名和后缀而不是路径。会根据base name搜索插件包，结果返回setting对象。后续调用load_settings载入同一个base_name将返回同一个对象，而不会从新从磁盘读取文件。
save_settings(base_name)	None	保存配置，写入磁盘。
windows()	[Window]	返回打开窗口的列表。
active_window()	Window	返回最近使用的一个窗口。
packages_path()	String	返回packages目录的路径.
installed_packages_path()	String	返回全部用户 *.sublime-package文件的目录。
get_clipboard()	String	返回剪贴板的内容。
set_clipboard(string)	None	设置剪贴板的内容。
score_selector(scope, selector)	Int	把选择器设置成对应的区域，返回区域值。 0标示没有选区，大于0表示有一个选区。 不一样的选择器能够经过scope来比较： scope值越高说明这段选区越适合这个选择器.
run_command(string, <args>)	None	运行ApplicationCommand，string是command名字，args是传给command的参数。
log_commands(flag)	None	控制命令的日志。若是启用，全部command从快捷键，菜单中执行都回记录到控制台。
log_input(flag)	None	控制日志输出。若是启用，全部按键都回被记录到控制台。
version()	String	返回版本号。
platform()	String	返回运行的平台。"osx", "linux" 或者 "windows"。
arch()	String	返回CPU架构。64/32位，"x32" or "x64"。

sublime.View类

view表明了text buffer(缓冲区)中的视图。注意，多个view能够引用同一段buffer, 可是它们有本身惟一的选区和几何形状。

方法	返回值	描述
id()	int	返回当前view的惟一标识ID。
buffer_id()	int	返回当前view下buffer标识的惟一ID。
file_name()	String	返回buffer关联的完整文件名，若是没有缓冲区存储在磁盘的话返回None。(buffer指缓冲区，下同)
name()	String	返回buffer指定的名称。
set_name(name)	None	设置buffer的名称。
is_loading()	bool	若是buffer还在从磁盘载入返回ture，表示还未准备好给用户使用。
is_dirty()	bool	返回是否有未保存到buffer的修改。
is_read_only()	bool	返回true，若是buffer不容许修改。
set_read_only(value)	None	设置缓冲区不可修改。
is_scratch()	bool	若是缓冲区是临时缓冲区返回True。临时缓冲区不会报告为dirty。
set_scratch(value)	None	设置buffer为临时缓冲区。
settings()	Settings	返回view的settings对象。settings对象对当前view是私有的。
window()	Window	返回持有当前view的window。
run_command(string, <args>)	None	运行指定的TextCommand，args传入参数。
size()	int	返回文件中字符总数量。
substr(region)	String	返回region选区内容字符串。
substr(point)	String	返回point点的右侧字符。
begin_edit(<command>, <args>)	Edit	建立一个edit对象，能够划定一组撤销操做，须要对应到 end_edit()标记。
end_edit(edit)	Edit	标记完成一个edit对象。（译者注：begin_edit到end_edit之间的操做能够当成一个命令分组，能够用于撤销操做。）
insert(edit, point, string)	int	在缓冲区指定的点插入一个字符串。返回插入的字符数量；若是插入当前缓冲区的tabs返回有点区别。
erase(edit, region)	None	从缓冲区移除region选区内容。
replace(edit, region, string)	None	把region选区内容替换成指定的字符串。
sel()	RegionSet	返回selection(选择)的引用。
line(point)	Region	返回point点所在的行。
line(region)	Region	返回region区域行头到行尾的一份拷贝，从行头到行尾可能跨了多行（译者注：换行显示的时候，可是中间没有换行符）。
full_line(point)	Region	同 line()，可是尾部有换行符的时候也包括了换行符。
full_line(region)	Region	同 line()， 可是尾部有换行符的时候也包括了换行符
lines(region)	[Region]	返回region区域的全部行列表 (通过排序) 。
split_by_newlines(region)	[Region]	用换行符把整个region分割成多个region区域，返回region列表。
word(point)	Region	返回包含point点的单词。
word(region)	Region	返回包含region区域的单词区域（从第一个单词的开头，到最后一个单词的末尾）。有可能会跨多个单词。
find(pattern, fromPosition, <flags>)	Region	返回匹配的第一个区域，从指定的点位置开始，没有匹配结果返回None。flags参数能够是 sublime.LITERAL, sublime.IGNORECASE, 或者2个"或运算"。
find_all(pattern, <flags>, <format>, <extractions>)	[Region]	返回全部(无重叠)的匹配区域结果。flags参数同上， 若是有format参数，全部匹配结果都会按指定格式被格式化并添加到extractions列表里。
rowcol(point)	(int, int)	计算指定点从0开始的行位置和列位置。
text_point(row, col)	int	计算指定行，列位置字符的偏移量。"col"("列")是从一行的行头开始的字符数量。
set_syntax_file(syntax_file)	None	指定语法文件。view. syntax_file文件应该是按行来定义语法名称，基于Packages/Python/Python.tmLanguage。接受当前语法可使用view.settings().get('syntax')。
extract_scope(point)	Region	返回指定点位置字符语法名称的范围。
scope_name(point)	String	返回指定点位置字符的语法名称。
score_selector(point, selector)	Int	返回包含指定点位置的选择器(selector)的数量(score)。score为0表示没有匹配, 大于0表示一个匹配，不一样的选择器能够经过scope来比较： scope值越高说明这段选区越适合这个选择器。
find_by_selector(selector)	[Regions]	返回符合指定选择器的全部区域，结果为一个列表。
show(point, <show_surrounds>)	None	滚动view到指定的点。
show(region, <show_surrounds>)	None	滚动view到指定的区域。
show(region_set, <show_surrounds>)	None	滚动view到能够显示指定的区域集。
show_at_center(point)	None	滚动到view的中心位置。
show_at_center(region)	None	滚动view到region区域的中心位置。
visible_region()	Region	返回当前view可看见的区域。
viewport_position()	Vector	返回可视区域在布局坐标中的偏移量。
set_viewport_position(vector, <animate<)	None	把可视区域滚动到指定位置。
viewport_extent()	vector	返回可视区域宽高。
layout_extent()	vector	返回文档layout的宽高。(译者注：layout区域至关于编辑器里写的代码的范围，到代码字符的最后一行和最后一列区域，下同)
text_to_layout(point)	vector	把文本位置转换成layout位置。
layout_to_text(vector)	point	layout位置转换成文本位置。
line_height()	real	返回layout的行高。
em_width()	real	范围layout的字符宽度。
add_regions(key, [regions], scope, <icon>, <flags>)	None	往view里添加这一组区域(region)。若是region已经存在，会被覆盖。 scope参数决定region绘制的颜色，必须是scope名称，好比 "comment" 或者 "string"。若是没有scope参数，region不会被写入。 icon参数,若是有的话，每一个region前面会绘制icon标记。图标的颜色跟scope参数有关。 icon名称能够是：dot、circle,、bookmark,、cross。 可选参数flags能够是下列的组合： sublime.DRAW_EMPTY. 用竖线绘制空白区域。默认根本不绘制。 sublime.HIDE_ON_MINIMAP. 在minimap不显示这些区域。 sublime.DRAW_EMPTY_AS_OVERWRITE. 用横线绘制空白区域。 sublime.DRAW_OUTLINED. 绘制区域轮廓而不是填充。 sublime.PERSISTENT. 保存区域到会话。 sublime.HIDDEN. 不绘制区域。
get_regions(key)	[regions]	返回指定key的region。
erase_regions(key)	None	移除指定key的region
set_status(key, value)	None	往view里添加状态。value值会被现实在状态栏， 以key排序，每一个状态值逗号分隔。value为空字符串将清空改key对应的状态值。
get_status(key)	String	返回key对应的状态值。
erase_status(key)	None	清空key对一个的状态值。
command_history(index, <modifying_only>)	(String,Dict,int)	返回undo/redo栈中保存的，命令名称，参数和重复次数。 Index 为0 对应最近的一次command， -1对应倒数第二次的命令，一次类推。index为正数表明redo 栈中德命令。若是undo / redo历史记录不足够多返回(None, None, 0) 。 若是modifying_only为True (默认为False) 将只会返回修改了缓冲区的输入。
fold([regions])	bool	折叠指定区域，若是已经折叠返回False。
fold(region)	bool	同上。
unfold(region)	[regions]	展开对应区域的全部文本，返回展开的区域。
unfold([regions])	[regions]	同上。
encoding()	String	返回当前文件编码。
set_encoding(encoding)	None	设置文件编码，文件下一次保存时生效。
line_endings()	String	返回当前文件使用的换行符模式。（译者注：windows系统下回返回"Windows"）
set_line_endings(line_endings)	None	设置文件的换行符模式，下一次保存时生效。

sublime.RegionSet类

维护一组区域，确保区域间没有重叠。区域的按保存的顺序持有。

方法	返回值	描述
clear()	None	移除全部区域。
add(region)	None	添加指定区域。若是已经存在与该region有交集的区域，会被合并。
add_all(region_set)	None	添加region_set里的全部区域。
subtract(region)	None	从全部region中移除指定区域。
contains(region)	bool	若是全部区域中包含指定的region返回true。

sublime.Region类

表明了buffer中的一块区域。空白区域能够相等(==)。

构造器	描述
Region(a, b)	建立一块区域。

属性	类型	描述
a	int	region区域的第一个结束位置。（译者注：结束位置是相对于整个文档的第一个开始字符而言。）
b	int	region区域的第二个结束位置。b可能会比a小，这样的话就至关于一个反转的区域。

方法	返回值	描述
begin()	int	返回a,b中较小的值。
end()	int	返回a,b中较大的值。
size()	int	返回区域的字符总数。始终 >= 0。
empty()	bool	若是begin()==end()，返回True。
cover(region)	Region	返回一个跨越当前region和指定region的一个新的区域。
intersection(region)	Region	返回当前region和指定region的交集。
intersects(region)	bool	若是this==region或者当前region和指定region都包含了一个或多个一样的位置。（译者注：其实就是判断指定的region和当前的region是否有交集）
contains(region)	bool	若是指定的region是当前region的一个子集返回True。
contains(point)	bool	若是begin() <= point <= end()返回True。（译者注：point点在当前区域范围内）。

sublime.Edit类

Edit对象没有方法，它是用于对buffer的修改进行分组。

能够经过view.begin_edit()来建立。每个begion_edit()调用都要对应一个view.end_edit()调用。一般会写在try ... finally块内。

方法	返回值	描述
(无方法)

sublime.Window类

方法	返回值	描述
id()	int	返回window的ID.
new_file()	View	建立一个文件。返回一个空的view，view的is_loaded方法返回True。
open_file(file_name, <flags>)	View	打开指定文件，并返回对应的view。若是文件已经被打开，会切换到当前当前视图。注意，文件载入是异步的，view的is_loading() 方法返回False前不能对文件进行操做。 可选参数flags能够是下列的组合： sublime.ENCODED_POSITION. 指定经过查找文件名后缀:row 或者 :row:col来定位打开文件后定位的位置。 sublime.TRANSIENT. 只做预览打开文件：在修改前不会有文件tab分配。
active_view()	View	返回当前正在编辑的view。
active_view_in_group(group)	View	返回指定组里正在编辑的view。
views()	[View]	返回window中全部打开的view。
views_in_group(group)	[View]	返回指定组里的全部view。
num_groups()	int	返回window中打开的view分组的总数。
active_group()	int	返回当前选中组的索引。
focus_group(group)	None	激活指定分组。
focus_view(view)	None	切换到指定view。
get_view_index(view)	(group, index)	返回view的分组，和在分组里的索引。若是没有返回-1。
set_view_index(view, group, index)	None	把view移动到指定分组和指定的索引位置。
folders()	[String]	返回当前打开的文件夹列表。（译者注：sublime左侧显示的folders列表的每一个跟目录）。
run_command(string, <args>)	None	运行WindowCommand，传入指定参数。
show_quick_panel(items, on_done, <flags>)	None	显示一个选择列表中某个选项的快速面板。 on_done会被调用一次，接受选中项的索引为参数。若是快速面板被取消，on_done调用的时候接收的参数为-1。 Items 能够是字符串数组，或者一个字符串数组的数组(二维字符串数组)。若是是后者，快速面板里的每一个条目会显示成多行。 Flags 只能有一个值： sublime.MONOSPACE_FONT
show_input_panel(caption, initial_text, on_done, on_change, on_cancel)	View	显示一个输入面板，收集用户的一行输入。caption是输入框的标题，on_done 和 on_change若是不为空的话须要是一个接受一个字符串的函。on_cancel 是一个无参数的函数。
get_output_panel(name)	View	返回view对应的指定名称的输出面板，若是有必要会建立。output面板能够经过运行show_panel( window command)来显示，panel 的名称会加上 "output." 前缀。

sublime.Settings类

方法	返回值	描述
get(name)	value	返回指定名称的设置。
get(name, default)	value	返回指定名称的设置，若是没有定义该设置返回默认的。
set(name, value)	None	设置某个名称的配置，只能接受原类型，列表， lists，字典。
erase(name)	None	移除某个配置。若是是继承自父配置不会被删除。
has(name)	bool	判断当前配置类中是否存在某个配置或者父配置中是否存在。
add_on_change(key, on_change)	None	注册当前配置对象的change的回调。只要有一个配置发生变化都会被回调。.
clear_on_change(key)	None	移除指定的change回调。

sublime_plugin模块

方法	返回值	描述
(无方法)

sublime_plugin.EventListener类

注意，有许多事件是view下的buffer缓冲区触发的，并且这些方法只调用一次， view做为第一个参数。

方法	返回值	描述
on_new(view)	None	当建立一个新的buffer时触发。
on_clone(view)	None	当从一个已存在的view复制一份时触发。
on_load(view)	None	当文件载入完成时触发。
on_close(view)	None	当view被关闭时触发(注意，在同一buffer中可能还有其它view)。
on_pre_save(view)	None	在一个view保存前触发。
on_post_save(view)	None	在一个view保存后触发。
on_modified(view)	None	view被修改后触发。
on_selection_modified(view)	None	view里的选区变化时触发。
on_activated(view)	None	一个view被激活时触发。
on_deactivated(view)	None	一个view被隐藏时触发（被切换到后台）。
on_query_context(view, key, operator, operand, match_all)	bool or None	当使用给定的上下文key去触发一个key绑定时触发。若是插件知道如何处理上下文能够返回True 或者 False。若是上线问是未知的，应该返回None。 operator可取下列某个值： sublime.OP_EQUAL. context等于operand sublime.OP_NOT_EQUAL. context 不等于operand sublime.OP_REGEX_MATCH. context匹配operand给定的正则 sublime.OP_NOT_REGEX_MATCH. context 不匹配operand给定的正则 sublime.OP_REGEX_CONTAINS. context包含能够匹配operand给定正则的子字符串 sublime.OP_NOT_REGEX_CONTAINS. context不包含能够匹配operand给定正则的子字符串 若是context涉及到选择(selections)应该使用match_all：是否每一个选择都须要匹配(match_all = True), 还至少要一个选择匹配 (match_all = Fals)。

sublime_plugin.ApplicationCommand类

方法	返回值	描述
run(<args>)	None	当command运行时执行。
is_enabled(<args>)	bool	若是command在当前时间可运行返回True。 默认实现都返回Flase。
is_visible(<args>)	bool	若是command在当前可显示在菜单。默认实现都返回False。
description(<args>)	String	返回command的描述。在菜单中使用，若是没有标题的状况下。返回None获取默认描述。

sublime_plugin.WindowCommand类

WindowCommands 每一个window只初始化一次。Window对象能够经过self.window来引用。

方法	返回值	描述
run(<args>)	None	command运行时调用。
is_enabled(<args>)	bool	若是command在当前时间可运行返回True。 默认实现都返回Flase。
is_visible(<args>)	bool	若是command在当前可显示在菜单。默认实现都返回False。
description(<args>)	String	返回command的描述。在菜单中使用，若是没有标题的状况下。返回None获取默认描述。

Class sublime_plugin.TextCommand

TextCommands每一个view只初始化一次。能够经过self.view放访问当前view。

方法	返回值	描述
run(edit, <args>)	None	command运行时调用。
is_enabled(<args>)	bool	若是command在当前时间可运行返回True。 默认实现都返回Flase。
is_visible(args)	bool	若是command在当前可显示在菜单。默认实现都返回False。
description(args)	String	返回command的描述。在菜单中使用，若是没有标题的状况下。返回None获取默认描述。