目录

1.1.11 参考

优质
小牛编辑
140浏览
2023-12-01

本节包含 Sublime Text 的一些简要的技术,它的目的是给想要更改 Sublime Text 默认行文的高级用户提供快速参考。

语法定义

Sublime Text 3084 版本加入了一种新的语法定义格式,扩展名为.sublime-syntax。目前只在 开发版 可用。

和 Textmate 兼容

通常情况,Sublime Text 语法定义和 Textmate 语言文件是相兼容的。

文件格式

Textmate 语法定义是扩展名为 tmLanguage 的 Plist 文件。然而为了方便,本参考中用 YAML 来代替。

此外,Sublime Text 也识别hidden-tmLanguage 为扩展名的文件,“文件内查找”会用到这个东西。缺点是不能被其它语言的 import 语句引入。

---
name: Sublime Snippet (Raw)
scopeName: source.ssraw
fileTypes: [ssraw]
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9

patterns:
- comment: Tab stops like $1, $2...
  name: keyword.other.ssraw
  match: \$\d+

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

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

- name: constant.character.escape.ssraw
  match: \\[$<>]

- name: invalid.illegal.ssraw
  match: '[$<>]'
  ...
  • name 语法定义的描述性名称。显示在 Sublime Text 界面语法定义菜单右下角的下拉列表中。

  • scopeName 此语法定义最顶层作用域的名称,不管是source.<lang>还是text.<lang>。用source来表示编程语言,用text表示标记性语言或其它东西。

  • fileTypes 可选。这是一个文件扩展名(不带前面的点)的列表。当打开这些类型的文件时,Sublime Text 将自动激活其语法定义。

  • uuid 语法定义的唯一识别码。

  • patterns 你的匹配模式的容器,数组格式。

  • repository 可选。从 patterns 中抽象出来的模式数组。对于保持语法定义的整洁或是对于复用模式、递归调用等一些特殊用途来说很有用。

匹配模式的数组

patterns 数组中的元素。

  • match 包含以下元素:

    | match | 搜索的匹配项 | | ---------- | :-------------------------------------------- | | name | 可选,安排给match匹配到的内容的作用域名称。 | | comment | 可选,注释。 | | captures | 可选,让match更加细致。 |

    captures可以包含下列元素项的n0表示全部匹配):

    | 0..n | 引用分组的名称,必须是字符串。 | | ------ | ------------------------------ | | name | 组的作用域 |

    例如:

    # Simple
    
    - comment: Sequences like \$, \> and \<
      name: constant.character.escape.ssraw
      match: \\[$<>]
    
    # With captures
    
    - comment: Tab stops like $1, $2...
      name: keyword.other.ssraw
      match: \$(\d+)
      captures:
        '1': {name: constant.numeric.ssraw}
    
  • include 包含 repository 中的条目、其它语法定义或是当前这个。

    参考:

    | $self | 当前语法定义 | | --------- | ------------------------ | | #itemName | repository 中的 itemName | | source.js | 外部语法定义 |

    例如:

    # Requires presence of DoubleQuotedStrings element in the repository.
    - include: '#DoubleQuotedStrings'
    
    # Recursively includes the complete current syntax definition.
    - include: $self
    
    # Includes and external syntax definition.
    - include: source.js
    
  • begin..end 定义多行文本的作用域。

    包含下列元素(只有beginend是必选的):

    | name | 包含标记的内容的作用域名称 | | --------------- | ---------------------------- | | contentName | 不包含标记的内容的作用域名称 | | begin | 匹配的开始标识 | | end | 匹配的结束标识 | | name | 全部区域的作用域 | | beginCaptures | 参看 captures | | endCaptures | 参看 captures | | patterns | 匹配项列表,用来匹配内容 |

    例如:

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

Repository

可以从 patterns 或其自身的 include 元素中被引用。

repository 可以包含下列元素:

repository:

  # Simple elements
  elementName:
    match: some regexp
    name:  some.scope.somelang

  # Complex elements
  otherElementName:
    patterns:
    - match: some regexp
      name:  some.scope.somelang
    - match: other regexp
      name:  some.other.scope.somelang

例子:

repository:
  numericConstant:
    patterns:
    - name: constant.numeric.double.powershell
      match: \d*(?<!\.)(\.)\d+(d)?(mb|kb|gb)?
      captures:
        '1': {name: support.constant.powershell}
        '2': {name: support.constant.powershell}
        '3': {name: keyword.other.powershell}
    - name: constant.numeric.powershell
      match: (?<!\w)\d+(d)?(mb|kb|gb)?(?!\w)
      captures:
        '1': {name: support.constant.powershell}
        '2': {name: keyword.other.powershell}

  scriptblock:
    name: meta.scriptblock.powershell
    begin: \{
    end: \}
    patterns:
    - include: $self

转义序列

在需要的时候确保对 JSON/XML 进行转义。

对于 YAML,请确保你没有使用一个不带引号的字符串作为开始。

示例将无法按预期生效。

match: [aeiou]

include: #this-is-actually-a-comment

match: "#"\w+""

配色方案

概述

用来对代码进行颜色高亮。例如:背景色、前景色...

文件格式

扩展名为.tmTheme的文件,文件格式继承自 Textmate。

注:Sublime Text 使用.tmTheme作为扩展名来保持与 Textamte 相兼容。有一个容易混淆的地方是,Sublime Text 还有一个用户界面(UI)主题的概念。UI 主题是用来改变编辑器外观的。一定要记住这两个不是一个东西。 一般来说,创建一个 UI 主题要比创建一个配色方案要复杂的多。

存储位置

你可以把配色方案文件放到 Packages 下的任何地方(甚至是深层次的嵌套)。

约定配色方案都用 Color Scheme作为前缀,如:Color Scheme - Default

可选配色方案在菜单栏中的 Preferences → Color Scheme

文件结构

配色方案文件是基于 Property List 格式的。所有配色方案最外层的结构都是一致的。

颜色的写法支持: #RRGGBB#RGB

大多数控制颜色的元素都支持 alpha 通道:#RRGGBBAA

配色方案文件最外层元素
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Monokai</string>
   <key>settings</key>
   <array>
   ... INSERT AWESOME COLORS HERE ...
   </array>
   <key>uuid</key>
   <string>D8D5E82E-3D5B-46B5-B38E-8C841C21347D</string>
</dict>
</plist>

name 可选,配色方案的名称,Sublime Text 会忽视。

uuid 可选,唯一的标识符,Sublime Text 会忽视。

设置的子元素

