完成

Sublime文本包括一些通过完成单词或插入样板来节省打字和时间的方法。完成包括以下来源:

  • Words from the current file
  • Context-aware suggestions4.0
  • Completion files
  • Snippet files
  • Plugins

存在各种设置来自定义完成行为。用户可以编写自己的片段或完成文件，并且存在许多第三方包来提供完成。

Usage

默认情况下，当用户编辑源代码或标记时，Sublime Text将自动显示补全弹出窗口，但不在注释、字符串或标记中的散文中。

按 Esc 键将隐藏完成弹出窗口。手动显示完成弹出，按 Ctrl + Space。 如果没有完成可用，messageNo available completions 将显示在状态栏。

上下文感知建议 4.0

Sublime Text中的完成引擎使用后台进程扫描项目中的所有文件以构建完成索引。该索引用于根据现有代码中的模式向用户提供建议的完成。

示例:

  • 如果经常将属性设置为布尔值，则建议将包括trueorfalse
  • 如果标识符通常是 “被调用的”，则该名称将被建议附加 ()

所提供的精确完成是基于各种启发式算法，并从项目中的现有代码中导出。由于完成是基于对现有代码的分析，因此不会建议项目中未使用的单词。

完成元数据 4.0

除文本内容外，补全还可能为用户提供其他详细信息。这些包括完成所代表的元素的 种类 、帮助选择完成的简短 注释 以及可能包含指向其他资源的链接的 详细信息。

 Kind info f apply() s application m absolute() s acls abstract class  Annotation c agent Struct 2 Definitions Details

KIND INFO

完成可能会提供与完成触发器一起提供的信息。这包括一个高级类别、一个识别字母和一个名称。以下是一些最常见的种类:

Icon Name
k Keyword
t Type
f Function
a Namespace
n Navigation
m Markup
v Variable
s Snippet

在本文档和Sublime Text中，将鼠标悬停在一个字母上会显示一个带有全名的工具提示。种类元数据的颜色由主题决定，可能与上面显示的不匹配。

.sublime-completions文件和插件可以使用上面列出的任何类别的组合，以及自定义演示的任何Unicode字符和名称。

注释

注释显示在完成弹出窗口的右侧边缘，并且可能包含作者认为有用的任何信息。通常，注释将是一两个单词。

DETAILS

完成的 details 字段可能包含带有链接的富文本描述。选择完成时，完成的详细信息显示在完成弹出窗口的底部。

定制化

有许多方法可以通过新的完成来增强引擎:

完成文件

向Sublime Text添加完成的最基本形式是创建一个.sublime-completions 文件。Completions文件使用JSON格式，并包含具有键 "scope" 和 "completions" 的对象。

"scope" 键的值是一个字符串，其中包含应用于completions的语法的 [选择器] (selectors)。"completions" 值是完成的数组。数组中的每个条目表示单个完成，并且可以是字符串或对象。

简单格式

当完成是一个字符串时，该字符串同时代表触发器文本和完成内容。

一个basic.sublime-completions file:

{
    "scope": "source.python",
    "completions": [
        "def",
        "class",
        "None",
        "True",
        "False"
    ]
}

复格式

当完成是一个对象时，有效键包括:

trigger string REQUIRED

用户必须输入的文本以匹配完成

content sstring REQUIRED

