API手册

Sublime API

  • View
  • Selection
  • Region
  • Edit
  • Window

  • Settings

    基类

  • EventListener

  • ApplicationCommand
  • WindowCommand
  • TextCommand

    插件示例

在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保存前修改缓冲区

    插件生命周期

在导入期间，插件不能调用API方法，除了可以调用sublime.version(), sublime.platform(), sublime.architecture()和sublime.channel()之外。

如果插件定义了模块级的方法plugin_loaded(), 会在API ready之后调用。插件也可以定义plugin_unloaded(), 在插件unloaded之前获得到通知。

线程

所有API方法都是线程安全的，不过需要注意，代码运行在次线程上时，应用的状态将会在代码运行时改变。

sublime模块

方法 返回值 描述
set_timeout(callback, delay) None 在主线程上延时调用(毫秒). 回调的顺序会按添加的顺序依次执行.
set_async_timeout(callback, delay) None 在次线程上延时调用(毫秒)。
status_message(string) None 设置状态栏消息.
error_message(string) None 显示一个error对话框.
message_dialog(string) None 显示一个message对话框.
ok_cancel_dialog(string, <ok_button>) bool
load_resource(name) String 载入指定资源。name为Packages/Default/Main.sublime-menu格式
load_binary_resource(name) bytes 载入指定资源。name需要为。name为Packages/Default/Main.sublime-menu格式.
find_resources(pattern) [String] 查找name匹配指定模式的资源.
encode_value(value, <pretty>) String 把JSON对象转换成字符串。如果pretty设置为True，返回的字符串将会包含, 换行和缩进.
decode_value(string) value 将JSON字符串解码成对象。如果字符串是非法的，会抛出ValueError
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文件的目录。
cache_path() String 返回Sublime Text保存缓存文件的路径。
get_clipboard(<size_limit>) String 返回剪贴板的内容。size_limit可以防止不必要的大数据，默认16,777,216个字符
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 控制日志输出。如果启用，所有按键都回被记录到控制台。
log_result_regex(flag) None 控制正则表达式日志。用于调试构建系统中使用的正则表达式比较有用。
version() String 返回版本号。
platform() String 返回运行的平台。"osx", "linux" 或者 "windows"。
arch() String 返回CPU架构。64/32位，"x32" or "x64"。

返回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点的右侧字符。
|insert(edit, point, string)|int|在缓冲区指定的点插入一个字符串。返回插入的字符数量；如果插入当前缓冲区的tabs返回有点区别。
|erase(edit, region)|None|从缓冲区移除region选区内容。
|replace(edit, region, string)|None|把region选区内容替换成指定的字符串。
|sel()|Selection|返回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区域的单词区域（从第一个单词的开头，到最后一个单词的末尾）。有可能会跨多个单词。
|classify(point)|int| 分类pt, 返回0个或多个下面这些标识符按位或的值：

  • CLASS_WORD_START
  • CLASS_WORD_END
  • CLASS_PUNCTUATION_START
  • CLASS_PUNCTUATION_END
  • CLASS_SUB_WORD_START
  • CLASS_SUB_WORD_END
  • CLASS_LINE_START
  • CLASS_LINE_END
  • CLASS_EMPTY_LINE
    |find_by_class(point, forward, classes, <separators>)|Region|从point开始查找下一个匹配classes的位置。如果forward为False，则向后查找。classes是sublime.CLASS_XXX标识符按位或的值。separators可以传入，用于指定哪些字符应该被当成独立的单词。
    |expand_by_class(point, classes, <separators>)|Region|扩展point到左边和右边，直到两端匹配到classes的位置。classes是sublime.CLASS_XXX标识符按位或的值。separators可以传入，用于指定哪些字符应该被当成独立的单词。
    |expand_by_class(region, classes, <separators>)|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的语法设置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. 不绘制区域。

下划线样式是唯一的，要么0个要么一个。如果使用underline，需要传入DRAW_NO_FILL和DRAW_NO_OUTLINE。