Sublime Text 支持以下几种配色方案的设置:

  • 全局设置

    此处的设置会影响全局,在 <array>中的<dict>中设置。

    <array>
       <dict>
          <key>settings</key>
          <dict>
             <key>background</key>
             <string>#272822</string>
             <key>caret</key>
             <string>#F8F8F0</string>
             ...
          </dict>
       </dict>
    ...
    </array>
    
  • 按类型排序的全局设置

    • 普通

      foreground 视图的前景色。

      background 视图的背景色。

      invisibles 忽略。

      caret 插入符的颜色。

      lineHighlight 插入符所在行的颜色,只有 higlight_line 设置成true才有效。

    • 括号

      bracketContentsForeground 插入符在括号中时,括号中文字的颜色。需要设置match_bracketstrue

      bracketContentsOptions 当光标在括号时控制某些选项,需要设置match_bracketstrue

      选项: underlinestippled_underlinesquiggly_underlineunderline表示文字应该用指定颜色绘制,而不仅仅是下划线。

      bracketsForeground 插入符挨着括号时括号的颜色。需要设置match_bracketstrue

      bracketsOptions 当光标挨着括号时控制某些选项,需要设置match_bracketstrue

      选项: underlinestippled_underlinesquiggly_underlineunderline表示文字应该用指定颜色绘制,而不仅仅是下划线。

    • 标签

      tagsForeground 插入符挨着标签时标签的颜色。需要设置match_tagstrue

      tagsOptions 当光标挨着标签时控制某些选项,需要设置match_tagstrue

      选项: underlinestippled_underlinesquiggly_underlineunderline表示文字应该用指定颜色绘制,而不仅仅是下划线。

    • 查找

      findHighlight 匹配结果的背景色。

      findHighlightForeground 匹配结果的前景色。

    • Gutter(指显示行号那个区域)

      gutter gutter 背景色。

      gutterForeground gutter 前景色。

    • 选择块

      selection 选中区域文字颜色。

      selectionBackground 选中区域背景色。

      selectionBorder 选中区域的边框颜色。

      inactiveSelection 非活动部分的颜色。

    • 引导

      guide 引导的颜色。

      activeGuide 有插入符的行的引导颜色。indent_guide_options需设置为draw_active

      stackGuide 当前引导的父级引导颜色。

      indent_guide_options需设置为draw_active

    • 高亮区域

      highlight 带有sublime.DRAW_OUTLINED标签时通过 sublime.add_regions() 添加的区域的背景色。

      highlightForeground 带有sublime.DRAW_OUTLINED标签时通过 sublime.add_regions() 添加的区域的前景色。

    • 阴影

      shadow 滚动时阴影的颜色。

      shadowWidth 滚动时阴影的宽度。

  • 范围设置

    特殊作用域的设置。

    <array>
       ...
       <dict>
          <key>name</key>
          <string>Comment</string>
          <key>scope</key>
          <string>comment</string>
          <key>settings</key>
          <dict>
             <key>foreground</key>
             <string>#75715E</string>
          </dict>
       </dict>
       ...
    </array>
    

    name 名称。

    scope 作用域名称。

    settings 设置的容器。合法的设置:

    fontStyle 字体样式,选项:bolditalic

    foreground 前景色。

    background 背景色。

Sublime Text 中有关配色的设置

color_scheme 配色方案文件的路径(如:Packages/Color Scheme - Default/Monokai.tmTheme)。

构建系统

利用构建系统,你无需离开 Sublime Text 就可以通过运行外部程序来查看文件的效果。

基本信息

构建系统只需要一个 .sublime-build 文件,更高级的构建系统最多也只会包含下列三部分:

  • 一个.sublime-build 文件(JSON 格式的配置文件)
  • 可选,一个驱动构建进程的自定义 Sublime Text 命令(Python 代码)
  • 可选,一个外部可执行文件(脚本或是二进制代码)

.sublime-build 文件

.sublime-build 文件包含了 JSON 对象、各种选项和环境配置数据作为配置数据。每个 .sublime-build 文件通常和特定作用域中相应文件类型相关联(如source.python)。

文件名就代表了构建系统,每当你可以选择构建系统时它就会展示出来。

例子

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

构建系统中使用的 Sublime Text 命令

当你运行 Sublime Text 中默认的构建任务(Ctrl+B)时,一个 Sublime Text 命令就会接收到 .sublime-build 中指定的配置数据,然后就会构建文件,通常情况,它会调用一个外部程序。构建系统中默认使用的命令 是 exec,这个命令也可以被重写。

重写构建系统默认执行命令

构建系统默认是通过Packages/Default/exec.py执行一个exec命令,这个命令只需要把配置数据转发到外部程序即可异步运行了。

.build-system 文件中使用target选项就可以重写 exec 命令了。详细查看下节配置。

调用外部程序

构建系统可以调用外部程序来处理文件,这个外部程序可以是 shell 脚本、标准化的 utility(如maketidy)等等。通常情况,外部程序在接收配置数据的同时也会接收文件或目录的路径。

注意:构建系统可以但是没必要调用一个外部程序,一个构建系统可以被完全地实现成一个 Sublime Text 命令。

配置

⚠️ 开发版本中构建系统章节正在被重新调整,所以下面的内容可能已经过时了。

概述

Sublime Text 中的构建系统框架足够灵活所以它可以容纳大量的构建场景。如果默认配置满足不了你的需求,你可以通过以下两种主要方式实现你自己的构建系统:

  • 自定义的target 命令(仍然使用默认的构建系统框架)
  • 新的插件(与默认构建系统无关)
构建系统中的 Meta 选项

这是所有构建系统都能够理解的标准选项,这些选项由 Sublime Text 内部使用。 target 选项不接收任何选项。

target(可选)一个 Sublime Text WindowCommand,默认为 execPackages/Default/exec.py)。此命令接收所有在 .sublime-build 文件中指定的目标命令参数。用来覆盖构建系统的默认命令,注意,如果你 选择了覆盖构建系统的默认命令,你可以把任意数量的额外选项添加到.sublime-build中。

selector(可选) Tools | Build System | Automatic设置为 true,Sublime Text 使用这个范围选择器来为当前活动视图找到合适的构建系统。

windows, osx and linux(可选)用于操作系统有选择性的应用选项,特定的操作系统的值将覆盖默认值,列出的项中每一个都接受一个字典选项。

variants(可选)选项中的一个字典列表,如果构建系统的选择器匹配了当前活动的文件,出现在命令面板的 Variant 的名称就可以方便地进行调用。可以在同一个 .sublime-build 文件中指定多个构建系统任务。

name (可选) 只有在 variant 中才合法。标识构建系统任务,如果name是“Run”,variant 将会显示在 Tools | Build System下。Sublime Text 自动绑定“Run”任务到 Ctrl+Shift+B

特定平台选项 windowsosxlinux 使你可以在构建系统中添加指定平台的数据。例如:

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

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

这个例子中,除 Windows 外的其他平台将执行ant命令,而 Windows 将执行ant.bat

