Sublime Text 非官方文档¶

搜索¶

Ctrl + F 可以打开当前缓冲区的 搜索面板。可通过下面这些指令对搜索面板进行控制：

（译者注：关于缓冲区，请参考 词汇表 这个章节）

增量搜索¶

增量搜索面板 可以通过``Ctrl + I``打开。与正常的搜索面板相比，唯一的区别在于 回车

键的作用：在增量搜索中，按下回车键将选中缓冲区中下一段与搜索条件匹配的文字，并自动关闭面板。 一般来说，可以根据个人的喜好来决定是选择增量搜索面板还是普通搜索面板。

替换文本¶

可以通过 Ctrl + H 来打开替换面板。

小技巧¶

搜索¶

使用 Ctrl + Shift + F 键可以打开多文件搜索面板。搜索面板与搜索动作可以使用快捷键进行操作：

搜索范围¶

搜索面板中的 Where 字段决定搜索文件的范围。你可以通过以下几种方式来确定文件的搜索作用域：

• 添加一个独立的目录 （需要使用 Unix风格的文件路径，在Windows平台也是如此）
• 使用某种模式来添加/删除某些文件
• 添加链接位置(<open folders>, <open files>)

你可以在一次搜索中组合使用以上确定作用域的方式，并且在不同方式之间用逗号分隔，例如：

/C/Users/Joe/Top Secret,-*.html,<open files>

通过在搜索面板中按 ... 按钮来显示包含这些选项的菜单。

（译者注：Unix风格的文件路径指的是使用 / 来区分目录结构，例如 /Users/voidmain/ ，在 Windows平台上，可以使用 /C/Users/ 来指定盘符）

搜索结果显示方式¶

在搜索面板中，可以使用下面的选项来自定义搜索结果的显示方式：

• 在单独的缓冲区/输出面板中显示
• 显示上下文

搜索结果跳转¶

一旦找到了符合要求的内容，你就可以使用以下的快捷键进行结果之间的跳转：

格式¶

配置项文件是以 .sublime-settings 作为扩展名的的JSON文件。

配置文件的类型¶

可以通过 .sublime-settings 文件的名字看出它的用途。这些文件的名字可能具有一定的描述性（例如 Preferences (Windows).sublime-settings 或者 Minimap.sublime-settings），亦或是跟 它所控制的内容有关联。以控制文件类型的配置项文件为例，命名时要求必须有与之对应的 .tmLanguage 语法定义文件。因此，对于 .py 文件类型，它的语法定义信息存放在 Python.tmLanguage 文件中， 那么对应的文件类型配置项文件就该被叫做 Python.sublime-settings 。

除此之外，某些配置文件只能作用于某个特定的平台。可以通过文件名进行推断，例如： Preferences (Windows).sublime-settings 和 Preferences (Linux).sublime-settings 。

有一点特别 重要 ：存放在 Packages/User 目录中的平台相关的配置文件将被忽略。通过这种方式， 就可以保证单个配置文件内容可以覆盖其他所有配置文件的内容了。

如何访问并修改公共的配置文件¶

除非你对配置项有非常精确的掌控力，否则，你只需要通过 Preferences | Settings - User 和 Preferences | Settings - More 菜单项来访问主要的配置文件。编辑 Preferences - Settings Default 这个文件并不是一件明智的事情，因为每次版本升级这些修改都 将被重置。不过，你确实可以把这些文件当作一个不错的参考资料：默认配置项文件里面包含了解释所有能 为你所用的全局配置项和文件类型配置项的说明注释。

.sublime-settings 文件的优先级顺序¶

名字相同的配置项文件（例如，都叫 Python.sublime-settings 的文件）可以在多个位置出现。以相同 名称命名的配置项文件中的内容都将按预定义的规则进行合并或者覆盖。请参考 合并与优先级顺序 这一小节以了解更多信息。

再说明一次，在 Packages/User 目录下的配置项文件拥有最高优先级，并且最终会覆盖其他同名配置项 文件中的相同内容。

除了配置项文件以外，Sublime Text还维护 会话 数据 —— 一些针对正在编辑的文件集所应用的配置项。 会话数据是在你编辑文件的过程中发生变化的，所以，无论你通过何种方式调整了一个特定文件的配置项 （主要是通过API调用的方式），这些配置项的变更将被记录在当前的会话中，并且将拥有比所有符合条件的 .sublime-settings 文件更高的优先级。

如果想要检查针对特定文件当前正在发挥作用的配置项的值，可以在控制台中输入 view.settings().get(<配置项名称>) 命令。

最后需要注意的是，某些配置项的值可能会被系统自动进行调整。请记住这一点，这样一来你就能够解释某 些令你困惑的配置项内容了。举例来说，在查看某些与空格相关的配置项的值，以及某些 语法 配置项 内容的时候，就有可能遇到这种问题。

接下来你将看到Sublime Text是如何处理Windows平台上Python相关的配置项文件的，这里的配置项文件 目录结构是虚构的：

• Packages/Default/Preferences.sublime-settings
• Packages/Default/Preferences (Windows).sublime-settings
• Packages/User/Preferences.sublime-settings
• Packages/Python/Python.sublime-settings
• Packages/User/Python.sublime-settings
• 当前文件的会话数据
• 由系统自动调整的配置项内容

（译者注：分析下优先级，可以得到结论：全局默认项 < 平台默认项 < 用户配置项 < 语言相关的配置 < 由用户指定的语言相关的配置 < 会话数据 < 系统调整的数据）

全局编辑器配置以及全局文件配置¶

这类全局配置项内容一般被保存在名为 Preferences.sublime-settings 和 Preferences (<platform>).sublime-settings 的文件中。默认的全局配置项存放在 Packages/Default 目录中。

上面所说的 <platform> 可能是 Linux, OSX, 或者 Windows.

文件类型配置¶

如果你想针对某个特定的文件类型进行一些配置，那请根据这个文件类型的语法定义文件名称来对应的命名 .sublime-settings 文件。举例来说，如果我们的语法定义文件叫 Python.tmLanguage ，那么 配置项文件的名称就应该叫 Python.sublime-settings 。

通常情况下，某个特定文件类型的配置项信息一般存放在包组文件夹的一个目录中，例如 Packages/Python， 但是，与同一个文件类型相关的多个配置项文件也有可能被存放在不同的位置。

与全局配置项类似，也可以为文件类型配置项信息创建平台相关的内容。例如只有在Linux平台下，保存在 Python (Linux).sublime-settings 中的配置项内容才会被系统考虑。

需要特别指出的一点是，在 Packages/User 目录下，只有 Python.sublime-settings 文件会被 加载，所有以 Python (<platform>).sublime-settings 命名的平台相关的变种都不会被考虑。

不管文件类型配置项信息保存在哪里，它拥有比保存在全局配置项文件中的、影响文件类型的配置项都高的 优先级。

用户配置信息应该保存到哪里¶

无论何时，当你想要保存一些配置的时候，尤其是那些在软件升级前后应该被保留的配置，就把它们保存在 Packages/User 目录下的对应 .sublime-settings 文件中吧。

文件格式¶