|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) 将只会返回修改了缓冲区的输入。
|change_count()|int|返回当前修改的总次数。每次修改时，exclusive都会计数。修改计数可用于判断从上一次期望计数开始是否已经改变。
|fold([regions])|bool|折叠指定区域，如果已经折叠返回False。
|fold(region)|bool|同上。
|unfold(region)|[regions]|展开对应区域的所有文本，返回展开的区域。
|unfold([regions])|[regions]|同上。
|encoding()|String|返回当前文件编码。
|set_encoding(encoding)|None|设置文件编码，文件下一次保存时生效。
|line_endings()|String|返回当前文件使用的换行符模式。
|set_line_endings(line_endings)|None|设置文件的换行符模式，下一次保存时生效。
|overwrite_status()|Bool|返回覆写状态，通常用户通过insert键来切换。
|set_overwrite_status(enabled)|None|设置覆写状态
|symbols(line_endings)|[(Region, String)]|提取所有缓冲区中定义的符号
|show_popup_menu(items, on_done, <flags>)|None| 在光标位置显示一个弹出菜单，用于选择一个列表中的元素。 on_done会调用一次，传入选择项的索引。如果弹出菜单被取消，on_done调用的时候会传入-1参数。
Items是一个字符串数组

Flags目前没有选项

sublime.Selection类

维护一组区域(Regions), 确保它们没有重叠。regions按顺序持有。
|方法|返回值|描述
|——-
|clear()|None|Removes all regions.
|add(region)|None|添加指定的region。会与已经存在的有交叉的regions合并。
|add_all(region_set)|None|添加一组regions
|subtract(region)|None|从所有的region中移除指定的region
|contains(region)|bool|如果指定的region是所有region的一个子集则返回true

sublime.Region类

代表了buffer中的一块区域。空白区域可以相等(==)。
|构造器|描述
|——-
|Region(a, b)|指定a,b创建一块区域。

属性 类型 描述
a int region区域的第一个结束位置。（译者注：结束位置是相对于整个文档的第一个开始字符而言。）
b int region区域的第二个结束位置。b可能会比a小，这样的话就相当于一个反转的区域。
xpos int 改区域的目标水平位置(target horizontal position)，如果未定义为-1。该值会影响按up和down键时的行为。
方法 返回值 描述
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点在当前区域范围内）。

Class sublime.Edit

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

Edit对象会传给TextCommands, 用户不能创建该对象。使用一个非法的Edit对象，或者来自其它view的Edit对象，将会导致引入的方法调用失败。

方法 返回值 描述
(no methods)

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 or :row:col 后缀指定打开后的位置
  • sublime.TRANSIENT. 只作预览打开文件：在修改前不会有文件tab分配
    |find_open_file(file_name)|View|在打开的文件列表中查找指定文件，并且返回对应的view,如果没有打开改文件则发挥None
    |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列表的每个跟目录）。
    |project_file_name()|String|如果有，则返回当前打开的project文件名
    |project_data()|Dictionary|返回当前window对应的project数据。内容跟.sublime-project文件的内容一致。
    |set_project_data(data)|None| 更新当前window对应的project数据。如果window有对应的.sublime-project文件，将会更新project文件， 同事window也会在内部保存这些数据。
    |run_command(string, <args>)|None|运行WindowCommand，传入指定参数。Window.run_command可以运行任何形式的命令，通过输入框来调度命令
    |show_quick_panel(items, on_done, <flags>, <selected_index>, <on_highlighted>)|None| 显示一个快速面板，用于选择一个列表中的元素。 on_done会调用一次，传入选择项的索引。如果弹出菜单被取消，on_done调用的时候会传入-1参数。.
    Items是一个字符串数组,或者一个字符串数组的二维数组，后者则会在快速面板的每一项显示成多行。

Flags 目前只有一个选项sublime.MONOSPACE_FONT