Variants

例子:

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

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

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

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

Ctrl+B 将执行date命令,Crtl+Shift+B将会运行 Python 解析器,其余的将会在构建系统被激活时已Build: name的形式出现在命令面板中。

捕获构建系统的结果

当构建系统输入文本到结果视图中时,你可以捕获结果数据以便启用结果导航。注:结果也被称作错误

参照下面的视图设置result_file_regex 一个 Perl 风格的正则表达式,捕获结果视图中错误信息中的资格字段,分别是:文件名、行数、列数、错误信息。

result_line_regex result_file_regex 不匹配,而result_line_regex存在且匹配当前行,在缓存中向后查找知道匹配了result_file_regex,这两个综合起来来确定将要跳转到哪个文件中的哪一行。

result_base_dir 用来寻找出错的文件。

构建系统变量

.sublime-build 文件中有以下变量:

$file_path当前文件的路径,如:C:\Files
$file当前文件的绝对路径,如:C:\Files\Chapter1.txt
$file_name当前文件的文件名, 如:Chapter1.txt
$file_extension当前文件的扩展名,如:txt
$file_base_name当前文件的名字部分,如:Document
$folder当前项目中被打开的第一个文件夹路径。
$project当前项目的绝对路径。
$project_path当前项目的路径。
$project_name当前项目的名字。
$project_extension当前项目的扩展名部分,
$project_base_name当前项目的名字部分。
$packagesPackages文件夹的绝对路径。
运行构建系统

Tools | Build System选择构建系统,然后选择Tools | Build。另外,你也可以用下列快捷方式:

Ctrl+B运行默认构建任务
F7运行默认构建任务
Ctrl+Shift+B运行 “Run” 构建任务
Ctrl+Break取消当前的构建任务

exec命令的参数

cmd shell_cmd为空时则必需。否则将会被 shell_cmd覆盖。包含将运行的命令及其参数的数组。如果不指定一个绝对路径,将会在PATH中搜索外部的程序。最终将会调用subprocess.Popen(cmd)

shell_cmd cmd为空时则必需。否则将会被 cmd覆盖。一个指定将运行的命令及其参数的字符串,最终将会调用subprocess.Popen(shell_cmd, shell=True)

working_dir 可选。运行cmd之前改变当前目录的指向目录,当前目录的原始值将会在之后恢复。

encoding 可选。输出cmd的编码,必须是合法的 Python 编码格式,默认是UTF-8

env 可选。传递给cmd之前将与当前进程进行合并的环境变量的字典。使用这个参数你就可以在不改变系统设置的情况编辑环境变量。

shell 可选。值为true时,cmd将通过 shell(cmd.exebash等等)运行。如果使用了shell_cmd,则此选项无效。

path 可选。cmd子进程使用的PATH。使用这个参数就可以在不改变系统设置的情况添加字典到PATH中。

file_regex 可选。给结果视图设置 result_file_regex

line_regex 可选。给结果视图设置 result_line_regex

syntax 可选。如果设置了,就会使构建系统的输入有色彩。

故障诊断

构建系统将会在 PATH中寻找可执行程序,所以你的 PATH必须设置正确。在一些操作系统中,终端和图形化的应用程序中的PATH可能不一样,因此,Sublime Text 能否正常工作取决于你如何打开它。为了解决这个问题 ,确保你设置了 PATH 以便应用程序可以找到它。另外,你也可以在 .sublime-build 文件中使用 path 选项覆盖可执行程序的 cmd中指定的PATH

按键绑定

按键绑定把按键映射到命令。

文件格式

.sublime-keymap 文件,JSON 格式。可以防止 package 中的任何位置。

给 Keymap 文件命名

命名为 Default.sublime-keymap 的文件会对所有平台生效。每个平台还可以设置独立的 keymap:

  • Default (Windows).sublime-keymap
  • Default (OSX).sublime-keymap
  • Default (Linux).sublime-keymap

其他与上述提到的文件名不相符的将被 Sublime Text 忽略。

按键绑定的结构
  • keys 区分大小写的一个数组。

  • command 将执行的命名名称。

  • args 传递给command的参数形成的字典。关键字必须是command的参数名。

  • context 决定一个特定上下文的条件数组,所有条件需同时满足才算是符合条件。

例子:

{
  "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 }
  ]
}
Context 的结构

key 上下文的名称。

operator 针对 key的值要进行的操作符,默认为equal

operand 通过key返回的结果用这个值进行测试。

match_all 需要测试对所有选择都生效,默认为false

Context Operands

auto_complete_visible 自动填充列表显示时返回true

has_next_field 下一个代码段域可用时返回true

has_prev_field 上一个代码段域可用时返回true

num_selections 返回选择的数量。

overlay_visible 遮罩层可见时返回true

panel_visible 面板可见时返回true

following_text 限制测试插入符之后的文本。

preceding_text 限制测试为插入符之前的文本。

selection_empty 选择区域是空时返回true

setting.x 返回x的值,setting.x 可以是任意字符串。

text 限制测试为选中文本。

selector 返回当前作用域的名称。

panel_has_focus 如果面板中有输入框是 focus 时返回true

panel 如果面板中指定的operand可见时返回true

Context Operators

equalnot_equal 测试是否相等。

regex_matchnot_regex_match 通过正则表达式匹配(全匹配)。

regex_containsnot_regex_contains 通过正则表达式匹配(部分匹配)。

命令模式

Sublime Text 提供了一个 command_mode 设置防止按键事件被发送到缓冲区。这还是很有用的,例如,模拟 VIM 的模态行为。

不适用于命令模式的按键绑定应该包含类似下面的内容:

{ "key": "setting.command_mode", "operand": false }

通过这种方式,使用了命令模式的插件将能够无干扰地定义合适的键绑定。

可绑定的按键

按键绑定中的 key 必须是指定的字面量或名称,如果使用名称不生效,换成字面量试试。合法名称列表如下:

  • 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
修饰符
  • shift
  • ctrl
  • alt
  • super (Windows 键, Command 键…)
警告

如果你在开发一个包,请注意:

  • Ctrl+Alt+<alphanum> 不应该在任何 Windows 按键绑定中使用。
  • Option+<alphanum> 不应该在任何 OS X 按键绑定中使用。

这两种情况,用户插入非 ASCII 字符将会有其他风险。

保持 Keymap 有组织性

Sublime Text 默认的按键映射位于 Packages/Default下。其他包也许会包含其自己的按键映射文件。

推荐把个人的按键映射文件放到Packages/User下。

国际化键盘

由于 Sublime Text 映射名称到按键的方式,按键名可能和 US 英语以外的键盘布局中的按键不对应。

故障诊断

启用按键绑定相关的日志,参考:

这将帮助你调试按键绑定。

