void 项目 HTML 语言功能扩展深度解析架构、配置与开发调试实战【免费下载链接】void开源AI代码编辑器Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/void导读extensions/html-language-features是 void开源 AI 代码编辑器中负责 HTML 与 Handlebars 文件语言智能的核心扩展它为编辑器提供补全、悬停文档、格式化、折叠、语义高亮、标签自动闭合等完整语言能力。本文将围绕该扩展的官方文档从功能清单、客户端/服务端架构、全部配置项、开发调试工作流以及底层语言服务接入方式五个层面展开帮助你在使用 void 时精准配置 HTML 编辑体验或在 fork 该扩展后快速搭建开发环境。扩展概述随编辑器分发、可禁用不可卸载根据 README.md 的说明该扩展与编辑器本体一同打包分发bundled因此可以禁用disabled用户可以在扩展管理界面中关闭它不可卸载cannot be uninstalled它属于编辑器内置组件无法从安装目录移除。在 package.json 中可以看到它的激活条件为onLanguage:html与onLanguage:handlebars即打开.html或.handlebars文件时才激活扩展并启动语言服务器进程。扩展的main入口指向./client/out/node/htmlClientMain桌面端browser入口指向./client/dist/browser/htmlClientMainWeb 端说明它同时支持桌面与浏览器两种运行环境并声明支持虚拟工作区virtualWorkspaces: true与不受信任的工作区untrustedWorkspaces.supported: true。从 package.nls.json 的本地化描述可知该扩展的职责是 Provides rich language support for HTML and Handlebar files即同时覆盖 HTML 与 Handlebars 模板语言。核心功能清单官方 README 将详细功能文档指向 VS Code 官方 HTML 语言文档结合本仓库源码尤其是 htmlClient.ts 与 htmlMode.ts可以确认以下能力在实现层面真实存在功能实现位置说明智能补全CompletionhtmlMode.ts基于htmlLanguageService.doComplete2支持标签、属性、属性值补全悬停文档HoverhtmlMode.ts通过doHover展示标签/属性文档与 MDN 引用格式化FormattinghtmlMode.ts通过format方法格式化配置合并自settings.html.format文档高亮Document HighlighthtmlMode.ts匹配标签高亮文档链接Document LinkshtmlMode.ts识别src、href等引用链接文档符号Document SymbolshtmlMode.ts大纲视图中的符号列表折叠范围FoldinghtmlFolding.ts标签块与!-- #region --折叠选择范围Selection RangeshtmlMode.ts智能选择扩展语义高亮Semantic TokenssemanticTokens.ts实验性语义 Token 着色自动补引号/自动闭合标签autoInsertion.ts通过自定义html/autoInsert请求实现嵌入式语言校验javascriptMode.ts、cssMode.ts校验script与style内嵌代码另外htmlClient.ts 中还内置了两个特殊补全项在空文档中键入时提供HTML5 骨架片段!DOCTYPE html完整模板在行首匹配到!-- #时提供折叠区域标记片段!-- #region --/!-- #endregion --这两个片段由客户端直接注册无需语言服务器参与。架构解析Language Client Language Server该扩展采用典型的 LSPLanguage Server Protocol客户端/服务端架构这一点在 CONTRIBUTING.md 中也被明确为扩展将 html language service 包装为一个 Language Server。客户端client/客户端目录包含node桌面与browserWeb两套入口核心逻辑集中在 htmlClient.ts文档选择器与设置同步documentSelector由语言参与者language participants见 languageParticipants.ts动态生成synchronize.configurationSection同步[html, css, javascript, js/ts]四组设置到服务端。初始化选项initializationOptions声明embeddedLanguages: { css: true, javascript: true }、handledSchemas: [file]并设置customCapabilities.rangeFormatting.editLimit: 10000限制单次范围格式化最多 10000 个编辑。格式化提供者动态注册客户端会根据html.format.enable配置动态注册/注销范围格式化提供者见 htmlClient.ts避免因晚注册导致的冲突源码注释提到 issue #71652。自定义协议消息包括html/customDataChanged自定义数据变更通知、html/customDataContent读取自定义数据内容、html/autoInsert自动插入请求与html/semanticTokens语义 Token 请求。扩展变更自动重启当语言参与者集合发生变化例如安装/卸载了新的语言扩展时客户端会在 2 秒后自动重启语言服务器htmlClient.ts。服务端server/服务端同样提供node与browser两套入口核心入口为 htmlServer.ts其内部按模式mode组织语言能力htmlModeHTML 标签级能力直接委托给vscode-html-languageservicecssMode / javascriptMode处理style与script内嵌内容并支持嵌入式语言的自动切换与补全合并见 embeddedSupport.tsformatting统一格式化编排见 formatting.ts语言模型缓存languageModelCache缓存解析后的 HTML 文档对象缓存容量为 10 个文档、TTL 60 秒见 htmlMode.ts。服务端还通过 customData.ts 拉取自定义数据提供者fetchHTMLDataProviders从而支持用户在配置中声明自定义 HTML 标签与属性。配置项全解析该扩展的全部配置在 package.json 的contributes.configuration中声明本地化说明位于 package.nls.json。以下按类别完整列出补全Completion配置项类型默认值说明html.completion.attributeDefaultValueenumdoublequotes接受补全后属性值的默认形式doublequotes、singlequotes、empty不填值html.suggest.html5booleantrue是否提示 HTML5 标签、属性与属性值html.autoCreateQuotesbooleantrue输入属性赋值时是否自动创建引号引号类型由html.completion.attributeDefaultValue决定格式化Formatting配置项类型默认值说明html.format.enablebooleantrue启用/禁用默认 HTML 格式化器html.format.wrapLineLengthinteger120每行最大字符数0表示不换行html.format.unformattedstring|nullwbr不参与重排的标签列表逗号分隔null时默认取 HTML5 phrasing content 全集html.format.contentUnformattedstring|nullpre,code,textarea内容不参与重排的标签列表null时默认取pre服务端在格式化时还会强制追加script见 htmlMode.tshtml.format.indentInnerHtmlbooleanfalse是否缩进head与body区块html.format.preserveNewLinesbooleantrue是否保留元素前的既有换行仅作用于元素之间不作用于标签内部或文本html.format.maxPreserveNewLinesnumber|nullnull单块最多保留的连续换行数null表示不限html.format.indentHandlebarsbooleanfalse是否格式化并缩进{{#foo}}/{{/foo}}html.format.extraLinersstring|nullhead, body, /html前面需要额外空行的标签列表null时默认取head, body, /htmlhtml.format.wrapAttributesenumauto属性换行策略auto仅超长时换行、force除首个属性外全部换行、force-aligned换行并对齐、force-expand-multiline每个属性都换行、aligned-multiple超长时换行并垂直对齐、preserve保留原有换行、preserve-aligned保留换行并对齐html.format.wrapAttributesIndentSizenumber|nullnull换行属性的缩进字符数null用默认缩进当wrapAttributes为aligned时忽略html.format.templatingbooleanfalse是否识别 django、erb、handlebars、php 模板语言标签html.format.unformattedContentDelimiterstring保持该字符串之间的文本内容不重排校验与悬停Validation Hover配置项类型默认值说明html.validate.scriptsbooleantrue是否校验内嵌脚本html.validate.stylesbooleantrue是否校验内嵌样式html.hover.documentationbooleantrue悬停时是否显示标签与属性文档html.hover.referencesbooleantrue悬停时是否显示指向 MDN 的参考链接输入与行为Typing Behavior配置项类型默认值说明html.autoClosingTagsbooleantrue自动闭合 HTML 标签html.mirrorCursorOnMatchingTagbooleanfalse已废弃deprecated建议改用editor.linkedEditing用于在匹配标签上镜像光标html.trace.serverenumoff跟踪客户端与服务端之间的 LSP 通信off、messages、verbose日志输出到 HTML Language Server 输出面板此外扩展通过configurationDefaults为[html]与[handlebars]两种语言设置了默认的editor.suggest.insertMode: replace即补全默认以替换模式插入并通过jsonValidation为*.html-data.json与package.json注册 JSON Schema 校验自定义数据格式的 JSON 文件与扩展自身 package.json。自定义数据Custom Datahtml.customData配置项接受一个相对文件路径数组指向符合 custom data 格式的 JSON 文件。编辑器在启动时加载这些数据从而为自定义的 HTML 标签、属性和属性值提供补全与校验支持。需要注意路径相对于工作区根目录只考虑工作区文件夹级别的设置workspace folder settings当自定义数据源发生变化时客户端会通过html/customDataChanged通知服务端刷新见 htmlClient.ts。开发调试工作流CONTRIBUTING.md 给出了完整的本地开发指南以下步骤均可在本仓库中直接执行环境搭建与编译克隆本仓库GitHub_Trending/void2/void仓库根目录存放着扩展代码、cli与src/vs等编辑器核心源码在仓库根目录运行npm i将同时安装extensions/html-language-features/的依赖extensions/html-language-features/server/的依赖gulp等开发依赖用编辑器打开extensions/html-language-features/作为工作区在该目录下运行npm run compile或开发时用npm run watch构建客户端与服务端。这两个脚本分别调用gulp compile-extension:html-language-features-client/compile-extension:html-language-features-server见 package.json。启动扩展调试在 Debug 视图中运行Launch Extension调试目标它会启动一个加载了html-language-features扩展的新编辑器实例打开一个.html文件以激活扩展此时扩展会启动 HTML 语言服务器进程在设置中添加html.trace.server: verbose即可在 HTML Language Server 输出面板观察客户端与服务端之间的通信在client/目录中设置断点可调试扩展与语言服务器客户端如需调试语言服务器进程本身在打开html-language-features工作区的窗口中使用Attach to Node Process命令选择命令行中包含htmlServerMain的进程将鼠标悬停在code进程上可查看完整命令行随后可在server/目录下设置断点修改代码后在被启动的实例中执行Reload Window命令即可重载扩展。深入修改语言智能链接 vscode-html-languageserviceHTML 语言智能的实际算法补全、悬停、格式化等并不在本扩展内而是位于独立的vscode-html-languageservice库中。本扩展只是将该库包装为 LSP 服务端。若要修复 HTML 智能相关问题或改进语言特性应修改vscode-html-languageservice本身同时扩展支持以开发版本的方式本地链接该库进行交互式调试克隆vscode-html-languageservice仓库在其根目录运行npm i在该仓库运行npm link会编译并链接该库在html-language-features/server/目录运行npm link vscode-html-languageservice用多根工作区multi-root workspace同时打开vscode-html-languageservice与html-language-features在server/目录运行npm run watch以链接版本重新编译扩展在vscode-html-languageservice中修改代码后再次运行Launch Extension调试目标新实例就会使用你的开发版本语言服务从而可以交互式验证语言特性改动。这种扩展仅做 LSP 封装、算法下沉到独立库的分层设计使 HTML 语言智能可以被其他编辑器或工具链复用也是本扩展可维护性的关键。测试体系扩展的server/src/test/目录提供了覆盖各核心能力的测试套件可作为功能行为的权威参考completions.test.ts补全行为验证formatting.test.ts格式化输出验证配套fixtures/expected/与fixtures/inputs/中的期望/输入 HTML 文件如缩进为 4 空格与 Tab 两种风格的 19813 系列用例folding.test.ts折叠范围验证embedded.test.ts嵌入式 CSS/JS 支持验证rename.test.ts、selectionRanges.test.ts、semanticTokens.test.ts、words.test.ts分别覆盖重命名、选择范围、语义 Token 与分词逻辑。这些测试与pathCompletionFixtures/模拟目录结构以验证路径补全共同保证了语言服务的高质量回归。总结extensions/html-language-features是 void 编辑器中 HTML/Handlebars 语言体验的完整实现它以 LSP 客户端/服务端架构运行将vscode-html-languageservice的语言智能包装为可插拔的编辑器能力并通过约 20 个配置项覆盖补全、格式化、校验、悬停、自动闭合等编辑体验的方方面面。对普通用户而言掌握 package.json 中列出的配置即可精确调校 HTML 编辑行为对扩展开发者而言CONTRIBUTING.md 提供了从编译、调试到链接底层语言服务的完整工作流而server/src/test/中的测试套件则为功能改动提供了可靠的验证基线。【免费下载链接】void开源AI代码编辑器Cursor的替代方案。项目地址: https://gitcode.com/GitHub_Trending/void2/void创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考