将插入到文件中的内容。支持片段 [fields] (completions#snippet_fields) 和 [variables] (completions#snippet_variables)。

annotation 4.0 string

要显示以完成的注释。

kind 4.0 string, 3-element array of strings

完成的元数据种类。

如果值是字符串，则它必须是以下之一:

  • "ambiguous"
  • "function"
  • "keyword"
  • "markup"
  • "namespace"
  • "navigation"
  • "snippet"
  • "type"
  • "variable"

举例:"kind":"function"

如果值是字符串的3元素数组，则它们必须为:

  1. 上面列表中的一个字符串，主题使用它来选择元数据类型的颜色
  2. 要显示在触发器左侧的单个Unicode字符
  3. 种类的描述，可在种类字母工具提示和详细信息窗格中查看 (当可见时)

举例:"kind": ["function","m","Method"]

details 4.0 string

完成的单行描述。可能包含以下用于基本格式设置的HTML标记:

  • <ahref="">–protocols
  • <b>
  • <strong>
  • <i>
  • <em>
  • <u>
  • <tt>
  • <code>

除了上面列出的属性或标签外，不支持其他属性或标签。

举例 :"details":"Wraps selection in a <code>&lt;b&gt;</code> tag"

A.sublime-completions file with examples of each field:

{
    "scope": "source.python",
    "completions": [
        {
            "trigger": "def",
            "contents": "def",
            "kind": "keyword"
        },
        {
            "trigger": "fun",
            "annotation": "basic function",
            "contents": "def ${1:name}($2):\n    $0\n",
            "kind": "snippet",
            "details": "A simple, non-<code>async</code> function definition"
        }
    ]
}

片段

片段通常用于样板类型的内容，由于跨越多行，因此不容易使用.sublime-completions 格式进行创作。

片段是扩展名为.sublime-snippet的XML文件。它们具有顶级标签 <snippet>，其中包含以下标签:

scope

片段应启用的选择器语法

tabTrigger

用于匹配完成弹出窗口中的片段的文本

contents

应用片段时插入文档的文本。支持 fields 和 [variables] (completions#snippet_variables)。

通常，此标签的内容被包装在 <![CDATA['and']]>中，因此不需要对内容进行XML转义。

description

片段的可选描述，显示在选项板中

An example.sublime-snippetfile:

<snippet>
    <scope>source.python</scope>
    <tabTrigger>fun</tabTrigger>
    <content><![CDATA[def ${1:name}($2):
    ${0:pass}]]></content>
    <description>function, non-async</description>
</snippet>

FIELDS

片段支持 字段，用户在插入片段后可以通过片段中的位置tab切换。字段可以是简单的位置，但也可以提供默认内容。

简单字段为 $，后跟整数。字段 $0 是片段完成后将放置选择的位置。字段 $1 到 $n 在移动到 $0 之前都已填写。

Name: $1
Email: $2
Description: $0

具有默认内容的字段使用格式 ${1:default text}。默认内容可以是文字文本，也可以包含变量。

Name: ${1:first} ${2:last}
Email: ${3:user}@${4:example.com}

如果片段不包含字段 $0，则在末尾隐式添加该片段。

变量

可以将以下变量添加到代码段中，以包括要插入代码段的文件中的信息:

Variable Description
$SELECTION The current selection
$TM_SELECTED_TEXT The current selection
$TM_LINE_INDEX The 0-based line number of the current line
$TM_LINE_NUMBER The 1-based line number of the current line
$TM_DIRECTORY The path to the directory containing the file
$TM_FILEPATH The path to the file
$TM_FILENAME The file name of the file
$TM_CURRENT_WORD The contents of the current word
$TM_CURRENT_LINE The contents of the current line
$TM_TAB_SIZE The number of spaces per tab
$TM_SOFT_TABS YESorNO– if tabs should be translated to spaces
$TM_SCOPE The base scope name of the file’s syntax

除了上面命名的变量之外，字段还可以用作变量，允许用户输入单个值并在多个位置重复该值。

Name: ${1:first} ${2:last}
Email: ${3:$1}@${4:example.com}

变量替换

变量可以直接引用，也可以使用正则表达式对其进行修改。 带有替换的变量以以下格式编写${*name*/*regex*/*replace*/*flags*}.

正则表达式 段支持regular expressions. replace 段支持相应的替换格式. 标志 段将包含来自以下内容的零个字母:

  • g– 所有事件，而不仅仅是第一次，都应该被替换
  • i– 不区分大小写匹配
  • m– 多行模式，其中 '^' 匹配每行的开头

通常情况下，变量替换与引用字段的数值变量相结合。

在删除第一个空格和之后的所有内容之后，以下内容使用第一个字段作为第二个字段的默认内容:

Name: ${1:name}
Email: ${2:${1/\s.*//}}@${3:example.com}

ESCAPING

由于片段可以包含以 $ 开头的变量，因此必须将文字 $ 字符写成 \$。

执行变量替换时，必须将 / 字符写成 \/。

插件

添加完成的最强大的工具是Python插件。

编写插件以提供完成包括在扩展的类上实现方法 on_query_completions()事件监听或ViewEventListener.

import sublime
import sublime_plugin


class MyCompletions(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):
        if not view.match_selector(locations[0], "source.python"):
            return []

        available_completions = [
            "def",
            "class",
            "None",
            "True",
            "False"
        ]

        prefix = prefix.lower()

        out = []
        for comp in available_completions:
            if comp.lower().startswith(prefix):
                out.append(comp)

        return out

异步完成可以通过on_query_completions() 返回 一个CompletionList对象.4050

完成细节，包括种类元数据，由从on_query_completions()返回CompletionItem对象提供。4050

设置

tab_completion boolean

启用后，按 Tab 将插入最佳匹配完成。禁用时，Tab只会触发片段或插入制表符。Shift+Tab可使用明确选项卡标签。

禁用此设置不会隐式禁用自动完成。

auto_complete boolean

键入时自动显示完成弹出窗口。

此行为不受设置选项卡 tab_completion 的影响。

auto_complete_size_limit integer

如果当前文件的文件大小 (以字节为单位) 大于此大小，则不会自动显示完成弹出窗口。

auto_complete_delay integer

自动显示完成弹出窗口之前要等待的毫秒数。

auto_complete_selector string

一个 选择器，用于限制何时自动显示完成弹出窗口。

示例:"meta.tag, source - comment - string.quoted.double.block - string.quoted.single.block - string.unquoted.heredoc"

auto\_complete\_triggers 设置可用于在特定情况下重新启用自动完成弹出窗口。

auto_complete_triggers array of objects

为何时自动显示完成弹出窗口提供显式触发器。

每个对象必须包含键 "selector" ，其字符串值包含 选择器，以匹配插入符号位置，和带有字符串值的 “字符” 键，指定插入符号左侧必须存在哪些字符。

Example:

[
    {
        "selector": "text",
        "characters": "<"
    }
]

触发器将覆盖设置 auto_complete_selector 。

auto_complete_commit_on_tab boolean

默认情况下，自动完成将在Enter上提交当前完成。此设置可用于在Tab 上完成。

在Tab 上完成通常是一个更好的选择，因为它消除了提交完成和插入换行符之间的歧义。

auto_complete_with_fields boolean

控制片段字段处于活动状态时是否自动显示完成弹出窗口。仅在启用了 auto_complete_commit_on_tab 选项卡上的 “提交” 时才相关。

auto_complete_cycle boolean

控制按⬆时会发生什么 当选择完成弹出窗口中的第一项时: 如果为 false，则隐藏弹出窗口，否则选择弹出窗口中的最后一个完成。

也使第一完成选择当 ⬇在最后一次完成时按下。

auto_complete_use_history boolean

是否应该自动选择先前选择的完成

auto_complete_use_index 4.0 boolean

启用后，完成弹出窗口将显示基于项目中其他文件的上下文感知建议。

auto_complete_preserve_order 4.0 string

控制在键入时如何重新排序自动完成结果:

  • "none"– 根据完成与键入的文本的匹配程度对结果进行完全重新排序
  • "some"– 部分重新排序结果，考虑到完成与类型匹配的程度以及完成的可能性
  • "strict"– 永远不对结果重新排序

auto_complete_trailing_symbols 4.0 boolean

是否完成引擎认为尾随符号可能足够，则添加尾随符号 (例如.,())

auto_complete_trailing_spaces 4.0 boolean

是否完成引擎认为它们可能足够，则在完成后添加一个空格

auto_complete_include_snippets 4.0 boolean

控制片段是否不会包含在完成弹出窗口中。

禁用后，仍然可以通过输入选项卡触发器并在未显示完成弹出窗口时按Tab来触发片段。 auto_complete_include_snippets_when_typing 4.0 boolean

当它被设置为 false动触发时，片段不会出现在完成弹出窗口中。如果手动触发，将显示它们。

ignored_snippets4.0 array of strings

文件模式 指定要忽略的片段文件。

例如，忽略所有默认的 C++ snippets:

[
    "C++/*"
]