菜单

文件格式

FormatJSON (带注释)
Extension.sublime-menu
Name可用菜单项的列表,查看Available Menus
LocationPackages下的任意位置
Content“Menu Item” 对象的列表

例子

下面的内容是 Main.sublime-menu 文件中的一个摘要:

[
  {
    "caption": "Edit",
    "mnemonic": "E",
    "id": "edit",
    "children": [
      { "command": "undo", "mnemonic": "U" },
      { "command": "redo_or_repeat", "mnemonic": "R" },
      {
        "caption": "Undo Selection",
        "children": [{ "command": "soft_undo" }, { "command": "soft_redo" }]
      },
      { "caption": "-", "id": "clipboard" },
      { "command": "copy", "mnemonic": "C" },
      { "command": "cut", "mnemonic": "t" },
      { "command": "paste", "mnemonic": "P" },
      { "command": "paste_and_indent", "mnemonic": "I" },
      { "command": "paste_from_history", "caption": "Paste from History" }
    ]
  }
]

“Menu Item”对象

除非你通过一个 ID 来引用已有项目,否则每个菜单项必须定义其 childrencommandcaption

菜单项包含下列属性:

command 菜单项选中时将调用的命令的名称。

args 命令的参数,是一个对象。对于Side BarSide Bar Mount Point 菜单,这是一个由侧边栏包含所有选中项的列表的文件参数所扩展的。

caption 菜单栏上展示的文字。

children 鼠标滑过菜单项时显示的列表,覆盖已存在的command属性。

mnemonic 菜单的快捷键,区分大小写的单个字符,必须包含在 caption 中。

id 菜单项的唯一字符串标识符。这可以用来扩展菜单或是子菜单,甚至完全改写菜单。

设置

⚠️ 本节内容也许包含过时的和未完成的信息,你可以在默认的设置文件(Preferences → Settings - Default orDefault/Preferences.sublime-settings)中查看可用的设置。

全局设置

这些设置只能从 Preferences.sublime-settings andPreferences (*platform*).sublime-settings进行编辑。

theme 使用的主题,如:Default.sublime-theme

scroll_speed 设置为 0 禁用滚动,设置 0 到 1 之间缓慢滚动,设置超过 1 快速滚动。

hot_exit hot_exit 启用时,无需提示就可以立即关闭应用程序或窗口,未保存的编辑和已打开的文件在下次启动时将被恢复。

remember_open_files 决定是否重新打开 Sublime Text 上次关闭时打开的文件。

open_files_in_new_window 只在 OS X 有效,控制是否创建了一个新窗口。

close_windows_when_empty 最后一个文件关闭时直接关闭窗口。

show_full_path 在标题栏显示文件的绝对路径。

preview_on_click 值为true时,点击侧边栏的文件时将预览其内容。双击将会在新标签打开这个文件。

folder_exclude_patterns 排除匹配的文件夹。

file_exclude_patterns 排除匹配的文件。

binary_file_patterns 从跳转、查找文件中排除匹配到的文件,但不从侧边栏排除。

show_tab_close_buttons 值为false时将隐藏标签上的关闭按钮知道鼠标悬停在 tab 上。

mouse_wheel_switches_tabs 值为true时,如果鼠标停在 tab 区域,滚动鼠标的滚轮将会切换标签。

ignored_packages 被忽略的(不加载)包的列表。

文件设置

空格和缩进

auto_indent 切换自动缩进。

tab_size Tab键等价于几个空格。

translate_tabs_to_spaces 决定按下Tab键时是否把 tab 符转化成tab_size规定的空格数。

use_tab_stops 如果translate_tabs_to_spaces值为true,每一次按下Tab键和Backspace键都将插入或删除 tab_size规定的空格数。

trim_automatic_white_space 切换是否删除由 auto_indent添加的空格。

detect_indentation 值为false时,文件加载后将禁用 tab 和空格。如果值为true,将自动编辑translate_tabs_to_spacestab_size

draw_white_space 合法的值:noneselectionall

trim_trailing_white_space_on_save 值为true时保存文件时将删除空格。

视觉设置

always_show_minimap_viewport 设置为true时,将会在始终在缩略图区域高亮显示当前文件位置;默认值是false,这种情况只有鼠标移到缩略图区域才能看到当前文件所在位置。这里说的缩略图就是右侧整个文件的缩略 。

color_scheme 设置文本高亮的颜色。如:Packages/Color Scheme - Default/Monokai Bright.tmTheme

font_face 可编辑的文字字体。

font_size 可编辑的文字字号。

font_options 合法值:bolditalicno_antialiasgray_antialiassubpixel_antialiasdirectwrite(Windows)。

gutter 切换 gutter。

rulers 显示垂直规则的列,接收一个包含数值的数组(如[79,89,99])或者一个单一的数值(如79)。

draw_minimap_border 是否对缩略图区域当前视图可见文本区域画边框,颜色主题中的minimapBorder控制边框的颜色。

highlight_line 设置为false禁用高亮当前行。

line_padding_top 每行顶部额外的空白,像素单位。

line_padding_bottom 每行底部额外的空白,像素单位。

scroll_past_end 设置为false时禁用滚动到文件的底部,设置为true时 Sublime Text 将会在最后一行和窗体底部留下一个大的边距。

line_numbers 切换是否显示行号。

word_wrap 设置为false时,长文本将不会换行,需要横向滚动以看全其它文本。

wrap_width 如果比0大,长行的换行将依据指定列而不是窗口的宽度。只有word_wrap设置为true时这个设置才会生效。

indent_subsequent_lines 设置为false时,换行的行将不会有缩进。只有word_wrap设置为true时这个设置才会生效。

draw_centered 是否居中对齐。

match_brackets 设置为false时禁用给光标周围的括号添加下划线。

match_brackets_content 当光标靠近一个括号时如果你仅仅想高亮显示括号,将其值设置为false

match_brackets_square 设置为false禁用高亮方括号。match_bracketstrue时才会生效。

match_bracktets_braces 设置为false禁用高亮花括号。match_bracketstrue时才会生效。

match_bracktets_angle 设置为false禁用高亮尖括号。match_bracketstrue时才会生效。

自动行为

auto_match_enabled 切换自动匹配引号、括号等。

save_on_focus_lost 值为ture时,切换到其他文件或应用程序将自动保存文件。

find_selected_text 值为true时,当打开查找面板,选中的文字会自动被复制到面板中。

word_separators 单词分隔符。

ensure_newline_at_eof_on_save 保存时始终在文件末尾加新的一行。

系统和其它设置

is_widget 相对于一个常规文件,如果文件是对话框中的输入字段,返回true

spell_check 切换拼写检查。

dictionary 拼写检查的单词列表,接收一个数据目录的路径,如:Packages/Language - English/en_US.dic

