使用语言配置自定义编辑器行为
你可以通过使用语言配置来启用特定于语言的语法操作,从而在 Visual Studio 编辑器中实现自定义的语言特定语法。 与使用语言服务器相比,使用语言配置可以提高性能,因为它的所有操作都是本地操作。
什么是语言配置
Visual Studio 通过语言扩展为各种编程语言提供智能编辑功能。 语言配置补充了使用语言服务器协议 (LSP) 的服务器,并提供声明性数据,使 Visual Studio 编辑器能够做出格式设置、着色和完成决策,而不会延迟对 LSP 服务器进行异步查询。 声明性语言功能在配置文件中定义。 例如,与 Visual Studio 捆绑在一起的 HTML、CSS 和打字稿基本扩展可提供以下部分声明性语言功能:
- 语法突出显示
- 片段完成
- 括号匹配
- 自动添加结束括号
- 注释切换
- 自动缩进
Visual Studio 提供了为任何编程语言定义语言配置的扩展功能。 语言配置文件控制基本的编辑功能,例如注释切换、括号匹配和包围。
使用语言配置有助于:
- 用户输入时进行同步工作
- 简单性:带有正则表达式的短 JSON 文件比复杂的算法更容易维护
- 可移植性:在 Visual Studio Code 和 Visual Studio 之间不需要进行更改或只需进行极少量更改
此外,语言配置文件提供了一种简单的方法来扩展 Visual Studio,以通过易于阅读的 JSON 文件支持一些基本的重构功能。
向 Visual Studio 扩展添加语言配置支持
向 Visual Studio 扩展添加语言配置支持分为三个部分:
您可以在语言配置示例中探索工作示例。
创建 VSIX 项目
要使用语言配置创建语言服务扩展,首先请确保为 VS 实例安装了 Visual Studio 扩展开发工作负载。
接下来,通过导航到文件>新建项目来创建一个新的 VSIX 项目,搜索“vsix”并查找 VSIX 项目:
创建语言配置文件
在制作自己的语言配置文件时,您可以选择要在 JSON 文件中加入哪些方面的内容。 例如,您可以选择支持注释切换、自动添加右括号或本节中描述的可用功能的任意组合。
要添加对扩展的支持,你首先需要创建一个语言配置文件。 文件名必须遵循以下标准:使用连字符分隔文件名中的单词,并确保以 language-configuration.json
结尾。
以下代码显示了示例语言配置文件。
{
"comments": {
"lineComment": "***",
"blockComment": ["{*", "*}"]
},
"brackets": [
["@", "@"],
["#", "#"],
["$", "$"],
["(", ")"]
],
"autoClosingPairs": [
{ "open": "{", "close": "}" },
{ "open": "@", "close": "@" },
{ "open": "#", "close": "#" },
{ "open": "$", "close": "$" },
{ "open": "(", "close": ")" },
{ "open": "'", "close": "'", "notIn": ["string", "comment"] },
{ "open": "\"", "close": "\"", "notIn": ["string"] },
],
"autoCloseBefore": ";:.,=}])>` \n\t",
"surroundingPairs": [
["@", "@"],
["#", "#"],
["$", "$"],
["[", "]"],
["(", ")"],
["'", "'"],
["\"", "\""],
["`", "`"]
],
"wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)",
"indentationRules": {
"increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
"decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
}
}
配置设置
以下部分描述了语言配置文件中可用的设置。
注释切换
语言配置文件提供了两个用于注释切换的命令。 切换行注释和切换块注释。 您可以指定 comments.blockComment
和 comments.lineComment
来控制 Visual Studio 应如何注释掉行/块。
{
"comments": {
"lineComment": "//",
"blockComment": ["/*", "*/"]
}
}
当您按 Ctrl+K、Ctrl+C 时,此设置会影响 Visual Studio 文本编辑器的行为。
括号定义
当你将光标移动到此处定义的括号时,Visual Studio 会突出显示该括号及其匹配对。
{
"brackets": [["{", "}"], ["[", "]"], ["(", ")"]]
}
Visual Studio 工具 > 选项对话框中的相关设置在文本编辑器、常规、显示中是启用大括号对着色复选框。
自动关闭
当您键入 '
时,Visual Studio 会创建一对单引号并将光标放在中间:'|'
。 本节定义了此类对。
{
"autoClosingPairs": [
{ "open": "{", "close": "}" },
{ "open": "[", "close": "]" },
{ "open": "(", "close": ")" },
{ "open": "'", "close": "'", "notIn": ["string", "comment"] },
{ "open": "\"", "close": "\"", "notIn": ["string"] },
{ "open": "`", "close": "`", "notIn": ["string", "comment"] },
{ "open": "/**", "close": " */", "notIn": ["string"] }
]
}
notIn
键会在某些代码范围内禁用此功能。 例如,当您编写以下代码时:
// ES6's Template String
`ES6's Template String`;
单引号不会自动关闭。
不需要 notIn
属性的对也可以使用更简单的语法:
{
"autoClosingPairs": [ ["{", "}"], ["[", "]"] ]
}
在前面自动关闭
默认情况下,Visual Studio 仅在光标后面有空格时自动关闭对。 因此,当您在以下 JSX 代码中输入 {
时,将不会进行自动关闭:
const Component = () =>
<div className={>
^ Does not get autoclosed by default
</div>
但是,此定义会替代该行为:
{
"autoCloseBefore": ";:.,=}])>` \n\t"
}
现在,当您在 >
之前输入 {
时,Visual Studio 会使用 }
自动关闭它。
自动包围
当您在 Visual Studio 中选择一个范围并输入左括号时,Visual Studio 会用一对括号将所选内容括起来。 此功能称为自动包围,您可以在此处为特定语言定义自动包围对:
{
"surroundingPairs": [
["{", "}"],
["[", "]"],
["(", ")"],
["'", "'"],
["\"", "\""],
["`", "`"]
]
}
Visual Studio 工具> 选项中的相关设置在文本编辑器、常规、显示中是键入引号或括号时自动包围所选内容复选框。
字词模式
wordPattern
定义编程语言中被视为字词的内容。 如果设置了 wordPattern
,则代码建议功能会使用此设置来确定单词边界。
{
"wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\-\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)"
}
缩进规则
indentationRules
定义当您键入、粘贴和移动行时,或者当您使用 Ctrl+K、Ctrl+D(设置文档格式)和 Ctrl+K、Ctrl+F(格式选择)设置文本格式时,编辑器应如何调整当前行或下一行的缩进 。
{
"indentationRules": {
"increaseIndentPattern": "^((?!\\/\\/).)*(\\{[^}\"'`]*|\\([^)\"'`]*|\\[[^\\]\"'`]*)$",
"decreaseIndentPattern": "^((?!.*?\\/\\*).*\\*/)?\\s*[\\)\\}\\]].*$"
}
}
例如,如果 if (true) {
匹配 increaseIndentPattern
,那么如果您在左括号 {
后按 Enter,则编辑器将自动缩进一次,您的代码最终将为:
if (true) {
console.log();
除了 increaseIndentPattern
和 decreaseIndentPatter
之外,还有另外两个缩进规则:
indentNextLinePattern
- 如果一个行与此模式匹配,则仅应将其后的下一行缩进一次。unIndentedLinePattern
- 如果某一行与此模式匹配,则不应更改其缩进,也不应根据其他规则对其进行评估。
如果没有为编程语言设置缩进规则,则编辑器会在行以左括号结束时缩进,并在您键入右括号时取消缩进。 此处的括号由 brackets
定义。
按 Enter
onEnterRules
定义在编辑器中按 Enter 时要评估的规则列表。
{
"onEnterRules": [{
"beforeText": "^\\s*(?:def|class|for|if|elif|else|while|try|with|finally|except|async).*?:\\s*$",
"action": { "indent": "indent" }
}]
}
按 Enter 时,将根据以下属性检查光标之前、之后或上方一行的文本:
beforeText
(必备)。 匹配光标之前的文本的正则表达式(仅限于当前行)。afterText
。 匹配光标之后的文本的正则表达式(仅限于当前行)。previousLineText
。 与光标上方一行文本匹配的正则表达式。
如果所有指定的属性都匹配,则认为该规则匹配并且不评估其他 onEnterRules
。 onEnterRule
可以指定以下操作:
indent
(必备)。none, indent, outdent, indentOutdent
其中之一。none
表示新行继承当前行的缩进。indent
表示新行相对于当前行进行缩进。outdent
表示新行相对于当前行没有缩进。indentOutdent
表示插入两个新行,第一行缩进,第二行不缩进。
appendText
。 附加在新行和缩进之后的字符串。removeText
。 要从新行缩进中删除的字符数。
属性设置
在扩展项目中,确保您的 language-configuration.json
文件具有以下属性设置:
Build Action = Content
Include in VSIX = True
Copy to output = Copy always
(可选)添加语法文件
此外,您还可以添加 TextMate 语法文件来为语言提供语法着色。 TextMate 语法是正则表达式的结构化集合,并以 plist (XML) 或 JSON 文件形式编写。 请参阅语言语法。 如果您不提供特定于语言的语法文件,则使用内置的默认设置。
要添加自定义 TextMate 语法或主题文件,请执行下列步骤:
在扩展内创建一个名为“Grammars”的文件夹(或者可以是您选择的任何名称)。
在 Grammars 文件夹中,包含您想要提供自定义着色的任何 *.tmlanguage、*.plist、*.tmtheme 或 *.json 文件。
提示
.tmtheme 文件定义范围如何映射到 Visual Studio 分类(命名的颜色键)。 如需指导,您可以参考 %ProgramFiles(x86)%\Microsoft Visual Studio\<version>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg 目录中的全局 .tmtheme 文件。
创建 pkgdef 文件
接下来,创建 .pkgdef
文件。 .pkgdef
文件包含将以其他方式添加到系统注册表中的所有注册信息。 有关 pkgdef
文件的详细信息,请参阅注册 VSPackages 和什么是 pkgdef 文件?为什么要使用此文件? 在 pkgdef
文件中,您应该具有 language-configuration.json
文件的路径和语言语法的路径。 LSP 等语言服务会请求编辑器内容类型并通过语言配置获取该类型。 此信息提供了可以与开发工具通信的服务器内部的语言特定智能。 当语言服务不存在时,语言配置引擎将回退到 TextMate 语法。 .pkgdef
文件应如下所示:
[$RootKey$\TextMate\Repositories]
"AspNetCoreRazor="$PackageFolder$\Grammars
// Defines where the language configuration file for a given
// grammar name is (value of the ScopeName tag in the tmlanguage file).
[$RootKey$\TextMate\LanguageConfiguration\GrammarMapping]
"text.aspnetcorerazor"="$PackageFolder$\language-configuration.json"
// Defines where the language configuration file for a given
// language name is (partial value of the content type name).
[$RootKey$\TextMate\LanguageConfiguration\ContentTypeMapping]
"RazorLSP"="$PackageFolder$\language-configuration.json"
[$RootKey$\TextMate\LanguageConfiguration\GrammarMapping]
"text.html.basic"="$PackageFolder$\html-language-configuration.json"
"source.js"="$PackageFolder$\javascript-language-configuration.json"
"source.css"="$PackageFolder$\css-language-configuration.json"
"source.cs"="$PackageFolder$\csharp-language-configuration.json
确保按如下方式设置 pkgdef
文件的属性:
Build Action = Content
Include in VSIX = True
Copy to output = Copy always
为了使 Visual Studio 能够访问语言配置信息,请在 VSIX 包中包含 language-configuration
文件。 包含此文件意味着它将随 Visual Studio 扩展一起提供。 该文件可让 Visual Studio 知道语言配置可供使用。 要添加此文件,请编辑您的 vsixmanifest
,以添加 PKGDEF def 文件,例如:
<Asset Type="Microsoft.VisualStudio.VsPackage" Path="Test.pkgdef"/>