自定义数据格式：改进 HTML 与 CSS 语言特性

2020 年 2 月 24 日，作者：Pine Wu，@octref

Web 在不断发展，其语言也在不断演进。新的实体不断被纳入 HTML 和 CSS 规范。自定义元素 (Custom Elements) 和 Houdini 允许用户扩展 HTML 和 CSS 的语义。如今，许多开发者使用的编程语言都内嵌了 HTML 和 CSS。尽管 HTML 和 CSS 的用法越来越灵活，但编辑器对新特性的支持却常常滞后。

为了让 Visual Studio Code 中的 HTML 和 CSS 语言支持与时俱进，我们设计了自定义数据格式，这是一种用于描述 HTML 和 CSS 实体的声明式 JSON 格式。VS Code 的 HTML 和 CSS 语言服务器可以读取以此格式定义的数据，并为新定义的 HTML 和 CSS 实体提供语言支持。

在这篇博文中，我们将解释该数据格式，以及用户和扩展作者如何利用它。

使用自定义数据格式

VS Code 在自动补全和悬停信息中提供有关 HTML/CSS 实体的信息

HTML and CSS Language Features

借助自定义数据格式，用户可以轻松定义新的 HTML/CSS 实体，并获得自动补全、悬停信息和其他语言特性。

首先，用户可以编写一个 JSON 文件 html.html-data.json

{
  "version": 1.1,
  "tags": [
    {
      "name": "my-button",
      "description": "My button. You should use it as in `<my-button type='alert'></mybutton>`.",
      "references": [
        {
          "name": "Bootstrap buttons",
          "url": "https://bootstrap.ac.cn/docs/4.0/components/buttons/"
        }
      ]
    }
  ]
}

然后在您的用户或工作区设置中定义一个 html.customData 值，指向该数据文件

{
  "html.customData": ["./html.html-data.json"]
}

之后您就能为所定义的实体获得语言特性支持了

Custom Data helloworld

您可以通过在 VS Code 中打开预先配置好的自定义数据 hello world 示例来尝试此功能。您可以编辑 HTML/CSS 自定义数据文件，以添加、删除或优化自定义实体的定义，并微调语言特性。

html.customData 和 css.customData 设置是使用自定义数据的一个良好起点。不过，还有其他方式可以利用自定义数据。在接下来的部分中，我们将介绍扩展作者如何共享精选的自定义数据集，或利用自定义数据来构建语言支持。

通过扩展共享自定义数据

如今，许多 Web 框架都构建在 HTML 之上。例如，Mavo 项目通过各种 mv- 属性扩展了 HTML 语法。自定义数据使得为这类 Web 框架提供支持变得容易

为所有 Mavo 属性生成自定义数据。
在扩展的 contributes.html.customData 贡献点 (Contribution Point) 中指向该自定义数据文件。
发布扩展，以帮助其他人在 VS Code 中使用 Mavo 框架。

通过下载 Mavo 扩展，用户可以在 HTML 文件中获得所有 Mavo 属性的自动补全和悬停信息

Mavo demo

该扩展的源代码位于 vscode-mavo 仓库中。我们希望这个项目能成为在 VS Code 中实现 Web 框架或语言支持的起点。您可以在 vscode-custom-data 中找到更多关于 contributes.html.customData 和 contributes.css.customData 贡献点的信息。

为语言服务器使用自定义数据

vscode-html-languageservice 和 vscode-css-languageservice 库使扩展作者可以轻松地为那些扩展或内嵌 HTML 和 CSS 的语言实现语言服务器。最近，我们添加了一个用于加载自定义数据的 API

import { getLanguageService } from 'vscode-html-languageservice'

getLanguageService({
  customDataProviders: [...]
})

我们内置的 HTML 语言服务器利用此 API 加载了一套我们从各种来源收集的精选自定义数据

W3C 的 HTML、CSS 和 WAI-ARIA 规范
Mozilla Developer Network
Mozilla 的 mdn-data 和 mdn-browser-compat-data 包
Chrome 的 CSS 属性使用情况排名

我们已将这套数据发布到 NPM。您也可以在 GitHub 上找到这些数据。语言服务器的作者可以将此数据集与我们的 HTML/CSS 语言服务结合使用，为他们那些扩展或内嵌 HTML/CSS 的语言实现支持；或者他们也可以使用这些数据为那些转译为 HTML/CSS 的语言（如 Pug 或 Stylus）实现支持。最后，我们将继续维护这个数据集，以便在 VS Code 中为 HTML/CSS 提供最新的语言支持。

总结

VS Code 团队致力于为 Web 语言提供良好的编辑体验。通过自定义数据格式，我们紧跟最新的 HTML 和 CSS 语言特性，并为用户和扩展作者提供了一个简单的接口来定制他们的 HTML 和 CSS 编辑体验。

Simple interface

您可以在 vscode-custom-data 仓库中阅读更多关于自定义数据格式的信息，您可以在那里提交问题和功能请求。

编码愉快！

Pine Wu，VS Code 团队成员 @octref