插件

另请参阅

API 参考 : 关于 Python API 的更多信息。

插件是继承自 sublime_plugin 模块中的 *Command 或 *Listener 类 的 Python 脚本。

插件存储位置

Sublime Text 会在以下位置查找插件

• Packages
• Packages/<pkg_name>
• .sublime-package 文件

嵌套在 Packages 中更深层的插件文件将不会被加载。

所有插件都应该放在自己的文件夹中，而不是直接放在 Packages 下。这样可以避免 Sublime Text 在尝试对包进行排序以加载时出现混淆。

命令命名约定

按照惯例，Sublime Text 命令类名以 Command 结尾，并以 NamesLikeThisCommand 的形式编写。

但是，命令名称会自动从 NamesLikeThisCommand 转换为 name_like_this。因此，ExampleCommand 将变为 example，而 AnotherExampleCommand 将变为 another_example。

在定义命令的类的名称中，使用 NameLikeThisCommand。要从 API 调用命令，请使用标准化的 name_like_this。

命令类型

• sublime_plugin.ApplicationCommand
• sublime_plugin.WindowCommand
• sublime_plugin.TextCommand

WindowCommand 的实例有一个指向创建它们的窗口实例的 .window 属性。类似地，TextCommand 的实例有一个 .view 属性。ApplicationCommand 实例没有这两个属性。

命令的共享特性

所有命令都必须实现 .run() 方法。

所有命令还可以提供方法来更改它们的可见性、启用状态、菜单中的默认标题，甚至它们的名称（不建议这样做）。

如何从 API 调用命令

根据命令的类型，使用对 View 或 Window 的引用，并调用 <object>.run_command('command_name')。除了命令的名称之外，.run_command 还接受一个字典，其键是该命令的有效参数的名称

window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."})

传递给命令的所有用户提供的参数必须是 JSON 可序列化的。这包括字符串、整数、浮点数、布尔值、None 以及递归列表和字典类型。映射键必须是字符串。

文本命令和 edit 对象

文本命令会收到 Sublime Text 传递给它们的 edit 对象。

在 edit 中执行的所有操作都将被分组为单个撤销操作。当最外层的编辑操作完成时，将调用回调函数，例如 on_modified() 和 on_selection_modified()。

edit 对象的生命周期完全由 Sublime Text 内部管理。插件作者必须确保在文本命令的 run() 方法中执行所有编辑操作，以确保宏和重复命令按预期工作。

响应事件

任何 EventListener 的子类都可以响应事件。您不能让一个类同时继承自 EventListener 和任何其他类型的命令。

警告

事件监听器中的昂贵操作会导致 Sublime Text 变得无响应，尤其是在频繁触发的事件中，例如 on_modified() 和 on_selection_modified()。请谨慎考虑在这些事件中完成的工作量，并且不要实现您不需要的事件，即使它们只是 pass。

Sublime Text 和 Python 标准库

默认发行版中最重要的缺失是 tkinter 模块。否则，您可以访问 Sublime Text 附带的 Python 版本的整个 Python 标准库。

自动插件重新加载

Sublime Text 会在最顶层的 Python 模块发生变化时重新加载它们（可能是因为您正在编辑 Packages 中的 .py 文件）。相比之下，Python 子包不会自动重新加载，这在您开发插件时可能会导致混淆。一般来说，最好在您对插件文件进行更改后重新启动 Sublime Text，以便所有更改都能生效。