键盘绑定是以 .sublime-keymap 作为扩展名的JSON文件。为了让键盘能够更好的与各平台融合，系统为 Linux，OSX以及Windows平台分别提供了不同的文件。只有与当前系统相符的键盘映射文件才会生效。

[
        { "keys": ["ctrl+shift+n"], "command": "new_window" },
        { "keys": ["ctrl+o"], "command": "prompt_open_file" }
]

定义与重载键盘绑定¶

Sublime Text自带一套默认的键盘绑定（一般对应这个文件： Packages/Default/Default (Windows).sublime-keymap)）。如果你想重载其中的部分键盘 或者添加新的键盘绑定，你可以在具有更高文件优先级的位置重新存储一个文件，例如 Packages/User/Default (Windows).sublime-keymap。

请参考 合并与优先级顺序 来了解Sublime Text中关于文件优先级以及文件合并的更多信息

高级键盘绑定¶

对于简单的键盘绑定，就是一个键盘组合对应一个命令。除此之外，还有一些传递参数和上下文信息的复杂语法。

{ "keys": ["shift+enter"], "command": "insert", "args": {"characters": "\n"} }

{ "keys": ["escape"], "command": "clear_fields", "context":
        [
                { "key": "has_next_field", "operator": "equal", "operand": true }
        ]
}

Command Dispatching¶

Normally, commands are bound to the application object, a window object or a view object. Window objects, however, will dispatch commands based on input focus, so you can issue a view command from a window object and the correct view instance will be found for you.

Anatomy of a Command¶

Commands have a name separated by underscores (snake_case) like hot_exit, and can take a dictionary of arguments whose keys must be strings and whose values must be JSON types. Here are a few examples of commands run from the Python console:

view.run_command("goto_line", {"line": 10})
view.run_command('insert_snippet', {"contents": "<$SELECTION>"})
view.window().run_command("prompt_select_project")

How to Record Macros¶

To start recording a macro, press Ctrl+q and subsequently execute the desired steps one by one. When you’re done, press Ctrl+q again to stop the macro recorder. Your new macro won’t be saved to a file, but kept in the macro buffer instead. Now you will be able to run the recorded macro by pressing Ctrl+Shift+q, or save it to a file by selecting Tools | Save macro...

Note that the macro buffer will remember only the latest recorded macro. Also, macros only record commands sent to the buffer: window-level commands, such creating a new file, will be ignored.

How to Edit Macros¶

As an alternative to recording a macro, you can edit it by hand. Just save a new file with the extension .sublime-macro under PackagesUser and add commands to it. Macro files have this format:

[
    {"command": "move_to", "args": {"to": "hardeol"}},
    {"command": "insert", "args": {"characters": "\n"}}
]

See the ../core/commands section for more information on commands.

If you’re editing a macro by hand, you need to escape quotation marks, blank spaces and backslashes by preceding them with \.

Where to Store Macros¶

Macro files can be stored in any package folder, and then will show up under Tools | Macros | <PackageName>.

Snippets File Format¶

Snippets typically live in a Sublime Text package. They are simplified XML files with the extension sublime-snippet. For instance, you could have a greeting.sublime-snippet inside an Email package.

The structure of a typical snippet is as follows (including the default hints Sublime Text inserts for your convenience):

<snippet>
    <content><![CDATA[Type your snippet here]]></content>
    <!-- Optional: Tab trigger to activate the snippet -->
    <tabTrigger>xyzzy</tabTrigger>
    <!-- Optional: Scope the tab trigger will be active in -->
    <scope>source.python</scope>
    <!-- Optional: Description to show in the menu -->
    <description>My Fancy Snippet</description>
</snippet>

The snippet element contains all the information Sublime Text needs in order to know what to insert, whether to insert and when. Let’s see all of these parts in turn.

content

The actual snippet. Snippets can range from simple to fairly complex templates. We’ll look at examples of both later.

Keep the following in mind when writing your own snippets:

• If you want to get a literal $, you have to escape it like this: \$.
• When writing a snippet that contains indentation, always use tabs. When the snippet is inserted, the tabs will be transformed into spaces if the option translateTabsToSpaces is true.
• The content must be included in a <![CDATA[...]]> section. Snippets won’t work if you don’t do this!
• The content of your snippet must not contain ]]> because this string of characters will prematurely close the <![CDATA[…]]> section, resulting in an XML error. To work around this pitfall, you can insert an undefined variable into the string like this: ]]$NOT_DEFINED>. This modified string passes through the XML parser without closing the content element’s <![CDATA[…]]> section, but Sublime Text will replace $NOT_DEFINED with an empty string before inserting the snippet into your document. In other words, ]]$NOT_DEFINED> in your snippet file content will be written as ]]> when you trigger the snippet.

tabTrigger

Defines the sequence of keys that must be pressed to insert this snippet. After typing this sequence, the snippet will kick in as soon as you hit the Tab key.

A tab trigger is an implicit key binding.

scope

Scope selector determining the context where the snippet will be active. See Scopes for more information.

description

Used for displaying the snippet in the Snippets menu. If unavailable, Sublime Text defaults to the name of the snippet.

With this information, you can start writing your own snippets as described in the next sections.

Snippet Features¶

====================================
USER NAME:          $TM_FULLNAME
FILE NAME:          $TM_FILENAME
 TAB SIZE:          $TM_TAB_SIZE
SOFT TABS:          $TM_SOFT_TABS
====================================

# Output:
====================================
USER NAME:          guillermo
FILE NAME:          test.txt
 TAB SIZE:          4
SOFT TABS:          YES
====================================

First Name: $1
Second Name: $2
Address: $3

First Name: $1
Second Name: $2
Address: $3
User name: $1

      Original: ${1:Hey, Joe!}
Transformation: ${1/./=/g}

# Output:

      Original: Hey, Joe!
Transformation: =========

File Format¶

Completions are JSON files with the .sublime-completions extension. Entries in completions files can contain either snippets or plain strings.