fallback_encoding 当不能自动决定编码时使用的编码格式,ASCII、UTF-8 和 UTF-16 编码格式将会被自动检测。

default_line_ending 决定用来指定新行的字符,合法的值:system (OS-dependant),windowsCRLF)和 unixLF)。

tab_completion 决定按下Tab键是否进行补全操作。

构建和错误导航设置

result_file_regex and result_line_regex 用来提取打印到视图或是输出面板的错误信息的正则表达式。

result_base_dir 开始查找基于用result_file_regexresult_line_regex进行信息提取问题的文件的文件夹

build_env 默认添加到构建系统的路径列表。

文件和目录设置

default_dir 设置视图的默认保存文件夹。

输入设置

command_mode 值为true时,文件将会忽略按键的点击,在模拟 VIM 模态行为时很有用。

补全文件

注意补全并不限制于补全文件,因为其他来源也会对补全做出补充,参考补全章节的内容。然而,Sublime Text 中提供给你用来完善补全功能的最明显的方法就是通过 .sublime-completions 文件。

补全文件是带有 .sublime-completions 后缀的 JSON 文件。

例子

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

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

scope

确定补全列表何时被填充。

completions

补全的数组。

补全的类型

纯字符串

纯字符串等价于triggercontents一致的条目。

"foo"
// is equivalent to:
{ "trigger": "foo", "contents": "foo" }
基于 Trigger 的补全
{ "trigger": "foo", "contents": "foobar" },
{ "trigger": "foo\ttest", "contents": "foobar" }

trigger

展示到补全列表中的文字,选中时将会插入contents中的内容。

你可以使用\t添加一个提示,提示是右对齐的、略微有点灰色,不影响当前的触发器。

contents

插入到文件中的文本。

注意:如果你想要一个字面量$,你需要进行转义\\$(由于是在一个 JSON 字符串中,所以需要双斜杠)。

符号

概述

Sublime Text 对符号导航提供了基本的支持(跳转到类和函数的定义),任何文件都可启用文件导航。

格式

符号使用元数据文件定义。

和常规元数据文件一样,符号定义文件有 .tmPreferences 后缀,且使用 Property List 格式。文件名会被 Sublime Text 忽略。

定义符号

Sublime Text 有两种符号列表:局部符号列表(当前文件)和全局符号列表(项目范围)。

符号定义文件使用作用域选择器在源代码中捕获符号。

同一个包中可以共存多个符号定义文件,例如,两个符号定义文件可以串联工作:一个将定义所有符号,和第二个可以选择性地隐藏其中的一些。

符号定义文件示例:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Symbol List</string>
   <key>scope</key>
   <string>source.python meta.function.python, source.python meta.class.python</string>
   <key>settings</key>
   <dict>
      <key>showInSymbolList</key>
      <integer>1</integer>
   </dict>
</dict>
</plist>

上述文件,Sublime Text 将会用source.python meta.function.pythonsource.python meta.class.python去查找源文件,找到的将被作为符号。 showInSymbolList 的设置告诉 Sublime Text 使用局部符号列表。

文本转换

符号显示给用户时可以对它们进行转换,符号转换包含了使用 Oniguruma语法定义的文本替换正则表达式。

文本替换的例子:

s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;

这个例子中, class FooBar(object) 在符号列表中将显示为 FooBar(object)

使用符号转换来扩展一下上面的例子:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Symbol List</string>
   <key>scope</key>
   <string>source.python meta.function.python, source.python meta.class.python</string>
   <key>settings</key>
   <dict>
      <key>showInSymbolList</key>
      <integer>1</integer>
      <key>symbolTransformation</key>
      <string>
         s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;
         s/def\s+([A-Za-z_][A-Za-z0-9_]*\()(?:(.{0,40}?\))|((.{40}).+?\)))(\:)/$1(?2:$2)(?3:$4…\))/g;
      </string>
   </dict>
</dict>
</plist>

符号定义文件的结构

所有源文件的外部结构都是一样的,继承自 Property List 格式。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   ...
</dict>
</plist>

下面这些是符号定义文件中合法的元素:

name 可选,符号定义的名称,Sublime Text 会忽略。

<key>name</key>
<string>Some arbitrary name goes here</string>

scope 以逗号分隔的作用域名称列表。

<key>scope</key>
<string>source.python meta.function.python, source.python meta.class.python</string>

settings 必需,设置的容器。

<key>settings</key>
<dict>
   ...
</dict>

uuid 可选,文件的唯一标识符,Sublime Text 会忽略。

<key>uuid</key>
<string>BC062860-3346-4D3B-8421-C5543F83D11F</string>

settings子元素

showInSymbolList

可选,把符号和局部符号列表关联起来。合法值是010表示对应的符号不展示。

<key>showInSymbolList</key>
<integer>1</integer>

showInIndexedSymbolList

可选,把符号和全局符号列表关联起来。合法值是010表示对应的符号不展示。

<key>showInIndexedSymbolList</key>
<integer>1</integer>

symbolTransformation

可选,目标是局部符号列表。分号分隔的正则表达式列表。

<key>symbolTransformation</key>
<string>
   s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;
   s/def\s+([A-Za-z_][A-Za-z0-9_]*\()(?:(.{0,40}?\))|((.{40}).+?\)))(\:)/$1(?2:$2)(?3:$4…\))/g;
</string>

symbolIndexTransformation

可选,目标是全局符号列表。

<key>symbolIndexTransformation</key>
<string>
   s/class\s+([A-Za-z_][A-Za-z0-9_]*.+?\)?)(\:|$)/$1/g;
   s/def\s+([A-Za-z_][A-Za-z0-9_]*\()(?:(.{0,40}?\))|((.{40}).+?\)))(\:)/$1(?2:$2)(?3:$4…\))/g;
</string>

导航符号

一旦符号定义了,你就可以通过标准的快捷键来调用它们:

F12跳转到定义
Ctrl+R显示局部符号列表
Ctrl+Shift+R显示全局符号列表

注释

概述

Sublime Text 提供了一个默认的命令来注释和取消注释,支持任何类型使用了元数据文件的文件。

文件格式

使用元数据文件定义注释标记。和普通元文件一样,注释元数据文件扩展名为 .tmPreferences ,使用 Property List 格式。查 看Metadata Files的官方介绍。

示例

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>Miscellaneous</string>
   <key>scope</key>
   <string>source.python</string>
   <key>settings</key>
   <dict>
      <string></string>
      <key>shellVariables</key>
      <array>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START</string>
            <key>value</key>
            <string># </string>
         </dict>
      </array>
   </dict>
</dict>
</plist>

元文件结构

所有源文件的外部结构都是一样的,继承自 Property List 格式。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   ...
</dict>
</plist>

下面这些是合法的元素:

name 可选,符号定义的名称,Sublime Text 会忽略。

<key>name</key>
<string>Shell Variables</string>

scope 必需,以逗号分隔的作用域名称列表。

<key>scope</key>
<string>source.python</string>

settings 必需,设置的容器。

<key>settings</key>
<dict>
   ...
</dict>

uuid 可选,文件的唯一标识符,Sublime Text 会忽略。

<key>uuid</key>
<string>BC062860-3346-4D3B-8421-C5543F83D11F</string>

setting子元素

shellVariables

必需,注释标记的容器。

<key>shellVariables</key>
<array>
   ...
</array>

shellVariables子元素

注意:shellVariables 数组可以包含任意的子元素,这里我们只关注和注释有关的。

TM_COMMENT_START 定义默认的注释标记。如果想定义一个额外的注释标记,取名为TM_COMMENT_START_2TM_COMMENT_START_3等等。

<dict>
   <key>name</key>
   <string>TM_COMMENT_START</string>
   <key>value</key>
   <string># </string>
</dict>

TM_COMMENT_END 可选,定义注释标记的结束。如果省略的话,TM_COMMENT_START将被视为一个行注释标记。如果开始和结束标记都有的话,则这一组将视为块级注释标记。如果想定义一个额外的注释结束标记,取名 为TM_COMMENT_END_2TM_COMMENT_END_3等等。

<dict>
   <key>name</key>
   <string>TM_COMMENT_END_2</string>
   <key>value</key>
   <string>*/</string>
</dict>

TM_COMMENT_DISABLE_INDENT 可选,合法值为yesno。禁用TM_COMMENT_START标记的缩进。如果要指定其他组的标记,使用 TM_COMMENT_DISABLE_INDENT_2等。

<dict>
   <key>name</key>
   <string>TM_COMMENT_DISABLE_INDENT</string>
   <key>value</key>
   <string>yes</string>
</dict>

示例

这里有一个更加完整的示例,使用了刚才说到的内容:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
   <dict>
      <key>shellVariables</key>
      <array>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START</string>
            <key>value</key>
            <string>// </string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START_2</string>
            <key>value</key>
            <string>/*</string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_END_2</string>
            <key>value</key>
            <string>*/</string>
         </dict>
      </array>
   </dict>
   <key>uuid</key>
   <string>BC062860-3346-4D3B-8421-C5543F83D11F</string>
</dict>
</plist>

相关快捷键

Ctrl+/切换行的注释
Ctrl+Shift+/切换块的注释

Metadata 文件

概述

元数据是可以被分配到使用作用域选择器特定文本段的参数。

这些参数可以有多种用途,如:

  • 指定当前注释标记,即使是在嵌入的源代码中,因此你可以用任何语法来切换注释。
  • 定义自动缩进的规则。
  • 快速浏览。

文件格式

扩展名为 .tmPreferences ,使用 Property List 格式。

示例

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>name</key>
   <string>JavaScript Metadata</string>
   <key>scope</key>
   <string>source.js</string>
   <key>settings</key>
   <dict>
      <key>decreaseIndentPattern</key>
      <string>^(.*\*/)?\s*\}.*$</string>
      <key>increaseIndentPattern</key>
      <string>^.*\{[^}"']*$</string>

      <key>bracketIndentNextLinePattern</key>
      <string>(?x)
      ^ \s* \b(if|while|else)\b [^;]* $
      | ^ \s* \b(for)\b .* $
      </string>
   </dict>
   <dict>
      <key>shellVariables</key>
      <array>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START</string>
            <key>value</key>
            <string>// </string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_START_2</string>
            <key>value</key>
            <string>/*</string>
         </dict>
         <dict>
            <key>name</key>
            <string>TM_COMMENT_END_2</string>
            <key>value</key>
            <string>*/</string>
         </dict>
      </array>
   </dict>
   <key>uuid</key>
   <string>BC062860-3346-4D3B-8421-C5543F83D11F</string>
</dict>
</plist>

示例文件结合了多种类型的元数据。

元文件结构

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   ...
</dict>
</plist>

下面这些是合法的元素:

name 可选,符号定义的名称,Sublime Text 会忽略。

<key>name</key>
<string>Shell Variables</string>

scope 必需,以逗号分隔的作用域名称列表。

<key>scope</key>
<string>source.python</string>

settings 必需,设置的容器。

<key>settings</key>
<dict>
   ...
</dict>

uuid 可选,文件的唯一标识符,Sublime Text 会忽略。

<key>uuid</key>
<string>BC062860-3346-4D3B-8421-C5543F83D11F</string>

settings子元素

settings 元素可以包含有不同用途的子元素。

缩进选项

increaseIndentPattern 正则表达式,如果匹配到当前行,则下一行将会有向下一级别的缩进。

<key>increaseIndentPattern</key>
<string>insert regex here</string>

decreaseIndentPattern 正则表达式,如果匹配到当前行,则下一行将会有向上一级别的缩进。

<key>decreaseIndentPattern</key>
<string>insert regex here</string>

bracketIndentNextLinePattern 正则表达式,如果匹配到当前行,则仅仅是下一行将会有下一级别的缩颈。

<key>bracketIndentNextLinePattern</key>
<string>insert regex here</string>

disableIndentNextLinePattern 正则表达式,如果匹配到当前行,下一行将不再缩进。

<key>disableIndentNextLinePattern</key>
<string>insert regex here</string>

unIndentedLinePattern 正则表达式,自动缩进计算下一行的缩进层级时将忽略当前匹配行。

<key>unIndentedLinePattern</key>
<string>insert regex here</string>
补全选项

cancelCompletion 正则表达式,如果匹配到当前行,会禁止补全弹出层。

<key>cancelCompletion</key>
<string>insert regex here</string>
Shell 变量

Shell 变量有多种用途且可以从代码段中访问,注意 Shell 变量是定义在 array 中的字典,因此和settings的子元素有不同的格式。

shellVariables “shell 变量”的容器。

<key>shellVariables</key>
<array>
   ...
</array>

shellVariables的子元素

<dict>
   <key>name</key>
   <string>BOOK_OPENING</string>
   <key>value</key>
   <string>Once upon a time...</string>
</dict>

相关 API 函数

view.meta_info(key, point) 从插件代码中提取元数据。

命令面板

文件格式

FormatJSON (带注释)
Extension.sublime-commands
Name任意
LocationPackages下任何位置
Content命令面板可选项列表

示例

这里有一个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" } }
]

命令面板项

下面这些事可以包含在 .sublime-commands 中的项:

caption 显示在命令面板中的文字。

command 将要执行的命令。

args 传递给command的参数。需要注意的是你需要用类似代码段形式的变量:${packages}$packages来定位包文件夹,这和其他地方有点区别。

