ST 社区文档

外观

插件 ​

信息

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

插件参考 : 关于插件的更多信息。

本节面向具有编程技能的用户。

Sublime Text 可以通过 Python 插件进行扩展。插件通过重用现有命令或创建新命令来构建功能。插件是一个逻辑实体，而不是物理实体。

先决条件 ​

为了编写插件，您必须能够使用 Python 编程。在撰写本文时，Sublime Text 使用 Python 3.3。

插件存储位置 ​

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

  • 已安装的包 (仅 .sublime-package 文件)
  • 包
  • Packages/<pkg_name>/

因此，嵌套在 Packages 中的任何插件都不会被加载。

不建议将插件直接保存在 Packages 下。Sublime Text 在加载插件之前以预定义的方式对插件进行排序，因此如果您将插件文件直接保存在 Packages 下，可能会得到令人困惑的结果。

您的第一个插件 ​

让我们为 Sublime Text 编写一个“Hello, World!”插件

  1. 在菜单中选择 **工具 | 开发者 | 新插件...**。
  2. 保存到 Packages/User/hello_world.py。

您刚刚编写了您的第一个插件！让我们开始使用它

  1. 创建一个新缓冲区 (Ctrl N).
  2. 打开 Python 控制台 (Ctrl `).
  3. 输入：view.run_command("example") 并按回车键。

您应该在新建的缓冲区中看到文本“Hello, World!”。

分析您的第一个插件 ​

上一节中创建的插件应该大致如下所示

py
import sublime
import sublime_plugin


class ExampleCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        self.view.insert(edit, 0, "Hello, World!")

sublime 和 sublime_plugin 模块都由 Sublime Text 提供；它们不是 Python 标准库的一部分。

如前所述，插件会重用或创建命令。命令是 Sublime Text 中必不可少的构建块。它们只是 Python 类，可以从不同的 Sublime Text 功能（如插件 API、菜单文件、宏等）以类似的方式调用。

Sublime Text 命令派生自 sublime_plugin 中定义的 *Command 类（稍后将详细介绍）。

我们示例中的其余代码涉及TextCommand的细节或 API。我们将在后面的章节中讨论这些主题。

不过，在我们继续之前，让我们看看如何调用新命令：首先我们打开 Python 控制台，然后我们调用view.run_command()。这是一种调用命令相当不方便的方式，但在插件的开发阶段通常很有用。现在，请记住，您的命令可以通过键绑定和其他方式访问，就像其他命令一样。

命令命名约定 ​

您可能已经注意到我们的命令名为ExampleCommand，但我们向 API 调用传递了字符串example。这是必要的，因为 Sublime Text 通过剥离Command后缀，用下划线分割PhrasesLikeThis之类的子词，并将其小写化来标准化命令名称，例如：phrases_like_this。

新的命令应该遵循相同的命名模式。

命令类型 ​

您可以创建以下类型的命令

  • 窗口命令 (sublime_plugin.WindowCommand)
  • 文本命令 (sublime_plugin.TextCommand)

在编写插件时，请考虑您的目标并选择合适的命令类型。

命令的共同特征 ​

所有命令都需要实现.run()方法才能工作。此外，它们可以接收任意数量的关键字参数。

注意：由于 ST 在内部序列化命令参数的方式，命令的参数必须是有效的 JSON 值。

窗口命令 ​

窗口命令在窗口级别运行。这并不意味着您不能从窗口命令中操作视图，而是指您不需要视图就可以使用窗口命令。例如，内置命令new_file被定义为WindowCommand，因此即使没有打开视图，它也能工作。在这种情况下，要求视图存在是没有意义的。

窗口命令实例具有.window属性，指向创建它们的窗口实例。

窗口命令的.run()方法不需要任何位置参数。

窗口命令能够将文本命令路由到其窗口的活动视图。

文本命令 ​

文本命令在视图级别运行，因此它们需要一个视图才能使用。

文本命令实例具有.view属性，指向创建它们的视图实例。

文本命令的.run()方法需要edit实例作为其第一个位置参数。

文本命令和edit对象 ​

edit 对象对视图的修改进行分组，以便撤消和宏可以正常工作。

注意：与旧版本相反，Sublime Text 3 不允许对 edit 对象进行编程控制。API 负责管理它们的生命周期。插件创建者必须确保所有修改操作都在新文本命令的.run方法中进行。要调用现有命令，您可以使用view.run_command(<cmd_name>, <args>)或类似的 API 调用。

响应事件 ​

任何从EventListener派生的命令都能够响应事件。

另一个插件示例：填充自动完成列表 ​

让我们创建一个插件，从 Google 的自动完成服务中获取数据，然后将其填充到 Sublime Text 自动完成列表中。请注意，就插件的想法而言，这是一个非常糟糕的插件。

python
import sublime
import sublime_plugin

from xml.etree import ElementTree as ET
import urllib

GOOGLE_AC = "http://google.com/complete/search?output=toolbar&q=%s"


class GoogleAutocomplete(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):
        elements = ET.parse(
            urllib.request.urlopen(GOOGLE_AC % prefix)
        ).getroot().findall("./CompleteSuggestion/suggestion")

        sugs = [(x.attrib["data"],) * 2 for x in elements]

        return sugs

注意

确保您在尝试完此插件后不要保留它，否则它会干扰自动完成系统。

学习 API ​

API 参考文档位于 https://text.sublime.net.cn/docs/api_reference.html。

要熟悉 Sublime Text API 和可用的命令，阅读现有代码并从中学习可能会有所帮助。

特别是，Packages/Default 包含许多未记录的命令和 API 调用示例。请注意，如果您想查看其中的代码，则需要先将其内容提取到一个文件夹中。命令面板中的“查看包文件”命令可以帮助您完成此操作。