{
        "scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",

        "completions":
        [
                { "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
                { "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
                { "trigger": "acronym", "contents": "<acronym>$0</acronym>" }
        ]
}

{
        "scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",

        "completions":
        [
                { "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
                { "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
                { "trigger": "acronym", "contents": "<acronym>$0</acronym>" },

                "ninja",
                "robot",
                "pizza"
        ]
}

Sources for Completions¶

Completions not only originate in .sublime-completions files. Here is the exhaustive list of sources for completions:

• Snippets
• API-injected completions
• .sublime-completions files
• Words in buffer

How to Use Completions¶

There are two methods for using completions. Even though, when screening them, the priority given to completions always stays the same, the two methods produce different results, as explained next.

Completions can be inserted in two ways:

• Through the completions list (Ctrl+spacebar).
• By pressing Tab.

Overview¶

The command palette bound to Ctrl+Shift+P is an interactive list whose purpose is to execute commands. The command palette is fed by entries in .sublime-commands files. Usually, commands that don’t warrant creating a key binding of their own are good candidates for inclusion in a .sublime- commands files.

File Format (Commands Files)¶

Commands files use JSON and have the .sublime-commands extension.

Here’s an excerpt from Packages/Default/Default.sublime-commands:

[
    { "caption": "Project: Save As", "command": "save_project_as" },
    { "caption": "Project: Close", "command": "close_project" },
    { "caption": "Project: Add Folder", "command": "prompt_add_folder" },

    { "caption": "Preferences: Default File Settings", "command": "open_file", "args": {"file": "${packages}/Default/Base File.sublime-settings"} },
    { "caption": "Preferences: User File Settings", "command": "open_file", "args": {"file": "${packages}/User/Base File.sublime-settings"} },
    { "caption": "Preferences: Default Global Settings", "command": "open_file", "args": {"file": "${packages}/Default/Global.sublime-settings"} },
    { "caption": "Preferences: User Global Settings", "command": "open_file", "args": {"file": "${packages}/User/Global.sublime-settings"} },
    { "caption": "Preferences: Browse Packages", "command": "open_dir", "args": {"dir": "$packages"} }
]

caption

Text for display in the command palette.

command

Command to be executed.

args

Arguments to pass to command.

How to Use the Command Palette¶

1. Press Ctrl+Shift+P
2. Select command

The command palette filters entries by context. This means that whenever you open it, you won’t always see all the commands defined in every .sublime-commands file.

Prerequisites¶

In order to follow this tutorial, you will need to install AAAPackageDev, a package intended to ease the creation of new syntax definitions for Sublime Text. It lives in a public Mercurial repository at Bitbucket.

Download the latest .sublime-package file and install it as described in Installation of .sublime-package Files.

File format¶

Sublime Text uses property list (Plist) files to store syntax definitions. However, because editing XML files is a cumbersome task, we’ll use JSON instead, and convert it to Plist format afterwards. This is where the AAAPackageDev package (mentioned above) comes in.

By all means, do edit the Plist files by hand if you prefer to work in XML, but always keep in mind their differing needs in regards to escape sequences, etc.

Scopes¶

Scopes are a key concept in Sublime Text. Essentially, they are named text regions in a buffer. They don’t do anything by themselves, but Sublime Text peeks at them when it needs contextual information.

For instance, when you trigger a snippet, Sublime Text checks the scope bound to the snippet and looks at the caret’s position in the file. If the caret’s current position matches the snippet’s scope selector, Sublime Text fires it off. Otherwise, nothing happens.

Scopes can be nested to allow for a high degree of granularity. You can drill down the hierarchy very much like with CSS selectors. For instance, thanks to scope selectors, you could have a key binding activated only within single quoted strings in Python source code, but not inside single quoted strings in any other language.

Sublime Text inherits the idea of scopes from Textmate, a text editor for Mac. Textmate’s online manual contains further information about scope selectors that’s useful for Sublime Text users too.

How Syntax Definitions Work¶

At their core, syntax definitions are arrays of regular expressions paired with scope names. Sublime Text will try to match these patterns against a buffer’s text and attach the corresponding scope name to all occurrences. These pairs of regular expressions and scope names are known as rules.

Rules are applied in order, one line at a time. Each rule consumes the matched text region, which therefore will be excluded from the next rule’s matching attempt (save for a few exceptions). In practical terms, this means that you should take care to go from more specific rules to more general ones when you create a new syntax definition. Otherwise, a greedy regular expression might swallow parts you’d like to have styled differently.

Syntax definitions from separate files can be combined, and they can be recursively applied too.

Your First Syntax Definition¶

By way of example, let’s create a syntax definition for Sublime Text snippets. We’ll be styling the actual snippet content, not the .sublime-snippet file.

Here are the elements we want to style in a snippet:

• Variables ($PARAM1, $USER_NAME...)
• Simple fields ($0, $1...)
• Complex fields with placeholders (${1:Hello})
• Nested fields (${1:Hello ${2:World}!})
• Escape sequences (\\$, \\<...)
• Illegal sequences ($, <...)

{ "name": "Syntax Name",
  "scopeName": "source.syntax_name",
  "fileTypes": [""],
  "patterns": [
  ],
  "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

{   "name": "Sublime Snippet (Raw)",
    "scopeName": "source.ssraw",
    "fileTypes": ["ssraw"],
    "patterns": [
    ],
    "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

Analyzing Patterns¶

The patterns array can contain several types of elements. We’ll look at some of them in the following sections. If you want to learn more about patterns, refer to Textmate’s online manual.

{ "match": "[Mm]y \s+[Rr]egex",
  "name": "string.ssraw",
  "comment": "This comment is optional."
}

{ "name": "Sublime Snippet (Raw)",
  "scopeName": "source.ssraw",
  "fileTypes": ["ssraw"],
  "patterns": [
  ],
  "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

\$[0-9]+
# or...
\$\d+

\\$\\d+

{ "match": "\\$\\d+",
  "name": "keyword.source.ssraw",
  "comment": "Tab stops like $1, $2..."
}

{   "name": "Sublime Snippet (Raw)",
    "scopeName": "source.ssraw",
    "fileTypes": ["ssraw"],
    "patterns": [
        { "match": "\\$\\d+",
          "name": "keyword.source.ssraw",
          "comment": "Tab stops like $1, $2..."
        }
    ],
    "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

{ "match": "\\$[A-Za-z][A-Za-z0-9_]+",
  "name": "keyword.source.ssraw",
  "comment": "Variables like $PARAM1, $TM_SELECTION..."
}

{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
  "name": "keyword.ssraw",
  "captures": {
      "1": { "name": "constant.numeric.ssraw" }
   },
  "comment": "Variables like $PARAM1, $TM_SELECTION..."
}

{ "name": "",
  "begin": "",
  "end": ""
}

{ "name": "",
  "begin": "",
  "beginCaptures": {
    "0": { "name": "" }
  },
  "end": "",
  "endCaptures": {
    "0": { "name": "" }
  },
  "patterns": [
     {  "name": "",
        "match": ""
                  }
  ],
  "contentName": ""
}

{ "name": "variable.complex.ssraw",
   "begin": "(\\$)(\\{)([0-9]+):",
   "beginCaptures": {
       "1": { "name": "keyword.ssraw" },
       "3": { "name": "constant.numeric.ssraw" }
   },
   "patterns": [
       { "include": "$self" },
       {  "name": "string.ssraw",
          "match": "."
       }
   ],
   "end": "\\}"
}

{  "name": "constant.character.escape.ssraw",
   "match": "\\\\(\\$|\\>|\\<)"
},

{  "name": "invalid.ssraw",
   "match": "(\\$|\\<|\\>)"
}

{   "name": "Sublime Snippet (Raw)",
    "scopeName": "source.ssraw",
    "fileTypes": ["ssraw"],
    "patterns": [
        { "match": "\\$(\\d+)",
          "name": "keyword.ssraw",
          "captures": {
              "1": { "name": "constant.numeric.ssraw" }
           },
          "comment": "Tab stops like $1, $2..."
        },

        { "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
          "name": "keyword.ssraw",
          "captures": {
              "1": { "name": "constant.numeric.ssraw" }
           },
          "comment": "Variables like $PARAM1, $TM_SELECTION..."
        },

        { "name": "variable.complex.ssraw",
          "begin": "(\\$)(\\{)([0-9]+):",
          "beginCaptures": {
              "1": { "name": "keyword.ssraw" },
              "3": { "name": "constant.numeric.ssraw" }
           },
           "patterns": [
              { "include": "$self" },
              { "name": "string.ssraw",
                "match": "."
              }
           ],
           "end": "\\}"
        },

        { "name": "constant.character.escape.ssraw",
          "match": "\\\\(\\$|\\>|\\<)"
        },

        { "name": "invalid.ssraw",
          "match": "(\\$|\\>|\\<)"
        }
    ],
    "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

Prerequisites¶

In order to write plugins, you must be able to program in Python.

Where to Store Plugins¶

Sublime Text will look for plugins directly in these places:

• Packages
• Packages/<pkg_name>/

Consequently, any plugin nested deeper in Packages won’t be loaded.

Keeping plugins just under Packages is discouraged, because Sublime Text sorts packages in a predefined way before loading them. So, you might get confusing results if your plugins live outside a package.

Your First Plugin¶

Let’s write a “Hello, World!” plugin for Sublime Text:

1. Select Tools | New Plugin... in the menu.
2. Save to Packages/User/hello_world.py.

You’ve just written your first plugin! Let’s put it to use:

1. Create a new buffer (Ctrl+n).
2. Open the Python console (Ctrl+`).
3. Type: view.run_command("example") and press enter.

You should see the text “Hello, World!” in your new buffer.

Analyzing Your First Plugin¶

The plugin created in the previous section should look roughly like this:

import sublime, sublime_plugin

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

Both the sublime and sublime_plugin modules are provided by Sublime Text.

All new commands derive from the *Command classes defined in sublime_plugin (more on this later).

The rest of the code is concerned with the particulars of TextCommand or with the API. We’ll discuss those topics in later sections.

Before moving on, though, we’ll look at how we invoked the new command. First we opened the Python console, and then we issued a call to view.run_command(). This is rather an inconvenient way of using plugins, but it’s often useful when you’re in the development phase of a plugin. For now, keep in mind that your commands can be accessed both through key bindings and by other means, just like other commands.

Types of Commands¶

You can create the following types of commands:

• Application commands (ApplicationCommand)
• Window commands (WindowCommand)
• Text commands (TextCommand)

When writing plugins, consider your goal and choose the appropriate type of commands for your plugin.

import sublime, sublime_plugin

from xml.etree import ElementTree as ET
from urllib import urlopen

GOOGLE_AC = r"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(
                        urlopen(GOOGLE_AC % prefix)
                    ).getroot().findall("./CompleteSuggestion/suggestion")

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

        return sugs

Learning the API¶

In order to create plugins, you need to get acquainted with the Sublime Text API and the available commands. Documentation on both is scarce at the time of this writing, but you can read existing code and learn from it too. In particular, the Packages/Default folder contains many examples of undocumented commands and API calls.

Types of Packages¶

In this guide, in order to talk about packages, we divide them into groups. This division is artificial, and just useful for clarity when discussing this topic. Sublime Text doesn’t use this division in any way.

core packages

Sublime Text requires these packages in order to work.

shipped packages

Sublime Text includes these packages in every installation, though technically they are not required. These shipped packages enhance Sublime Text out of the box. They may have been contributed by users or third parties.

user packages

Packages installed by the user to extend Sublime Text’s functionaility. They are not part of any Sublime Text installation, and always are contributed by users or third parties.

installed packages

Any package that, if deleted, Sublime Text will be able to restore.

Let’s emphasize again that you don’t need to memorize this classification.

Also, it’s worth noting that by third party we mainly refer to users of other editors, such as Textmate.

Installation of Packages¶

There are two main ways to install packages:

• .sublime-package files
• version control systems

Ultimately, installing a package is simply a matter of copying a folder containing Sublime Text resources thato Packages. The only thing that changes from one system to another is how you copy these files.

Packages and Magic¶

Sublime Text deals with packages quite simply, without much hidden magic. There are two notable exceptions: Macros defined in any package automatically appear under Tools | Macros | <Your Package>, and snippets from any package appear under Tools | Snippets | <Your Package>.

However, as mentioned at the beginning, Sublime Text follows some rules for packages. For instance, Package/User will never be clobbered during updates to the software.

Restoring Packages¶

Sublime Text keeps a copy of all installed packages so it can recreate them as needed. This means it can reinstall core packages, shipped packages and, potentially, user packages alike. However, only user packages installed as sublime-packages are added to its registry of installed packages. Packages installed in alternative ways will be lost completely if you delete them.

The Installed Packages Directory¶

You will find this folder in the data directory. It contains a copy of every sublime-package installed. It is used to restore Packages.

The Pristine Packages Directory¶

You will find this folder in the data directory. It contains a copy of every shipped and core package. It is used to restore Packages.

与Textmate的兼容性¶

Sublime Text的代码片段与Textmate的代码片段基本兼容。

File Format¶

代码片段文件是有 sublime-snippet 后缀的XML文件。

<snippet>
    <content><![CDATA[]]></content>
    <tabTrigger></tabTrigger>
    <scope></scope>
    <description></description>
</snippet>

content

实际的代码片段内容。

tabTrigger

与这段代码片段关联的隐式按键绑定。最后一个（隐式的）按键式 TAB 。

scope

适用于这段代码片段的作用域选择器

description

为了菜单项准备的用户友好的说明性文字。

转义序列¶

\$

常量 $.

环境变量¶

字域¶

标记代码片段中可以通过 TAB 或 SHIFT + TAB 循环的各个位置。

语法： $1 .. $n

$0

退出标记。当循环到这个标记的时候，编辑器应该返回至正常的编辑模式。默认情况下，Sublime Text在 content 元素内容的结尾位置隐式的添加这个标记。

有相同名字的字域互相映射。

站位符¶

带有默认值的字域。

语法：: ${1:PLACE_HOLDER} .. ${n:PLACE_HOLDER}

字域和站位符可以遇其他的站位符进行组合和嵌套。

替换¶

语法：:

• ${var_name/regex/format_string/}
• ${var_name/regex/format_string/options}

var_name

需要替换的区域：1，2，3……

regex

Perl风格的正则表达式：关于`正则表达式 <http://www.boost.org/doc/libs/1_44_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html>`_ ，请参考Boost库的文档。

format_string

参考Boost库文档的 格式字符串 内容。

options

可选的。可以选择下面的任何一个：

i

忽略大小写敏感的正则。

g

替换所有匹配 regex 的内容。

m

在字符串中不要忽略换行符。

与Textmate的兼容性¶

Sublime Text的语法定义内容基本上与Textmate的语法定义文件是相互兼容的。.

文件格式¶

语法定义文件是以 tmLanguage 作为扩展名的Plist（属性列表）文件。然而，在本文档中，我们将使用 JSON文件来进行讲解，然后再将JSON文件转换为Plist文件。

{ "name": "Sublime Snippet (Raw)",
  "scopeName": "source.ssraw",
  "fileTypes": ["ssraw"],
  "patterns": [
      { "match": "\\$(\\d+)",
        "name": "keyword.ssraw",
        "captures": {
            "1": { "name": "constant.numeric.ssraw" }
         },
        "comment": "Tab stops like $1, $2..."
      },
      { "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
        "name": "keyword.ssraw",
        "captures": {
            "1": { "name": "constant.numeric.ssraw" }
         },
        "comment": "Variables like $PARAM1, $TM_SELECTION..."
      },
      { "name": "variable.complex.ssraw",
        "begin": "(\\$)(\\{)([0-9]+):",
        "beginCaptures": {
            "1": { "name": "keyword.control.ssraw" },
            "3": { "name": "constant.numeric.ssraw" }
         },
         "patterns": [
            { "include": "$self" },
            { "name": "string.ssraw",
              "match": "."
            }
         ],
         "end": "\\}"
      },
      { "name": "constant.character.escape.ssraw",
        "match": "\\\\(\\$|\\>|\\<)"
      },
      { "name": "invalid.ssraw",
        "match": "(\\$|\\>|\\<)"
      }
  ],
  "uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}

name

所定义语法的描述性名称。这个名称显示在Sublime Text界面右下角的下拉菜单中。通常情况下， name 表示的是 编程语言或其他标记语言的名称。

scopeName

语法定义文件起效的顶级坐拥域名称。这个名称一般是 source.<语言名称> 或者 text.<语言名称> 。 如果是在定义编程语言的语法，那么就使用 source 这个名称，否则使用 text 作为名称。

fileTypes

记录适用于这个语法文件的文件扩展名的数组。数组中的每项是去掉”.”的文件扩展名称。

uuid

这个语法定义的唯一标示符。目前被忽略。

foldingStartMarker

目前被忽略，用于标示折叠内容的开始。

foldingStopMarker

目前被忽略，用于标示折叠内容的结束。

patterns

记录与缓冲区中的文字进行匹配的模式的数组。

repository

从模式元素中抽象出来的数组。定义这个数组一方面有助于保持语法定义文件整洁，另一方面也能为像 递归模式这样的功能服务。这个内容是可选的。

模式数组¶

在 patterns 数组中包含的元素。

match

包含下列原素:

match	用于搜索的模式。
name	设置被 match 匹配到的内容所具有的作用域。
comment	可选。只是为了提供信息。
captures	可选。是对 match 的精炼。见下文解释

captures` 内容可以包含 多 组下面要说明的元素对：:

0..n	分组的索引。
name	组内元素具有的作用域。

示例：:

// Simple

{ "name": "constant.character.escape.ssraw",
  "match": "\\\\(\\$|\\>|\\<)"
  "comment". "Sequences like \$, \> and \<"
}

// With captures

{ "match": "\\$(\\d+)",
  "name": "keyword.ssraw",
  "captures": {
      "1": { "name": "constant.numeric.ssraw" }
   },
  "comment": "Tab stops like $1, $2..."
}

include

在仓库中包含其他的语法定义内容或者当前定义的内容。

References:

$self	当前的语法定义。
#itemName	仓库中名为 “itemName” 的内容。
source.js	外部的语法定义。

Examples:

// Requires presence of DoubleQuotedStrings element in the repository.
{ "include": "#DoubleQuotedStrings" }

// Recursively includes the current syntax definition.
{ "include": "$self" }

// Includes and external syntax definition.
{ "include": "source.js" }

begin..end

定义一个可以跨多行的作用域。

包含下面的一些元素：

begin	模式的开始标志。
end	模式的终止标志。
name	整个区域的作用域名称。
beginCaptures	为 begin 准备的 captures。请参考 captures。
endCaptures	为 end 准备的 captures。请参考 captures。
patterns	与正文内容进行配对的 patterns 。
contentName	除掉标志符之后的内容的作用域名称。

Example:

{ "name": "variable.complex.ssraw",
  "begin": "(\\$)(\\{)([0-9]+):",
  "beginCaptures": {
      "1": { "name": "keyword.control.ssraw" },
      "3": { "name": "constant.numeric.ssraw" }
   },
   "patterns": [
      { "include": "$self" },
      { "name": "string.ssraw",
        "match": "."
      }
   ],
   "end": "\\}"
}

仓库¶

在 include 元素中，既可以从 patterns 中引用，也可以从自身引用。请参考 include 章节来了解更多信息。

仓库可以包含下列元素:

• Simple elements:

  "elementName": {
    "match":  "some regexp",
    "name":   "some.scope.somelang"
  }
  

• Complex elements:

  "elementName": {
    "patterns": [
      { "match":  "some regexp",
        "name":   "some.scope.somelang"
      },
      { "match":  "other regexp",
        "name":   "some.other.scope.somelang"
      }
    ]
  }
  

Examples:

"repository": {
  "numericConstant": {
    "patterns": [
      { "match":  "\\d*(?<!\\.)(\\.)\\d+(d)?(mb|kb|gb)?",
        "name":   "constant.numeric.double.powershell",
        "captures": {
          "1": { "name": "support.constant.powershell" },
          "2": { "name": "support.constant.powershell" },
          "3": { "name": "keyword.other.powershell" }
          }
      },
      { "match":  "(?<!\\w)\\d+(d)?(mb|kb|gb)?(?!\\w)",
        "name":   "constant.numeric.powershell",
        "captures": {
          "1": { "name": "support.constant.powershell" },
          "2": { "name": "keyword.other.powershell" }
          }
      }
    ]
  },
  "scriptblock": {
    "begin":  "\\{",
    "end":    "\\}",
    "name":   "meta.scriptblock.powershell",
    "patterns": [
      { "include": "$self" }
    ]
  },
}

转义序列¶

请确保对JSON/XML序列内容进行正确的转义。

文件格式¶

.build-system JSON文件。下面是一个简单的示例：

{
    "cmd": ["python", "-u", "$file"],
    "file_regex": "^[ ]*File \"(...*?)\", line ([0-9]*)",
    "selector": "source.python"
}

选项(Options)¶

cmd

包含需要运行的命令和其参数的数组。如果不指定绝对路径，外部程序会从`PATH`环境变量中搜索。

Windows下GUI会被抑制。

file_regex

可选。获取``cmd``错误输出的正则表达式(Perl风格)。参看下一部分。

line_regex

可选。If file_regex doesn’t match on the current line, but line_regex exists, and it does match on the current line, then walk backwards through the buffer until a line matching file regex is found, and use these two matches to determine the file and line to go to.

selector

可选。当**Tools | Build System | Automatic** 设为``true``时使用。 Sublime Text在此范围内为当前的view选择合适的构建系统。

working_dir

可选。 运行``cmd``前需要切换的当前目录。之后会恢复到原来目录。

encoding

可选。cmd``输出的编码。必须是有效的python编码字符。 默认``UTF-8。

target

可选。 需要运行的Sublime Text命令。默认是``exec`` (Packages/Default/exec.py)。 这个命令接受*.build-system*文件的配置数据。

如果需要覆盖默认的命令来构建，需要在*.sublime-build*文件中指定你特有的变量。

env

可选。 执行``cmd``需要合并进来的环境变量。

可以使用它在不修改系统设置的情况下来添加或者修改环境变量。

shell

可选。如果是``true``, cmd``会通过shell来运行(``cmd.exe, bash…)。

path

可选。这个字符串在运行``cmd``前会替换系统变量：PATH。之后会把`PATH`恢复原值。

可以使用这个选项在不修改系统设置的情况下，添加目录到`PATH`变量中。

variants

可选。 字典列表，用于覆盖主构件系统的选项。Variant的``name`会显示在构建系统选择时命令面板上。

name

只在variant内有效 (参看``variants``)。标识variant构建系统。如果``name``是*Run*，这个variant将显示在**Tools | Build System**菜单下，并且绑定到*Ctrl + Shift + B*上。

{
    "cmd": ["ant"],
    "file_regex": "^ *\\[javac\\] (.+):([0-9]+):() (.*)$",
    "working_dir": "${project_path:${folder}}",
    "selector": "source.java",

    "windows":
    {
        "cmd": ["ant.bat"]
    }
}

{
    "selector": "source.python",
    "cmd": ["date"],

    "variants": [

        { "cmd": ["ls -l *.py"],
          "name": "List Python Files",
          "shell": true
        },

        { "cmd": ["wc", "$file"],
          "name": "Word Count (current file)"
        },

        { "cmd": ["python", "-u", "$file"],
          "name": "Run"
        }
    ]
}

构建系统变量¶

构建系统会在*.sublime-build*文件中扩展下面这些变量：

${project_name:Default}

${file/\.php/\.txt/}

运行构建系统¶

从**Tools | Build System**选择期望的构建系统，然后选择**Tools | Build**或者``F7``。

构建系统故障排除¶

构建系统会在系统变量`PATH`路径下搜寻可执行文件，除非你指定了特定的可执行目录。所以，`PATH`系统变量要配置正确。

有些系统中，`PATH`变量的值在终端中与图形应用中会有不同。所有，尽管你在命令行中使用的构建命令运行正常，但也有可能在Sublime Text运行不正常。这跟用户的shell配置有关。

要解决这个问题，所有要确保你设定的`PATH`是期望的，让Sublime Text这种图形界面程序可以找到。参考下面的连接获取更多信息。

另外，也可以使用*.sublime-build*文件中的``path``配置项来指定`PATH`，不过这只在构建系统运行期间有效，运行完之后会恢复系统原来的值。

文件格式¶

对于按键绑定的配置存储于后缀为 .sublime-keymap 的文件中，文件中记录的是JSON内容。所有按键绑定 配置文件都需要按照如下模式命名： Default (<platform>).sublime-keymap 。否则，Sublime Text 将忽略这些文件。

{ "keys": ["shift+enter"], "command": "insert_snippet", "args": {"contents": "\n\t$0\n"}, "context":
        [
                { "key": "setting.auto_indent", "operator": "equal", "operand": true },
                { "key": "selection_empty", "operator": "equal", "operand": true, "match_all": true },
                { "key": "preceding_text", "operator": "regex_contains", "operand": "\\{$", "match_all": true },
                { "key": "following_text", "operator": "regex_contains", "operand": "^\\}", "match_all": true }
        ]
}

命令模式¶

Sublime Text提供一个称为 command_mode （命令模式）的设置项，启用这个设置可以阻止按键内容 被送往缓冲区。这个设置项在模拟Vim的模式功能的时候很有用处。

可绑定的按键¶

按键可以通过字面值或者名字来指定。你可以在下面找到一个有效名称的列表:

• up
• down
• right
• left
• insert
• home
• end
• pageup
• pagedown
• backspace
• delete
• tab
• enter
• pause
• escape
• space
• keypad0
• keypad1
• keypad2
• keypad3
• keypad4
• keypad5
• keypad6
• keypad7
• keypad8
• keypad9
• keypad_period
• keypad_divide
• keypad_multiply
• keypad_minus
• keypad_plus
• keypad_enter
• clear
• f1
• f2
• f3
• f4
• f5
• f6
• f7
• f8
• f9
• f10
• f11
• f12
• f13
• f14
• f15
• f16
• f17
• f18
• f19
• f20
• sysreq
• break
• context_menu
• browser_back
• browser_forward
• browser_refresh
• browser_stop
• browser_search
• browser_favorites
• browser_home

让按键映射井井有条¶

Sublime Text自带的按键组合存放在 Packages/Default 目录下。其他包组可以包含它们特有的按键 映射文件。对于你自己的键位映射设置而言，推荐的文件存放地址是 Packages/User 目录。

请参考 排序与优先级顺序 以了解关于Sublime Text排序文件并进行合并的更多信息

国际化键盘¶

根据Sublime Text将按键名称与物理按键进行映射的方式，此二者在不同平台上可能有不同的配对。

常见问题解答¶

使用 sublime.log_commands(flag) 开启命令日志。这对于调试按键映射有所帮助。

全局设置项¶

Target file: Global.sublime-settings. 对应文件： Global.sublime-settings 。

theme

系统使用的主题文件。接受主题文件的名称（例如： Default.sublime-theme ）。

remember_open_files

设置Sublime Text启动时是否需要打开上次关闭时打开了的缓冲区。

folder_exclude_patterns

与匹配模式相符的目录将不会出现在侧边栏、快速跳转面板等位置。

file_exclude_patterns

与匹配模式相符的文件将不会出现在侧边栏、快速跳转面板等位置。

scroll_speed

如果把值设为 0 ，将禁止平滑滚动。取 0 到 1 之间的数值将使滑动变的比较缓慢，取大于 1 的值使得滑动更加迅速。

show_tab_close_buttons

如果设置为 false ，通常情况下就不会显示标签页的关闭按钮，只有当鼠标移动到标签上时才显示。

mouse_wheel_switches_tabs

如果设置为 true ，在标签区域滑动鼠标滚轮会触发标签页之间的切换。

open_files_in_new_window

仅在OS X平台有效。当用户从Finder中开打文件，或者把文件拖拽到dock面板的图标上，这个设置项将决定 是否需要创建一个新窗口。

文件设置项¶

Target files: Base File.sublime-settings, <file_type>.sublime-settings. 对应文件： Base File.sublime-settings， <file_type>.sublime-settings。

文件格式 (.sublime-commands 文件)¶

如下是来自 Packages/Default/Default.sublime-commands 的实例:

[
    { "caption": "Project: Save As", "command": "save_project_as" },
    { "caption": "Project: Close", "command": "close_project" },
    { "caption": "Project: Add Folder", "command": "prompt_add_folder" },

    { "caption": "Preferences: Default File Settings", "command": "open_file", "args": {"file": "${packages}/Default/Base File.sublime-settings"} },
    { "caption": "Preferences: User File Settings", "command": "open_file", "args": {"file": "${packages}/User/Base File.sublime-settings"} },
    { "caption": "Preferences: Default Global Settings", "command": "open_file", "args": {"file": "${packages}/Default/Global.sublime-settings"} },
    { "caption": "Preferences: User Global Settings", "command": "open_file", "args": {"file": "${packages}/User/Global.sublime-settings"} },
    { "caption": "Preferences: Browse Packages", "command": "open_dir", "args": {"dir": "$packages"} }
]

caption

显示在命令面板中的标题.

command

执行的命令.

args

传给 command 的参数。 需要注意的是，要定位包所在目录，需要使用 ${packages} 或 $packages。由于底层的实现不同，这与在编辑器的其他区域的用法略有不同。

如何使用命令面板¶

1. Press Ctrl+Shift+P
2. 选择命令

显示的选项会根据上下文不同有所区别，并不是在任何时候都会显示所有选项。

文件格式¶

补全信息是以 .sublime-completions 作为扩展名的JSON文件。

补全列表的结构¶

scope

控制补全是否应该在这个文件中发挥作用。参考 作用域与作用域选择子 来了解更多信息。

completions

补全的数组。

下面是从html补全列表中截取出来的一部分:

{
        "scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",

        "completions":
        [
                { "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
                { "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
                { "trigger": "acronym", "contents": "<acronym>$0</acronym>" }

        ]
}

补全的类型¶

补全的来源¶

用户可以控制的补全来源包括:

• .sublime-completions
• EventListener.on_query_completions()

除此之外，其他在最终补全列表中可以显示的内容包括：

• Snippets
• Words in the buffer

补全列表¶

要使用补全列表需要:

• Press Ctrl+spacebar 来打开补全列表
• Optionally, 再次 press Ctrl+spacebar 来选择下一个候选项
• Press Enter or Tab 来确认选择

代码片段以如下形式出现在补全列表中：<tab_trigger> : <name> 。对于其他补全项，你只能看到要被 插入的文本。

当补全列表被缩减到只有一个候选项时，系统就会绕开自动补全对话框，根据之前介绍的优先级，对应内容 会被直接插入。

为补全列表启用或禁用Tab补全¶

tab_completion 选项默认是 true 。如果你想停止 Tab 键对最可能选项的索引功能， 就把这个值设置为 false 。这个设置项对定义在 .sublime-snippet 文件中的触发器没有效果， 因此按下 Tab 时，代码片段一定会被插入。

当 tab_completion 选项开启的时候，上面介绍的优先级顺序仍然有效，但是，与补全列表不同的是，

插件放到哪里¶

Sublime Text 2在以下这些目录中寻找可用插件：

• Packages
• Packages/<pkg_name>

存放在 Packages 更深层次的目录结构中的插件不会被加载。

任何插件都应该又自己单独的目录，而不应该直接放在 Packages 目录下。

命令名称的命名规则¶

Sublime Text 遵循 CamelCasedPhrases 命名规则来定义命令类，同时用 Command 作为后缀。

然而，Sublime Text将类名从 CamelCasedPhrases 形式自动转换成 camel_cased_phrases 。 举例来说， ExampleCommand 将被转换为 example ，而 AnotherExampleCommand 将 转换为 another_example

对于类定义名称，可以使用 CamelCasedPhrasesCommand 命名方式；要从API中调用一个命令，请使用 标准化后的名称（ snake_cased_phrases ）。

命令类型¶

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

WindowCommand 类的实例都有一个 .window 属性，指向创建他们的那个窗口实例。于此类似， TextCommand 类的实例拥有 .view 属性。

如何利用API调用命令¶

根据命令的类型来选择对 View 、 Window 或者 sublime 的引用，然后通过 object.run_command('command_name') 来调用。 除此之外, 你可以用字典作为参数，字典中的键就是要传给 command_name 的参数名称:

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

命令的参数¶

用户提供给命令的所有参数都必须是有效的JSON类型。只有Sublime Text可以给命令传递其他类型的参数

（例如修改对象，视图实例等等）。

Text Commands 和 edit 对象¶

文本命令的两个较为重要的API是 view.begin_edit() 和 view.end_edit() 。 其中 view.begin_edit() 可以接受一个可选的命令名称和可选的参数字典；而 view.end_edit() 用来结束编辑过程。

在修改过程中发生的所有动作都被整合成一个单一的撤销动作。当编辑过程结束的时候，类似与 on_modified 和 on_selection_modified() 的回调函数会被触发。

有一点非常重要，每次调用 view.begin_edit() 之后必须调用 view.end_edit() 方法，否则 缓冲将处于一种不一致状态。在不匹配发生时，系统将尝试自动进行修正，但是这种自动修正的发生频率并 没有你想象的那么多，同时会在控制台输出一条警告信息。换句话说，你应该始终使用 try..finally 来包裹代码快。

传递给 begin_edit() 的命令名称用于重复、宏录制以及撤销/重复过程中的动作描述。如果你在 TextCommand 外面做修改，你就不该指定命令名称。

你可以在开始的时候创建一个修改对象，然后调用了一个方法又创建了另外的一个修改对象：只有当最外层 的修改对象执行了 end_edit() 方法之后，系统才认为整个修改都完成了。

与群组修改类似，你也可以使用修改对象把对选中文本做的修改组合成一个群组，对它们的修改只要一步就 能撤销。

对事件的响应¶

任何 EventListener 的子类都能够响应事件。对于任何一个类，不能同时继承 EventListener 和其他任何的命令类。

Python和标准库¶

Sublime Text集成了一个精简版的标准库。被裁剪掉的模块包括 Tkinter ， multiprocessing 以及 sqlite3 。

自动插件重载¶

当你对插件做修改的时候（比如你正在修改一个 .py 文件），Sublime Text会自动加载包中的顶级 Python模块。值得注意的是Python的子模块不会被自动重新加载；这一点在插件开发中可能会产生一些挺 奇葩的问题。一般来说，当你对插件文件做修改之后，最好重启以下Sublime Text，这样能保证你做的修 改能发挥作用。

多线程¶

只有 .set_timeout() 方法可以安全的从其他线程调用。

Exploring the API¶

快速查看API的方法：

1. 将 Packages\Default (Preferences | Browse Packages…) 添加到你的项目中.
2. 按下组合键 CTRL + SHIFT + F
3. 在 In Files: 栏中输入 *.py
4. 检查 Use Buffer 选项
5. 搜索 API 名字
6. 按 F4
7. 学习相关的源代码

概述¶

命令列表的整理仍在进行中。

关于命令参数中的路径¶

有些命令把路径作为参数。这些命令中，有些支持代码片段那样的语法，有些则不支持。第一中类型的命令 可以接受类似 ${packages}/SomeDir/SomeFile.Ext 这样的参数，而第二种类型的命令可以接受类似 Packages/SomeDir/SomeFile.Ext 这样的参数。

大体上来说，较新引入的命令支持类似代码片段的语法。

通常情况下，认为命令参数中的相对路径是相对与 Data 目录来说的。

命令列表¶

build

运行某个构件系统。

• variant [String]: 可选参数。要运行配置的名称

run_macro_file

运行一个 .sublime-macro 文件。

• file [String]: 宏文件路径。

insert_snippet

从字符串或者 .sublime-snippet 文件中插入一个代码片段。

• contents [String]: 要插入的代码片段的字符串内容。
• name [String]: 要插入的 .sublime-snippet 文件的路径。

insert

插入一个字符串。

• characters [String]: 要插入的字符串内容。

move

根据指定的单位移动光标。

• by [Enum]: 可选值: characters, words, word_ends, subwords, subword_ends, lines, pages, stops.
• forward [Bool]: 在缓冲区中向前或向后移动。
• word_begin [Bool]
• empty_line [Bool]
• punct_begin [Bool]
• separators [Bool]

move_to

将光标移动到指定位置。

• to [Enum]: 可选值: bol, eol, bof, eof, brackets.
• extend [Bool]: 是否扩展选择内容。默认值是 false 。

new_window

打开一个新的窗口。

close_window

关闭当前活跃窗口。

switch_file

在有相同文件名、不同扩展名的两个文件之间进行切换。

• extensions [[String]]: 切换可以发生的文件扩展名（不包括点号）。

close

关闭当前视图。

close_file

关闭当前视图，在某些情况下关闭整个应用程序。 XXX Sounds kinda wrong.

save

保存当前激活的文件。

prompt_save_as

提示输入新的文件名称并保存。

toggle_sidebar

开启或关闭侧边栏。

toggle_full_screen

开启或退出全屏模式。

toggle_distraction_free

开启或退出免打扰模式。

left_delete

删除光标前的那个字符

right_delete

删除光标后的那个字符。

undo

撤销上次操作。

redo

重做上次撤销的操作。

redo_or_repeat

再次执行上次的动作。

soft_undo

先移动到编辑位置再进行撤销操作。

soft_redo

先移动到编辑位置再进行重做操作。

cut

把当前选中的文字从缓冲区中移除，并送到系统剪贴板中。换句话说，执行剪切操作。

copy

把当前选中的文字送到系统剪贴板中。

paste

把剪贴板中的内容插入到光标后。

paste_and_indent

把剪贴板中的内容插入到光标后同时根据上下文进行缩进。

select_lines

在当前选择的内容中添加一行。

• forward [Bool]: 添加下一行还是上一行。默认值是 true 。

scroll_lines

在视图中滚动行。

• amount [Float]: 正值向下滚动，负值向上滚动。

prev_view

切换到上一个视图。

next_view

切换到下一个视图。

next_view_in_stack

切换到最近的活跃视图。

previous_view_in_stack

切换到最近活跃视图的前一个活跃视图。我不认为这种说法非常确切，这么说甚至是不正确的。

select_all

选择视图的全部内容。

split_selection_into_lines

不出所料的，把当前的选择切散成不同行。

single_selection

把多重选择整合成单一选择。

clear_fields

跳出活跃代码片段域的选择。

hide_panel

隐藏当前活跃面板。

• cancel [Bool]: 当面板打开的时候恢复它之前选择的内容。（仅对增量搜索面板有效。）

hide_overlay

隐藏覆盖控件。使用 show_overlay 命令打开覆盖控件。

hide_auto_complete

隐藏自动补全列表。

insert_best_completion

插入根据当前上下文能推断出的最佳补全内容。 XXX 可能没什么用

• default [String]: 插入根据当前上下文能推断出的最佳补全内容。 XXX 可能没什么用

replace_completion_with_next_completion

XXX 对用户来说没什么用。 XXX

reindent

XXX ??? XXX 译者注：重新进行缩进操作，常用于整理文件缩进。）

indent

增加缩进。

next_field

将光标移动到下一个代码片段中的可修改区域。

prev_field

将光标移动到上一个代码片段中的可修改区域。

commit_completion

向缓冲区中插入自动补全列表中当前选中项的内容。 XXX 对用户来说没很么用。

unindent

取消缩进。

toggle_overwrite

开启关闭覆盖插入选项。

expand_selection

将选择内容扩展到预定义的边界。

• to [Enum]: 可选值: bol, hardbol, eol, hardeol, bof, eof, brackets, line.

find_under_expand

根据当前选中的内容增加一个新的选择或者把选择项扩展到当前单词。

close_tag

为当前内部文本添加适当的标签。

toggle_record_macro

开始或关闭宏录制器。

run_macro

运行宏缓冲区中存储的宏脚本。

show_overlay

显示请求的覆盖控件。使用 hide_overlay 命令来隐藏覆盖控件。

• overlay [Enum]:

  要显示的覆盖控件的类型。可选值：

  • goto: 显示 `Goto Anything（快速跳转 <http://docs.sublimetext.info/en/latest/file_management/file_management.html#goto-anything>``_ 控件。
  • command_palette: 显示 命令面板.

• show_files [Bool]: 如果显示快速跳转面板，开始的时候显示文件列表，而不是显示一个空的控件。

• text [String]: 放到覆盖控件中的初始值。

show_panel

显示面板。

• panel [Enum]: 可选值: incremental_find, find, replace, find_in_files, console
• reverse [Bool]: 在缓冲区中是否后向搜索内容。
• toggle [Bool]: 当面板已经可见时，是否隐藏面板。

find_next

找到当前搜索内容的下一个匹配项。

find_prev

找到当前搜索内容的上一个匹配项。

find_under

找到与当前选中内容或光标所在位置档次匹配的下一个内容。

find_under_prev

找到与当前选中内容或光标所在位置档次匹配的上一个内容。

find_all_under

选中与当前选择内容或光标所在位置单词匹配的所有内容。

slurp_find_string

复制当前选中内容或当前单词到搜索面板中的 “find” 域。

slurp_replace_string

复制当前选中内容或当前单词到搜索域替换面板中的 “replace” 域。

next_result

移动到下一个搜索到的结果。

prev_result

移动到上一个搜索到的结果。

toggle_setting

修改布尔型设置项的值。

• setting [String]: 要修改的设置项的名称。

next_misspelling

移动到下一个错误拼写的单词的位置。

prev_misspelling

移动到上一个错误拼写的单词的位置。

swap_line_down

交换当前行与下一行。

swap_line_up

交换当前行与上一行。

toggle_comment

为当前行添加或取消注释。

• block [Bool]: 为当前行添加或取消注释。

join_lines

把当前行与下一行连接起来。

duplicate_line

重复当前行内容。

auto_complete

打开自动补全列表。

replace_completion_with_auto_complete

XXX 对用户来说没什么用。 XXX

show_scope_name

在状态栏中显示光标所在作用域的名称。

exec

异步运行一个外部进程。

XXX 为所有选项添加文档。

transpose

移动内容。

sort_lines

对行进行排序。

• case_sensitive [Bool]: 对行进行排序。

set_layout

XXX

focus_group

XXX

move_to_group

XXX

select_by_index

XXX

next_bookmark

选择下一个被标记的区域。

prev_bookmark

选择上一个被书签标记的区域。

toggle_bookmark

对活跃区域设置书签或取消书签。（在区域API中使用 "bookmarks" 作为键可以访问书签内容。）

clear_bookmarks

清楚所有书签。

select_all_bookmarks

选择所有被书签标记过的区域。

wrap_lines

环绕行。默认情况下，在第一个标尺所在的列进行环绕。

• width [Int]: 设置环绕开始的列坐标。

upper_case

把选择的内容改成大写。

lower_case

把选择的内容改成小写。

title_case

把选择区的首字母大写，其它的字母都小写。

swap_case

转换选择区的每个字母的大小写。(就是大写变小写，小写变大写)

set_mark

XXX

select_to_mark

XXX

delete_to_mark

XXX

swap_with_mark

XXX

yank

XXX

show_at_center

XXX

increase_font_size

放大字体。

decrease_font_size

缩小字体。

fold

XXX

unfold

XXX

fold_by_level

XXX

context_menu

显示上下文菜单。

编辑¶

导航/快速跳转¶

通用快捷键¶

查找/替换¶

标签页(Tabs)¶

分割窗口¶

书签¶

文本操作¶

编辑¶

导航/快速跳转¶

通用快捷键¶

查找/替换¶

标签页(Tabs)¶

分割窗口¶

书签¶

文本操作¶