on_highlighted, 如果指定，每次快速面板上高亮的项变化时都会调用。

|show_input_panel(caption, initial_text, on_done, on_change, on_cancel)|View|显示输入面板，获取一行用户输入。on_done和on_change, 如果不为空的话，需要是接收一个参数的方法。on_cancel是一个不接受任何参数的方法。返回调用输入widget的view
|create_output_panel(name)|View|返回输出面板相对应的view,如果需要则创建它。可以运行show_panel这个window命令来显示输出面板，panel参数设置为一个"output."前缀的name。
|lookup_symbol_in_index(symbol)|[Location]|返回所有定义的符号的位置，当前project下跨文件查找。
|lookup_symbol_in_open_files(symbol)|[Location]|同上功能相似，跨当前打开的文件查找

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回调。

Module sublime_plugin

方法 返回值 描述
(no methods)

Class sublime_plugin.EventListener

注意，有许多事件是view下的buffer缓冲区触发的，而且这些方法只调用一次， view作为第一个参数。
|方法|返回值|描述
|——-
|on_new(view)|None|当创建一个新的buffer时触发。
|on_new_async(view)|None|同上，运行在一个独立的线程上，这样就不中断主应用。
|on_clone(view)|None|当从一个已存在的view复制一份时触发。
|on_clone_async(view)|None|同on_new_async原理
|on_load(view)|None|当文件载入完成时触发。
|on_load_async(view)|None|同on_new_async原理
|on_pre_close(view)|None|在一个view关闭前触发。
|on_close(view)|None|在一个view关闭时触发 (注意，同一个缓冲区还可能有其它view)。
|on_pre_save(view)|None|在一个view保存前触发。
|on_pre_save_async(view)|None|同on_new_async原理
|on_post_save(view)|None|在一个view保存后触发。
|on_post_save_async(view)|None|同on_new_async原理
|on_modified(view)|None|view被修改后触发。
|on_modified_async(view)|None|同on_new_async原理
|on_selection_modified(view)|None|view里的选区变化时触发。
|on_selection_modified_async(view)|None|同on_new_async原理
|on_activated(view)|None|一个view被激活时触发。
|on_activated_async(view)|None|同on_new_async原理
|on_deactivated(view)|None|一个view被隐藏时触发（被切换到后台）。
|on_deactivated_async(view)|None|同on_new_async原理
|on_text_command(view, command_name, args)|(new_command_name, new_args)|当一个text command触发时调用。监听者需要返回一个元祖(command, arguments) 用于重写这个command，或者不做任何修改时返回None。
|on_window_command(window, command_name, args)|(new_command_name, new_args)|当一个window command触发时调用。用法同上
|post_text_command(view, command_name, args)|None|当一个text command执行之后调用。
|post_window_command(window, command_name, args)|None|当一个window command执行之后调用。
|on_query_context(view, key, operator, operand, match_all)|bool or None| 当指定的key触发键盘绑定时调用。如果该插件知道如何响应这个上下文，应该返回一个虚假的True，如果不识别该上下文则返回None。

operator可以是下面这些值：

  • sublime.OP_EQUAL. 上下文是否与operand相等?
  • sublime.OP_NOT_EQUAL. 上下文是否与operand不相等?
  • sublime.OP_REGEX_MATCH. 上下文与operand指定的正则匹配?
  • sublime.OP_NOT_REGEX_MATCH. 上下文与operand指定的正则不匹配?
  • sublime.OP_REGEX_CONTAINS. 上下文包含与operand指定的正则相匹配的子字符串?
  • sublime.OP_NOT_REGEX_CONTAINS.上下文不包含与operand指定的正则相匹配的子字符串
    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。
is_checked(<args>) bool 如果需要在菜单项旁边显示checkbox则返回true。.sublime-menu文件必须要有checkbox属性，设置为true
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获取默认描述。

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获取默认描述。

原文:

http://feliving.github.io/Sublime-Text-3-Documentation/api_reference.html