使用方法

  1. 按下Ctrl+Shift+P
  2. 选择命令

可选项会根据输入的文字过滤,并不会一次显示所有的项。

插件

插件是从sublime_plugin中实现*Command类的 Python 脚本。

存放位置

Sublime Text 在下列位置寻找插件:

  • Packages
  • Packages/
  • .sublime-package 文件

Packages 中嵌套目录中的插件不会被加载。所有插件都应该放到Packages目录下其自己的文件夹中,不能直接放到Packages下。

指令命名约定

带有Command的后缀,如:NamesLikeThisCommand。然而,指令名称会自动被转化成name_like_this。因此 ExampleCommand 会变成exampleAnotherExampleCommand 会变成another_example

指令的类型

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

WindowCommand 实例必须有一个 .window 属性指向创建他们的窗口实例,类似的, TextCommand 必须有一个 .view 属性。

命令的共同点

所有的命令都需要实现一个.run()函数才能正常运行,此外,它们可以接收任意多的关键字参数。

注意:命令的参数必须是有效的 JSON 值。

通过 API 调用指令

根据不同指令的类型,使用ViewWindow的引用并调用<object>.run_command('command_name')。除了命令的名称外,.run_command接收一个字典参数。

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

指令参数

所有用户提供的参数都必须是合法的 JSON 类型。

文本指令和edit对象

文本指令接收一个edit对象,所有 edit 中完成的操作都会被分组为一个撤销操作。编辑完成时 on_modified()on_selection_modified() 等回调函数会被调用。

和老版本不同,Sublime Text3 不允许对edit对象进行编程控制,edit对象的生命周期由编辑器单独管理。API 是负责管理其生命周期的。插件的作者必须确保新的文本命令中的所有的编辑都在.run()中,以便宏和代码段 可以正常工作。

run_command() 函数可以从你自己的指令中调用其他指令。

事件响应

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

标准库

Sublime Text 自带一个缩减版的标准库。

自动重载插件

插件有变动时 Sublime Text 将会重新加载 Python 模块,但是 Python 的子包不会被自动加载,这在你开发插件时会造成困惑。插件的文件有变化时最好还是重启 Sublime Text 为好。

多线程

只有 set_timeout() 函数可以安全地从不同的线程调用。

Python API

官方文档

官方文档中缺失的

官方文档中有些缺失,本章节就是尝试解决这个问题的。

索引
sublime 模块
  • class sublime.Window

    表示 Sublime Text 中的窗口,并提供了一些方法与窗口进行交互。

    • setlayout (_layout)

      更改视图组基于区块的面板布局。

      | Parameters: | layout (dict) – 指定新的布局 | | ----------- | ---------------------------------- | | Returns: | None |

      期望的字典如下:

      { "cols": [float], "rows": [float], "cells": [[int]] }
      

      [type] 代表type的列表:

      cols

      列分隔符的列表,从 0(左)到 1(右)。

      rows

      行分隔符的列表,从 0(上)到 1(下)。

      cells

      格子列表,每项值表示格子的边界。如下:

      [x1, y1, x2, y2]
      

      每个值分别表示行列的索引,因此, [0, 0, 1, 2] 表示把一个单元格从左上角平移到第一列第二行的位置。

      注意:没有进行过边界测试,也不会进行自动调整。因此,你可以指定比 0 小或比 1 大的值,Sublime Text 会有相应的处理。这意味着你可以裁剪视图或创建边框。目前还不清楚这些空白空间的背景色( 默认是黑色)是否可以被修改,使用的话后果自负 。

      行列的顺序也没有被检查,所以如果你使用了一个类似 [1, 0.5, 0] 这样的值,你将会看到两个黑色的面板,Sublime Text 在这种状态将不可用。

      示例:

      # A 2-column layout with a separator in the middle
      window.set_layout({
          "cols": [0, 0.5, 1],
          "rows": [0, 1],
          "cells": [[0, 0, 1, 1], [1, 0, 2, 1]]
      })
      
      # A 2x2 grid layout with all separators in the middle
      window.set_layout({
          "cols": [0, 0.5, 1],
          "rows": [0, 0.5, 1],
          "cells": [[0, 0, 1, 1], [1, 0, 2, 1],
                    [0, 1, 1, 2], [1, 1, 2, 2]]
      })
      
      # A 2-column layout with the separator in the middle and the right
      # column being split in half
      window.set_layout({
          "cols": [0, 0.5, 1],
          "rows": [0, 0.5, 1],
          "cells": [[0, 0, 1, 2], [1, 0, 2, 1],
                                  [1, 1, 2, 2]]
      })
      
  • class sublime.View

    Window类似,表示 Sublime Text 中的视图,并提供了一些方法与窗口进行交互。

    • matchselector(_point, selector)

      匹配指定selector下的point作用域。

      | Parameters: | point (int) – 一个作用域选择器 | | ------------- | ------------------------------------ | | Returns bool: | 是否匹配到 |

      等价于:

      view.score_selector(point, selector) != 0
      # or
      sublime.score_selector(view.scope_name(point), selector) != 0
      
