嵌入式编程语言
Visual Studio Code 为编程语言提供了丰富的语言功能。正如您在 语言服务器扩展指南中所阅读的那样，您可以编写语言服务器来支持任何编程语言。然而，要实现对嵌入式语言的这种支持需要付出更多的努力。
如今，嵌入式语言的数量越来越多，例如：
- HTML 中的 JavaScript 和 CSS
- JavaScript 中的 JSX
- 模板语言中的插值，例如 Vue、Handlebars 和 Razor
- PHP 中的 HTML
本指南重点介绍嵌入式语言的语言功能的实现。如果您有兴趣为嵌入式语言提供语法突出显示，可以在语法突出显示指南中找到信息。
本指南包括两个示例，说明构建此类语言服务器的两种方法：语言服务和请求转发。我们将审查这两个示例并总结每种方法的优缺点。
两个示例的源代码可以在以下位置找到：
这是我们将要构建的嵌入式语言服务器：
html1出于说明目的，两个示例都贡献了一种新语言。您可以创建一个文件.html1并测试以下功能：
- HTML 标签的补全
<style>标签中 CSS 的补全- CSS 诊断（仅在语言服务示例中）
语言服务
语言服务是一个为单一语言实现编程语言功能的库。语言服务器可以嵌入语言服务来处理嵌入语言。
以下是 VS Code 对 HTML 支持的概述：
- 内置的html 扩展仅提供 HTML 的语法突出显示和语言配置。
- 内置的html-language-features 扩展包括一个 HTML 语言服务器，为 HTML 提供编程语言功能。
- HTML 语言服务器使用vscode-html-languageservice来支持 HTML。
- CSS 语言服务器使用vscode-css-languageservice来支持 HTML 中的 CSS。
HTML 语言服务器分析 HTML 文档，将其分解为语言区域，并使用相应的语言服务来处理语言服务器请求。
例如：
- 对于 的自动完成请求
<|，HTML 语言服务器使用 HTML 语言服务来提供 HTML 完成。 - 对于 的自动完成请求
<style>.foo { | }</style>，HTML 语言服务器使用 CSS 语言服务来提供 CSS 完成。
让我们检查一下lsp-embedded-language-service示例，它是 HTML 语言服务器的简化版本，可实现 HTML 和 CSS 的自动完成以及 CSS 的诊断错误。
语言服务样本
注意：此示例假定您了解编程语言功能主题和语言服务器扩展指南。该代码构建在lsp-sample之上。
源代码可在microsoft/vscode-extension-samples获取。
与lsp-sample相比，客户端代码是相同的。
如上所述，服务器将文档分解为不同的语言区域来处理嵌入的内容。
这是一个简单的例子：
<div></div>
<style>.foo { }</style>
在这种情况下，服务器会检测到该<style>标签，并将其标记.foo { }为 CSS 区域。
给定特定位置的自动完成请求，服务器使用以下逻辑来计算响应：
- 如果该位置属于任何区域
- 使用具有该区域语言的虚拟文档来处理它，同时用空格替换所有其他区域
- 如果位置超出任何区域
- 使用 HTML 中的虚拟文档来处理它，同时用空格替换所有区域
例如，在这个位置进行自动完成时：
<div></div>
<style>.foo { | }</style>
服务器确定该位置在该区域内，并计算具有以下内容的虚拟 CSS 文档（█ 代表空格）：
███████████
███████.foo { | }████████
然后，服务器用于vscode-css-languageservice分析该文档并计算完成项目的列表。由于内容现在不包含 HTML，因此 CSS 语言服务可以毫无问题地处理它。通过用空格替换所有非 CSS 内容，我们就不必手动偏移位置。
处理完成请求的服务器代码：
connection.onCompletion(async (textDocumentPosition, token) => {
const document = documents.get(textDocumentPosition.textDocument.uri);
if (!document) {
return null;
}
const mode = languageModes.getModeAtPosition(document, textDocumentPosition.position);
if (!mode || !mode.doComplete) {
return CompletionList.create();
}
const doComplete = mode.doComplete!;
return doComplete(document, textDocumentPosition.position);
});
CSS 模式负责处理落入 CSS 区域的所有语言服务器请求：
export function getCSSMode(
cssLanguageService: CSSLanguageService,
documentRegions: LanguageModelCache<HTMLDocumentRegions>
): LanguageMode {
return {
getId() {
return 'css';
},
doComplete(document: TextDocument, position: Position) {
// Get virtual CSS document, with all non-CSS code replaced with whitespace
const embedded = documentRegions.get(document).getEmbeddedDocument('css');
// Compute a response with vscode-css-languageservice
const stylesheet = cssLanguageService.parseStylesheet(embedded);
return cssLanguageService.doComplete(embedded, position, stylesheet);
}
};
}
这是处理嵌入式语言的简单而有效的方法。然而，这种方法有一些缺点：
- 您必须不断更新您的语言服务器所依赖的语言服务。
- 包含与语言服务器不是用同一语言编写的语言服务可能具有挑战性。例如，用 PHP 编写的 PHP 语言服务器会发现包含
vscode-css-languageservice用 TypeScript 编写的内容很麻烦。
现在我们将介绍请求转发，这将解决上述问题。
请求转发
简而言之，请求转发的工作方式与语言服务类似。请求转发方法还接受语言服务器请求、计算虚拟内容并计算响应。
主要区别是：
- 虽然语言服务方法使用库来计算语言服务器响应，但请求转发将请求发送回 VS Code，以使用活动的且已为嵌入式语言注册完成提供程序的扩展。
又是一个简单的例子：
<div></div>
<style>.foo { | }</style>
自动完成是这样发生的：
- 语言客户端注册一个虚拟文本文档提供者以供
embedded-content文档使用workspace.registerTextDocumentContentProvider。 - 语言客户端劫持 的完成请求
<FILE_URI>。 - 语言客户端确定请求位置落入CSS区域。
- 语言客户端构造一个新的 URI，例如
embedded-content://css/<FILE_URI>.css. - 然后语言客户端调用
commands.executeCommand('vscode.executeCompletionItemProvider', ...)- VS Code 的 CSS 语言服务器响应此提供程序请求。
- 虚拟文本文档提供者为 CSS 语言服务器提供虚拟内容，其中所有非 CSS 代码都被替换为空格。
- 语言客户端接收来自 VS Code 的响应并将其作为响应发送。
通过这种方法，即使我们的代码不包含任何理解 CSS 的库，我们也能够计算 CSS 自动完成。随着 VS Code 更新其 CSS 语言服务器，我们无需更新代码即可获得最新的 CSS 语言支持。
现在让我们回顾一下示例代码。
请求转发示例
注意：此示例假定您了解编程语言功能主题和语言服务器扩展指南。该代码构建在lsp-sample之上。
源代码可在microsoft/vscode-extension-samples获取。
保存文档的 URI 与其虚拟文档之间的映射，并为相应的请求提供它们：
const virtualDocumentContents = new Map<string, string>();
workspace.registerTextDocumentContentProvider('embedded-content', {
provideTextDocumentContent: uri => {
// Remove leading `/` and ending `.css` to get original URI
const originalUri = uri.path.slice(1).slice(0, -4);
const decodedUri = decodeURIComponent(originalUri);
return virtualDocumentContents.get(decodedUri);
}
});
通过使用middleware语言客户端的选项，我们劫持了自动完成的请求：
let clientOptions: LanguageClientOptions = {
documentSelector: [{ scheme: 'file', language: 'html' }],
middleware: {
provideCompletionItem: async (document, position, context, token, next) => {
// If not in `<style>`, do not perform request forwarding
if (
!isInsideStyleRegion(
htmlLanguageService,
document.getText(),
document.offsetAt(position)
)
) {
return await next(document, position, context, token);
}
const originalUri = document.uri.toString(true);
virtualDocumentContents.set(
originalUri,
getCSSVirtualContent(htmlLanguageService, document.getText())
);
const vdocUriString = `embedded-content://css/${encodeURIComponent(originalUri)}.css`;
const vdocUri = Uri.parse(vdocUriString);
return await commands.executeCommand<CompletionList>(
'vscode.executeCompletionItemProvider',
vdocUri,
position,
context.triggerCharacter
);
}
}
};
潜在问题
在实现嵌入式语言服务器时，我们遇到了很多问题。尽管我们还没有完美的解决方案，但我们希望提醒您，因为您也可能会遇到这些问题。
难以实现的语言功能
一般来说，跨语言区域边界工作的语言功能更难实现。例如，自动完成或悬停内容很容易实现，因为您可以检测嵌入内容的语言并根据嵌入内容计算响应。但是，格式化或重命名等语言功能可能需要特殊处理。在格式化的情况下，您需要处理单个文档内多个区域的缩进和格式化程序设置。对于重命名，使其在不同文档的不同区域中工作可能具有挑战性。
语言服务可能是有状态的且难以嵌入
VS Code 的 HTML 支持提供 HTML、CSS 和 JavaScript 语言功能。尽管 HTML 和 CSS 语言服务是无状态的，但支持 JavaScript 语言功能的 TypeScript 服务器却是无状态的。我们只在 HTML 文档中提供基本的 JavaScript 支持，因为很难告知 TypeScript 项目的状态。例如，如果您包含一个指向 CDN 上托管的库的<script>标签，您将不会在标签内获得补全。lodash_.<script>
编码和解码
文档的主要语言可能具有与其嵌入语言不同的编码或转义规则。例如，根据HTML 规范，此 HTML 文档无效：
<SCRIPT type="text/javascript">
document.write ("<EM>This won't work</EM>")
</SCRIPT>
在这种情况下，如果嵌入式 JavaScript 的语言服务器返回包含 的结果</，则应将其转义为<\/。
结论
两种方法都有其优点和缺点。
语言服务：
- + 完全控制语言服务器和用户体验。
- + 不依赖于其他语言服务器。所有代码都位于一个存储库中。
- + 语言服务器可以在所有符合 LSP 的代码编辑器中重复使用。
- - 可能很难嵌入用其他语言编写的语言服务。
- - 需要持续维护才能从语言服务依赖项中获取新功能。
请求转发：
- + 避免嵌入不是用语言服务器语言编写的语言服务的问题（例如，在 Razor 语言服务器中嵌入 C# 编译器以支持 C#）。
- + 无需维护即可从其他语言服务上游获取新功能。
- - 尚不能处理诊断错误。VS Code API 目前不支持可以“拉取”（请求）诊断的诊断提供程序。（问题）。
- - 由于缺乏控制，很难与其他语言服务器共享状态。
- - 跨语言功能可能很难实现（例如，在存在
.foo时提供 CSS 补全）。<div class="foo">
总的来说，我们建议通过嵌入语言服务来构建语言服务器，因为这种方法可以让您更好地控制用户体验，并且该服务器对于任何符合 LSP 的编辑器都是可重用的。但是，如果您有一个简单的用例，可以在没有上下文或语言服务器状态的情况下轻松处理嵌入内容，或者如果捆绑 Node.js 库对您来说是一个问题，那么您可以考虑请求转发方法。