1.4.1 API 参考
优质
小牛编辑
133浏览
2023-12-01
Sublime API
基类
示例插件
Sublime Text预置了几个插件，你可以在Default包中找到它们：
Packages/Default/delete_word.py删除光标左边或右边的一个单词。Packages/Default/duplicate_line.py重复当前行。Packages/Default/goto_line.py给用户的输入增加提示，然后更新可选列表。Packages/Default/font.py展示了如何使用设置工作。Packages/Default/mark.py用add_regions()给gutter添加一个icon。Packages/Default/trim_trailing_whitespace.py在保存之前修改缓冲区。
插件生命周期
在导入的时候，插件不能调用任何API函数，除了sublime.version()，sublime.platform()，sublime.architecture()和 sublime.channel()。
如果一个插件定义了一个模块层级的函数plugin_loaded()，当API准备被使用时将调用这个函数。插件也可以定义一个plugin_unloaded()在写在插件前得到一个通知。
线程
所有的函数都是线程安全的，但是要记住，从以一个新的线程运行代码（异步运行）的角度来看，在代码运行时，应用程序的状态会发生变化。
Module sublime
| 方法 | 返回值 | 描述 |
|---|---|---|
| set_timeout(callback, delay) | None | 在给定延时（ms）之后在主线程中执行回调函数。相同延时的回调函数将按其添加顺序执行。 |
| set_async_timeout(callback, delay) | None | 在给定延时后以一个新的线程运行回调函数。 |
| status_message(string) | None | 设置显示在状态栏的信息。 |
| error_message(string) | None | 给用户显示错误对话框。 |
| message_dialog(string) | None | 给用户显示一个消息提示框。 |
| ok_cancel_dialog(string, ) | bool | 展示一个ok / cancel对话框，如果提供了ok_title，这个文字将展示在ok按钮上。当用户按下ok按钮时，返回true。 |
| yes_no_cancel_dialog(string, , ) | Int | 展示一个yes / no / cancel对话框，yes_title和no_title分别对应于相应按钮的文字。返回sublime.DIALOG_YES、sublime.DIALOG_NO、sublime.DIALOG_CANCEL。 |
| load_resource(name) | String | 加载指定的资源，name必须采用Packages/Default/Main.sublime-menu格式。 |
| load_binary_resource(name) | bytes | 加载指定的资源，name必须采用Packages/Default/Main.sublime-menu格式。 |
| find_resources(pattern) | [String] | 找到文件名和pattern相匹配的资源。 |
| encode_value(value, ) | String | 把JSON相兼容的格式转成字符串的表现形式，如果pretty设置为true，字符串将以换行和缩进进行美化。 |
| decode_value(string) | value | 把JSON字符串转化成对象形式，如果字符串格式不合法，将抛出一个ValueError错误。 |
| expand_variables(value, variables) | value | 用定义在字典中的varialbes来扩展任何字符串value中的变量。value也可以是一个数组或字典，这种情况下，其结构将进行递归拓展。字符串应该使用代码段语法，例如：expand_variables("Hello, ${name}", {"name": "Foo"})。 |
| load_settings(base_name) | Settings | 加载指定的设置。name应该包含一个文件名和扩展名，但不是一个路径。这将搜索和base_name相匹配的包，结果将被整理到setting对象中去。随后以base_name调用load_settings将不再从磁盘加载设置，而是直接返回相同的对象。 |
| save_settings(base_name) | None | 把指定设置在内存中的改变冲刷到磁盘。 |
| windows() | [Window] | 返回所有打开的窗口列表。 |
| active_window() | Window | 返回最近使用的窗口。 |
| packages_path() | String | 返回包的基本路径。 |
| installed_packages_path() | String | 返回用户的.sublime-package文件所在路径。 |
| cache_path() | String | 返回Sublime Text存储缓存文件的路径。 |
| get_clipboard() | String | 返回剪切板中的内容。size_limit用来防止不必要的大数据，默认是16,777,216个字符。 |
| set_clipboard(string) | None | 设置剪切板的内容。 |
| score_selector(scope, selector) | Int | 用给定的作用域去匹配选择器，返回一个分值。0表示未匹配到，大于0表示有匹配项。不同的选择器可能会对同一个作用域进行比较：分值越高，表示越匹配。 |
| run_command(string, ) | None | 用指定的参数（可选）运行指定的ApplicationCommand。 |
| log_commands(flag) | None | 控制指令的日志。如果启用了，所有通过按键和菜单栏运行的指令都将记录到控制台。 |
| log_input(flag) | None | 控制输入的日志。如果启用了，所有的按键都将被记录到控制台。 |
| log_result_regex(flag) | None | 返回结果正则的日志。这对于调试构建系统中使用的正则表达式很有用。 |
| version() | String | 返回版本号。 |
| platform() | String | 返回平台类型，“osx”、“linux”或“windows”。 |
| arch() | String | 返回CPU结构，“x32”或“x64”。 |
Class sublime.View
表示一个文本缓冲的视图。注意多个视图可以引用相同的缓冲区，但是它们有独立的选择和几何结构。
| 方法 | 返回值 | 描述 | |
|---|---|---|---|
| id() | int | 返回可唯一识别视图的数值。 | |
| buffer_id() | int | 返回唯一识别视图中的缓冲区的数值。 | |
| file_name() | String | 完整的文件名，不存在则是None。 | |
| name() | String | 分配给缓冲区的名称。 | |
| set_name(name) | None | 给缓冲区设置一个名字。 | |
| is_loading() | bool | 如果缓冲区正则从磁盘中加载则返回true。 | |
| is_dirty() | bool | 如果缓冲区中有任何未保存的修改则返回true。 | |
| is_read_only() | bool | 缓冲区是否只读。 | |
| set_read_only(value) | None | 给缓冲区添加只读属性。 | |
| is_scratch() | bool | 如果一个缓冲区是从无到有的缓冲区（大概就是新建的文件）则返回true，这将不会被报告为dirty。 | |
| set_scratch(value) | None | 给缓冲区设置`scratch`属性。 | |
| settings() | Settings | 返回视图的`settings`对象的引用。`settings`对象的任何变化都属于这个视图私有。 | |
| window() | Window | 返回包含视图的窗口的引用。 | |
| run_command(string, ) | None | 以给定的参数（可选）执行`TextCommand`。 | |
| size() | int | 返回文件中的字符总数。 | |
| substr(region) | String | 以字符串形式返回`region`的内容。 | |
| substr(point) | String | 返回`point`右边的字符。 | |
| insert(edit, point, string) | int | 在缓冲区中指定的`point`处插入给定的`string`。返回插入字符串的字符数：如果tab被替换为空格，则这个结果会不同。 | |
| erase(edit, region) | None | 冲缓冲区中清除`region`的内容。 | |
| replace(edit, region, string) | None | 用给定的`string`替换`region`的内容。 | |
| sel() | 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`都是一行。 | |
| word(point) | Region | 返回包含`point`的单词。 | |
| word(region) | Region | 返回`region`的一个编辑副本，这样它以一行的开始开始，以一行的结尾为结束。注意它可能跨越好几行。 | |
| classify(point) | int | Classifies pt, returning a bitwise OR of zero or more of these flags:
| |
| find_by_class(point, forward, classes, ) | Region | 找到`point`之后与`classes`匹配的下一个位置。如果`forward`是False，则用向后搜索代替向前搜索。`classes`是一个位运算符或`sublime.CLASS_XXX`标签，`separators`用来定义什么字符应该被视为单独的词。 | |
| expand_by_class(point, classes, ) | Region | 向左或向右扩展`point`直到每一个都匹配到`classes`的位置。`classes`是一个位运算符或`sublime.CLASS_XXX`标签，`separators`用来定义什么字符应该被视为单独的词。 | |
| expand_by_class(region, classes, ) | Region | 向左或向右扩展`region`直到每一个都匹配到`classes`的位置。 | |
| find(pattern, fromPosition, ) | Region | 返回匹配到正则表达式`pattern`的第一个Region，从给定的point开始，未找到则返回None。可选的`flags`参数可以是`sublime.LITERAL`、`sublime.IGNORECASE`或两者一起。 | |
| find_all(pattern, , , ) | [Region] | 返回所有匹配到正则表达式的区域（无重叠）。可选的`flags`参数可以是`sublime.LITERAL`、`sublime.IGNORECASE`或两者一起。如果给定了`format`字符串，则所有匹配值都将被以格式化的字符串进行格式化。 | |
| rowcol(point) | (int, int) | 计算`point`的行号和列号。从0开始算。 | |
| text_point(row, col) | int | 计算给定的字符偏移量，从0开始算。 | |
| set_syntax_file(syntax_file) | None | 修改视图使用的语法。用`view.settings().get('syntax')`来恢复语法。 | |
| extract_scope(point) | Region | 返回在给定的`point`分配给该字符的语法名称的范围。 | |
| scope_name(point) | String | 返回在给定的`point`分配给该字符的语法名称。 | |
| score_selector(point, selector) | Int | 从指定位置的作用域中匹配选择器，返回一个分值。`0`表示没有匹配项，大于`0`表示有匹配。分值越大匹配度越高。 | |
| find_by_selector(selector) | [Region] | 返回匹配到指定的选择器的区域列表。 | |
| show(point, ) | None | 滚动视图到给定的`point`。 | |
| show(region, ) | None | 滚动视图到给定的`region`。 | |
| show(region_set, ) | None | 滚动视图到给定的`region_set`。 | |
| show_at_center(point) | None | 滚动视图到给定的`point`居中的位置。 | |
| show_at_center(region) | None | 滚动视图到给定的`region`居中的位置。 | |
| visible_region() | Region | 返回当前视图中的可视区域。 | |
| viewport_position() | Vector | 返回视区的偏移量。 | |
| set_viewport_position(vector, <animate<) | None | 滚动视图到指定的布局位置。 | </animate<)|
| viewport_extent() | vector | 返回视图的宽度和高度。 | |
| layout_extent() | vector | 返回布局的宽度和高度。 | |
| text_to_layout(point) | vector | 把文本位置转化成布局位置。 | |
| layout_to_text(vector) | point | 把布局位置转化成文本位置。 | |
| window_to_layout(vector) | vector | 把窗口位置转化成布局位置。 | |
| window_to_text(vector) | point | 把窗口位置转化成文本位置。 | |
| line_height() | real | 返回布局中使用的行高。 | |
| em_width() | real | 返回布局中使用的典型字符的宽度。 | |
| add_regions(key, [regions], , , ) | None | 给视图添加一组区域。如果指定的key已经存在了一组区域，则它们将被覆盖。scope用来指定画区域的颜色，它的值是一个作用域的名称，如“comment”或“string”。如果scope为空，则不会画区域。 可选的icon名称，如果指定了，将会在挨着区域的gutter处绘制一个指定的icon。这个icon将使用和scope相关联的颜色进行着色。合法的icon名称是dot、circle、bookmark、cross。icon名称也可以是一个完整的package相对路径，如Packages/Theme - Default/dot.png。 可选的falg参数：
| |
| get_regions(key) | [regions] | 返回和给定`key`相关联的区域。 | |
| erase_regions(key) | None | 删除命名区域。 | |
| set_status(key, value) | None | 给视图设置状态`key`。`value`将显示在状态栏，以逗号分隔，按`key`排序。`value`为空字符串时将清除状态。 | |
| get_status(key) | String | 返回先前和`key`相关联的指定的值。 | |
| erase_status(key) | None | 清除已命名的状态。 | |
| command_history(index, ) | (String,Dict,int) | 对于给定的历史记录条目，返回其存储在撤销/重做堆栈中的指令名称、指令参数和重复次数。索引`0`对应最近一个指令，`-1`对应最近第二个指令，以此类推。索引值为正数表示在重做堆栈中寻找指令。如果撤销/重做历史记录不够多（超出索引），则将返回（None,None,0）。`modifying_only`为`true`表示只返回编辑缓冲区的条目，默认值是`false`。 | |
| change_count() | int | 返回当前修改的数量。缓冲区每一次被修改，修改数就会增加。这个数值可以用来判断缓冲区自上次被检测时是否有作修改。 | |
| fold([regions]) | bool | 折叠指定的区域，如果已经被折叠则返回False。 | |
| fold(region) | bool | 折叠指定的区域，如果已经被折叠则返回False。 | |
| unfold(region) | [regions] | 展开所有区域的文本，返回展开后的区域。 | |
| unfold([regions]) | [regions] | 展开所有区域的文本，返回展开后的区域。 | |
| encoding() | String | 返回当前文件的编码格式。 | |
| set_encoding(encoding) | None | 设置文件的编码格式。新的编码格式会在文件下次保存时生效。 | |
| line_endings() | String | 返回当前文件使用的行结束符。 | |
| set_line_endings(line_endings) | None | 下次保存时设置将使用的行结束符。 | |
| overwrite_status() | Bool | 返回覆盖的状态。 | |
| set_overwrite_status(enabled) | None | 设置覆盖的状态。 | |
| symbols(line_endings) | [(Region, String)] | 提取在缓冲区中定义的所有符号。 | |
| show_popup_menu(items, on_done, ) | None | 在光标处显示一个弹出菜单，用来从一个列表中选择一个选项。`on_done`会以指定项目的索引被调用一次。如果弹出层取消了，`on_done`将会以参数`-1`被调用。`items`是一个字符串组成的数组。`flags`目前别无选择（完全不知道这里是啥意思Flags currently only has no option）。 |
Class sublime.Selection
维护一组区域，确保其没有重叠。区域是有序保存的。
| 方法 | 返回值 | 描述 |
|---|---|---|
| clear() | None | 删除所有区域 |
| add(region) | None | 添加指定的区域，它将与已经包含在集合内的任何相交的区域合并。 |
| add_all(region_set) | None | 添加所有区域。 |
| subtract(region) | None | 从所有区域中删掉指定的区域。 |
| contains(region) | bool | 如果包含了给定区域则返回true。 |
Class sublime.Region
代表缓冲区的一个区域，两个空区域a==b是合法的。
| Constructors | 描述 |
|---|---|
| Region(a, b) | 用初始值a和b创建一个Region。 |
| 属性 | 类型 | 描述 |
|---|---|---|
| a | int | 该区域的第一端。 |
| b | int | 该区域的第二端。比a小时表示这个区域是颠倒的。 |
| xpos | int | 区域的水平位置，如果未定义则是-1。 |
| 方法 | 返回值 | 描述 |
|---|---|---|
| begin() | int | 返回a和b当中的较小值。 |
| end() | int | 返回a和b当中的较大值。 |
| size() | int | 返回区域包含的字符数。 |
| empty() | bool | 区域是否为空。a=b时为true。 |
| cover(region) | Region | 返回两个区域的并集。 |
| intersection(region) | Region | 返回两个区域的交集。 |
| intersects(region) | bool | 如果两个区域存在相交的区域则返回true。 |
| contains(region) | bool | 如果当前区域包含region则返回true。 |
| contains(point) | bool | 如果begin() <= point <= end()则返回true。 |
Class sublime.Edit
Edit对象没有函数，它的存在是为了对缓冲区的修改进行分组。
Edit对象是要传递给TextCommands的，不是用户创建的。使用一个不合法的Edit对象或是从一个不同的视图中使用一个Edit对象将会造成需要依赖它们的函数失败。
| Methods | Return Value | Description |
|---|---|---|
| (no methods) |
Class sublime.Window
| 方法 | 返回值 | 描述 |
|---|---|---|
| id() | int | 返回窗口的唯一识别码 |
| new_file() | View | 创建一个新文件。返回的视图将为空，is_loaded方法将返回true。 |
| open_file(file_name, ) | View | 打开指定文件名的文件，返回相应的视图。如果文件已经被打开，则此文件将会被显示到最前面。注意由于文件加载时异步的，只有is_loading()方法返回false时才能进行操作。可选参数flag是一个和一下选项相结合的按位符：1.sublime.ENCODED_POSITION，表示文件将在:row或:row:col后缀下进行搜索。2.把文件作为一个预览打开：这将不会有一个tab，直到被编辑过。 |
| find_open_file(file_name) | View | 从打开的文件列表中找到指定名称的文件，返回相应的视图，如果没有文件打开则返回None。 |
| active_view() | View | 返回当前正在被编辑的视图。 |
| active_view_in_group(group) | View | 返回指定group中正在被编辑的视图。 |
| views() | [View] | 返回窗口中的所有打开的视图。 |
| views_in_group(group) | [View] | 返回指定group中所有打开的视图。 |
| num_groups() | int | 返回窗口中的视图组的数量。 |
| active_group() | int | 返回当前选中的分组的索引。 |
| focus_group(group) | None | 使当前分组处于激活状态。 |
| focus_view(view) | None | 切换到指定视图。 |
| get_view_index(view) | (group, index) | 返回视图所处的分组和索引。如果没找到则返回-1。 |
| set_view_index(view, group, index) | None | 把视图移动到指定的group和索引。 |
| is_sidebar_visible() | bool | 侧边栏是否可见。 |
| set_sidebar_visible(flag) | None | 设置侧边栏的可见状态。 |
| folders() | [String] | 返回当前打开文件夹组成的列表。 |
| project_file_name() | String | 返回当前打开的项目文件的名称。 |
| project_data() | Dictionary | 返回和当前窗口关联的项目的数据。 |
| set_project_data(data) | None | 更新和当前窗口相关联的项目的数据。如果窗口和.sublime-project文件相关联，则项目文件将在磁盘进行更新，否则窗口将在内存中存储数据。 |
| run_command(string, ) | None | 运行指令。 |
| show_quick_panel(items, on_done, , , ) | None | 显示一个快速面板，可以从中选择一个项。on_done将会用选择项的索引调用一次。如果取消了快速面板，on_done将会以-1进行调用。items可以是一个字符串组成的数组或是一个包含字符串数组的数组。 |
| show_input_panel(caption, initial_text, on_done, on_change, on_cancel) | View | 显示输入面板。on_done和on_change如果不为none时，都应该是一个接收唯一字符串参数的函数。on_cancel是无参数的函数。返回输入组件使用的视图。 |
| create_output_panel(name, ) | View | 返回和输出面板关联的视图，如果需要则创建。运行窗口指令show_panel来显示输出面板。 |
| find_output_panel(name) | View or None | 返回指定输出面板的视图，如果不存在则返回none。 |
| destroy_output_panel(name) | None | 销毁指定输入面板，如果当前是打开的则隐藏它。 |
| active_panel() | string or None | 返回当前打开的面板的名称，如果没有则返回none。 |
| panels() | [string] | 返回没有被标记为不列出的所有面板的名称。包括除了输出面板的特定内置面板。 |
| create_output_panel(name) | View | 返回和输出面板关联的视图，如果需要则创建。运行窗口指令show_panel来显示输出面板。 |
| lookup_symbol_in_index(symbol) | [Location] | 返回当前项目中所有文件中定义的符号的位置。 |
| lookup_symbol_in_open_files(symbol) | [Location] | 返回所有打开文件中定义的符号的位置。 |
| extract_variables() | Dictionary | 返回一个字典：packages，platform，file，file_path，file_name， file_base_name，file_extension，folder，project， project_path， project_name，project_base_name，project_extension。这个字典适合传递给sublime.expand_variables()。 |
Class sublime.Settings
| 方法 | 值 | 描述 |
|---|---|---|
| get(name) | value | 返回指定名称的设置。 |
| get(name, default) | value | 返回指定名称的设置，如果未定义则返回默认值。 |
| set(name, value) | None | 设置指定名称的设置。只支持原始类型，列表和字典。 |
| erase(name) | None | 删除指定设置，不从父级Settings中删除。 |
| has(name) | bool | 是否存在某项设置。 |
| add_on_change(key, on_change) | None | 当一个设置有改动时注册一个回调函数。 |
| clear_on_change(key) | None | 删除所有以指定key注册的回调函数。 |
Module sublime_plugin
| Methods | Return Value | Description |
|---|---|---|
| (no methods) |
Class sublime_plugin.EventListener
很多事件都是由视图的底层触发的，因此这些方法只会以第一个视图作为参数被调用一次。
| 方法 | 返回值 | 描述 |
|---|---|---|
| on_new(view) | None | 创建新的缓冲区时调用。 |
| on_new_async(view) | None | 创建新的缓冲区时异步调用。 |
| on_clone(view) | None | 克隆一个视图时调用。 |
| on_clone_async(view) | None | 克隆一个视图时异步调用。 |
| on_load(view) | None | 文件加载完毕时调用。 |
| on_load_async(view) | None | 加载完毕时异步调用。 |
| on_pre_close(view) | None | 视图关闭之前被调用。 |
| on_close(view) | None | 视图关闭后调用（注意，可能会有其他的视图到缓冲区中）。 |
| on_pre_save(view) | None | 视图保存前调用。 |
| on_pre_save_async(view) | None | 视图保存前异步调用。 |
| on_post_save(view) | None | 视图保存后调用。 |
| on_post_save_async(view) | None | 视图被保存后异步调用。 |
| on_modified(view) | None | 视图有修改时调用。 |
| on_modified_async(view) | None | 视图有修改时异步调用。 |
| on_selection_modified(view) | None | 视图中的选中区被修改后调用。 |
| on_selection_modified_async(view) | None | 视图中的选中区被修改后异步调用。 |
| on_activated(view) | None | 视图获得输入焦点时调用。 |
| on_activated_async(view) | None | 视图获得输入焦点时异步调用。 |
| on_deactivated(view) | None | 视图失去输入焦点时调用。 |
| on_deactivated_async(view) | None | 视图失去输入焦点时异步调用。 |
| on_text_command(view, command_name, args) | (new_command_name, new_args) | 发出文本指令时调用。监视器可以返回一个（command, arguments）元组来重写改指令，如果未作修改则返回none。 |
| on_window_command(window, command_name, args) | (new_command_name, new_args) | 发出窗口指令时调用。监视器可以返回一个（command, arguments）元组来重写改指令，如果未作修改则返回none。 |
| post_text_command(view, command_name, args) | None | 文本指令被执行时调用。 |
| post_window_command(window, command_name, args) | None | 窗口指令被执行时调用。 |
| on_query_context(view, key, operator, operand, match_all) | bool或None | 当决定用指定key去触发一个按键绑定时被调用。如果插件知道如何对上下文进行回应，则应该返回true或false。如果上下文是未知的，则返回none。 operater可以是以下中的一个：
match_all 如果上下文涉及到这些选择则应该被使用：是否每一个选择都应该匹配（match_all = True），是否匹配一项就够了（match_all = False）？ |
Class sublime_plugin.ApplicationCommand
| 方法 | 返回值 | 描述 |
|---|---|---|
| run() | None | 指令执行时调用。 |
| is_enabled() | bool | 如果指令此时是可以运行时返回true。默认返回true。 |
| is_visible() | bool | 如果指令当前显示在菜单栏中则返回true。默认返回true。 |
| is_checked() | bool | 如果复选框显示在菜单项旁边则返回true，如果要使用这个则.sublime-menu文件必须把checkbox属性设置为true。 |
| description() | String | 返回指令的描述。 |
Class sublime_plugin.WindowCommand
每个窗口只会实例化一次WindowCommands。Window对象可以通过self.window来恢复。
| 方法 | 返回值 | 描述 |
|---|---|---|
| run() | None | 指令执行时调用 |
| is_enabled() | bool | 如果指令此时是可以运行时返回true。默认返回true。 |
| is_visible() | bool | 如果指令当前显示在菜单栏中则返回true。默认返回true。 |
| description() | String | 返回指令的描述。 |
Class sublime_plugin.TextCommand
每个窗口只会实例化一次TextCommands。Window对象可以通过self.view来恢复。
| 方法 | 返回值 | 描述 |
|---|---|---|
| run(edit, ) | None | 指令执行时调用 |
| is_enabled() | bool | 如果指令此时是可以运行时返回true。默认返回true。 |
| is_visible() | bool | 如果指令当前显示在菜单栏中则返回true。默认返回true。 |
| description() | String | 返回指令的描述。 |
| want_event() | bool | 当指令值通过鼠标行为触发时返回true以接收一个事件参数。事件的信息允许指令判断视图的哪一部分被点击了，默认返回false。 |