sublime_plugin 模块
  • class sublime_plugin.EventListener

    • onquery_completions(_view, prefix, locations)

      请求补全列表时调用。

      • view

        补全到的view实例。

      • prefix

        到目前为止输入的文字。

      • locations

        view 中补全将要插入的作用域的选择器列表。

        如果你想处理依赖于单词分隔符的补全,你需要单独测试每一个 location。

      • Return value

        • [[trigger, contents], ...]

          和“基于选择器补全”类似,但是没有 keys.trigger 的映射,可以使用\\t描述语法的列表

          注意:Sublime Text 3 中,补全还可以包含纯文本,而不是触发内容列表。

        • ([[trigger, contents], ...], flags)

          基本上和上面一种相同,第二个元素flag可能是这些标记的按位或的组合:

          • sublime.INHIBIT_WORD_COMPLETIONS

            所有插件都被处理后,阻止 Sublime Text 把它的单词添加到补全列表。

          • sublime.INHIBIT_EXPLICIT_COMPLETIONS

            这个是做啥的?

          所有补全中的标记都是共享的,一旦被某种插件设置过就无法恢复了。

        • 其它(例如None

          没作用。

探索 API

快速查看 API 的方法:

  1. Packages/Default (Preferences | Browse Packages…) 添加到你的项目中
  2. Ctrl + Shift + F
  3. 在输入框中输入 *.py
  4. 开启 Use Buffer选项
  5. 搜索 API 名称
  6. F4
  7. 学习相关的源代码

指令

Windows/Linux 键盘快捷键

编辑

⚠️ 本文只是一个草稿也许包含错误的信息。

KeypressCommand
Ctrl + X剪切当前行
Ctrl + ↩在后面插入一行
Ctrl + ⇧ + ↩在前面插入一行
Ctrl + ⇧ + ↑向上移动行/区块
Ctrl + ⇧ + ↓向下移动行/区块
Ctrl + L选中行-重复按下以选择后面的行
Ctrl + D选择单词-重复按下以选择相同的单词
Ctrl + M跳转到括号的结尾,重复按下跳转到括号的开头。
Ctrl + ⇧ + M选择当前括号中的所有内容
Ctrl + ⇧ + K删除行
Ctrl + KK删除光标到行尾的内容
Ctrl + K + ⌫删除光标到行首的内容
Ctrl + ]缩进当前行
Ctrl + [向前缩进当前行
Ctrl + ⇧ + D重复行
Ctrl + J把当前行下面的一行追加到当前行尾
Ctrl + /添加/取消当前行的注释
Ctrl + ⇧ + /块级注释
Ctrl + Y重做,或重复上一次键盘快捷键
Ctrl + ⇧ + V粘贴并正确地缩进
Ctrl + Space选择下一个自动补全的建议
Ctrl + U撤销
Alt + ⇧ + W把选择的块用 html 标签包起来
Alt + .关闭当前 html 标签
Window
Ctrl + Alt + Up向上选择行
Ctrl + Alt + Down向下选择行
Linux
Alt + ⇧ + Up向上选择行
Alt + ⇧ + Down向下选择行

导航

KeypressCommand
Ctrl + P根据文件名快速打开文件
Ctrl + R跳转到符号
Ctrl + ;跳转到当前文件中的单词
Ctrl + G跳转到当前文件中的行

通用

KeypressCommand
Ctrl + ⇧ + P打开命令面板
Ctrl + KB切换侧边栏的显示
Ctrl + ⇧ + Alt + P在状态栏显示作用域

查找、替换

KeypressCommand
Ctrl + F查找
Ctrl + H替换
Ctrl + ⇧ + F在文件中查找

Tab 标签

KeypressCommand
Ctrl + ⇧ + t打开上一次关闭的标签
Ctrl + PgUp在 tab 中向上循环
Ctrl + PgDn在 tab 中向下循环
Ctrl + ⇆在文件中查找
Ctrl + W关闭当前标签
Alt + [NUM]切换到第 NUM 个 tab

分割窗口

KeypressCommand
Alt + ⇧ + 1恢复视图为 1 列
Alt + ⇧ + 2将视图变成 2 列
Alt + ⇧ + 3将视图变成 3 列
Alt + ⇧ + 4将视图变成 4 列
Alt + ⇧ + 5把视图变成网格(4 块)
Alt + ⇧ + 8把视图变成 2 行
Ctrl + [NUM]调到第 1-4 块区域
Ctrl + ⇧ + [NUM]把文件移到指定第 1-4 块区域

标记

KeypressCommand
Ctrl + F2切换标记的显示
F2下一个标记
⇧ + F2上一个标记
Ctrl + ⇧ + F2清除标记

文本操作

KeypressCommand
Ctrl + KU转换成大写
Ctrl + KL转换成小写

OSX 键盘快捷键

编辑

KeypressCommand
⌘ + X剪切行
⌘ + ↩在后面插入行
⌘ + ⇧ + ↩在之前插入行
⌘ + ⌃ + ↑向上移动行/区块
⌘ + ⌃ + ↓向下移动行/区块
⌘ + L选中行,重复按下可连续选择多行
⌘ + D选中单词,连续按下可选择重复的单词
⌃ + ⌘ + G在当前部分选中所有出现的
⌃ + ⇧ + ↑Extra cursor on the line above
⌃ + ⇧ + ↓Extra cursor on the line below
⌃ + M跳转到括号结束的地方,重复按下可跳转到括号开始的地方
⌃ + ⇧ + M选择当前括号内的所有内容
⌃ + A, ⌘ + Left跳转到行首
⌃ + E, ⌘ + Right跳转到行尾
⌘ + K, ⌘ + K删除光标到行尾的内容
⌘ + K + ⌫删除光标到行首的内容
⌘ + ]缩进
⌘ + [向前缩进
⌘ + ⇧ + D重复行
⌘ + J把当前行的下一行追加到行尾
⌘ + /单行注释
⌘ + ⌥ + /块级注释
⌘ + Y重做
⌘ + ⇧ + V粘贴并使用正确的缩进
⌃ + Space选择下一个自动补全的建议
⌃ + U撤销
⌃ + ⇧ + Up向上选择行
⌃ + ⇧ + Down向下选择行
⌃ + ⇧ + W把选中文字用 HTML 标签包起来
⌃ + ⇧ + K删除光标所在行

导航

KeypressCommand
⌘ + P or ⌘ + T根据文件名快速打开文件
⌘ + R跳转到符号
⌃ + G跳转到当前文件的行

通用

KeypressCommand
⌘ + ⇧ + P命令面板
⌃ + `Python 控制台
⌃ + ⌘ + F切换到全屏模式
⌃ + ⇧ + ⌘ + F切换到免打扰模式
⌘ + K, ⌘ + B切换侧边栏
⌃ + ⇧ + P在状态栏显示作用域

查找、替换

KeypressCommand
⌘ + F查找
⌘ + ⌥ + F替换
⌘ + ⇧ + F在文件中查找

滚动

KeypressCommand
⌃ + V向下滚动一页
⌃ + L把当前行定位到视图中间
⌘ + Down跳转到文件结尾
⌘ + Up跳转到文件开始

Tab 标签

KeypressCommand
⌘ + ⇧ + t打开上一次关闭的标签
⌘ + ⇧ + [在 tab 中向上循环
⌘ + ⇧ + ]在 tab 中向下循环
^ + Tab在最近 tab 中向上循环
⇧ + ^ + Tab在最近 tab 中向下循环
⌘ + [NUM]切换到第 NUM 个 tab

分割窗口

KeypressCommand
⌘ + ⌥ + 1恢复视图为 1 列
⌘ + ⌥ + 2将视图变成 2 列
⌘ + ⌥ + 3将视图变成 3 列
⌘ + ⌥ + 4将视图变成 4 列
⌘ + ⌥ + 5把视图变成网格(4 块)
⌘ + ⌥ + 8把视图变成 2 行
⌃ + [NUM]调到第 1-4 块区域
⌃ + ⇧ + [NUM]把文件移到指定第 1-4 块区域

标记

KeypressCommand
⌘ + F2切换标记的显示
F2下一个标记
⇧ + F2上一个标记
⇧ + ⌘ + F2清除标记

文本操作

KeypressCommand
⌘ + K, ⌘ + U转换成大写
⌘ + K, ⌘ + L转换成小写
⌘ + ⌃ + up, ⌘ + ⌃ + down向上/向下剪辑文本