ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

LSP linkedEditingRange 深度解析:Language Server Protocol 3.18 链接编辑范围协议详解

LSP linkedEditingRange 深度解析:Language Server Protocol 3.18 链接编辑范围协议详解 开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载本文以 Language Server Protocol 3.18 规范仓库 中的 linkedEditingRange 文档为骨架完整剖析该请求的定义、能力协商、参数与响应结构并结合仓库中的元模型metaModel.json与初始化流程initialize.md等源码级证据展开讲解。读者读完本文后将能正确理解并实现textDocument/linkedEditingRange请求在语言服务器中为 HTML/XML 标签对、括号、模板语法等场景提供一处修改、同步联动的编辑体验。一、Linked Editing Range 是什么一次编辑处处同步Since version 3.16.0根据 规范原文linked editing 请求由客户端发送给服务端用于针对文档中的某个给定位置返回该位置所在符号的范围以及所有内容与之相同的其他范围。可选地服务端还可以返回一个 word pattern正则表达式来描述这些范围的合法内容。当用户对其中一个范围发起重命名时只要新内容合法该重命名会被应用到所有其他范围。如果服务端没有返回结果级别的 word pattern客户端会回退使用客户端语言配置language configuration中的 word pattern。这一机制解决的是编辑器中最常见的成对符号联动需求HTML/XML 标签对修改开标签div时闭标签/div同步改名成对括号/定界符( )、[ ]、{ }、Markdown 中的**bold**等模板语法与插值表达式${variable}的起始与结束标记引号对...、...的起始与结束引号。与textDocument/renamerename.md不同rename 是基于符号语义的全局重命名服务端计算 workspace-wide 的改动而 linked editing 是基于文本内容相等的局部联动不依赖符号表适合编辑器在光标停留时即时高亮并联动编辑。二、能力协商客户端与服务端的双向声明linkedEditingRange 遵循 LSP 的标准能力协商模式客户端在initialize请求中声明自己支持该功能服务端在InitializeResult.capabilities中声明自己提供该能力。2.1 客户端能力LinkedEditingRangeClientCapabilitiesClient Capabilities:property name (optional):textDocument.linkedEditingRangeproperty type:LinkedEditingRangeClientCapabilities定义如下export interface LinkedEditingRangeClientCapabilities { /** * Whether the implementation supports dynamic registration. * If this is set to true the client supports the new * (TextDocumentRegistrationOptions StaticRegistrationOptions) * return value for the corresponding server capability as well. */ dynamicRegistration?: boolean; }其中dynamicRegistration表示客户端是否支持动态注册。若为true服务端不仅可以在initialize响应中静态声明能力还可以在运行期通过client/registerCapability动态注册对应能力值使用LinkedEditingRangeRegistrationOptions。该能力在TextDocumentClientCapabilities中位于linkedEditingRange字段since 3.16.0参见 initialize.md 中的 TextDocumentClientCapabilities 定义。2.2 服务端能力linkedEditingRangeProviderServer Capability:property name (optional):linkedEditingRangeProviderproperty type:boolean|LinkedEditingRangeOptions|LinkedEditingRangeRegistrationOptions定义如下export interface LinkedEditingRangeOptions extends WorkDoneProgressOptions { }该字段是ServerCapabilities的一部分since 3.16.0与selectionRangeProvider、callHierarchyProvider等并列参见 initialize.md 中的 ServerCapabilities 定义。三种取值形态的含义true最简单的静态声明表示服务端支持该请求不附带任何选项LinkedEditingRangeOptions在静态声明基础上附加workDoneProgress选项继承自WorkDoneProgressOptions表示该请求支持工作进度上报LinkedEditingRangeRegistrationOptions完整的注册选项形态用于动态注册场景。在initialize响应中服务端可以这样声明{ capabilities: { linkedEditingRangeProvider: true } }或带进度上报支持{ capabilities: { linkedEditingRangeProvider: { workDoneProgress: true } } }三、注册选项详解三种 Options 的组合语义Registration Options:LinkedEditingRangeRegistrationOptions定义如下export interface LinkedEditingRangeRegistrationOptions extends TextDocumentRegistrationOptions, LinkedEditingRangeOptions, StaticRegistrationOptions { }它由三部分组合而成每一部分的语义都可在 metaModel.json 中查到精确定义TextDocumentRegistrationOptionsmetaModel.json 第 4762 行起携带documentSelector字段用于限定该能力作用于哪些文档按语言、模式等过滤。若设置为null则使用客户端提供的 document selector。LinkedEditingRangeOptionsmetaModel.json 第 7117 行本身继承WorkDoneProgressOptions携带可选的workDoneProgress?: boolean声明服务端是否会在处理该请求时上报$/progress进度。StaticRegistrationOptionsmetaModel.json 第 6820 行起携带可选的id字段用于在动态注册时标识该注册项便于后续client/unregisterCapability注销。WorkDoneProgressOptions的定义见 workDoneProgress.mdexport interface WorkDoneProgressOptions { workDoneProgress?: boolean; }完整的动态注册形态示例{ linkedEditingRangeProvider: { id: linkedEditingRange-html, documentSelector: [ { language: html } ], workDoneProgress: true } }四、请求与响应textDocument/linkedEditingRange4.1 请求参数LinkedEditingRangeParamsRequest:method:textDocument/linkedEditingRangeparams:LinkedEditingRangeParams定义如下export interface LinkedEditingRangeParams extends TextDocumentPositionParams, WorkDoneProgressParams { }该类型继承两个基础类型TextDocumentPositionParams见 textDocumentPositionParams.md包含textDocument: TextDocumentIdentifier文档 URI与position: Position文档内位置。如何把用户选区转换为 position 由客户端决定客户端可以自行决定是否尊重选区方向。WorkDoneProgressParams包含可选的workDoneToken?: ProgressToken客户端可在请求中携带该 token 让服务端通过$/progress通知上报进度token 仅在请求未响应前有效。一个典型的请求 JSON{ jsonrpc: 2.0, id: 4, method: textDocument/linkedEditingRange, params: { textDocument: { uri: file:///workspace/index.html }, position: { line: 3, character: 1 } } }4.2 响应结果LinkedEditingRangesResponse:result:LinkedEditingRanges|null定义如下export interface LinkedEditingRanges { /** * A list of ranges that can be renamed together. The ranges must have * identical length and contain identical text content. The ranges cannot * overlap. */ ranges: Range[]; /** * An optional word pattern (regular expression) that describes valid * contents for the given ranges. If no pattern is provided, the client * configurations word pattern will be used. */ wordPattern?: string; }ranges是Range数组Range由零基的start/end位置构成end 为开区间见 range.md。协议对ranges施加了三条硬性约束相同长度所有范围必须等长相同文本内容所有范围包含的文本必须完全相同不可重叠任意两个范围不能有重叠部分。wordPattern是可选的正则表达式字符串用于描述这些范围的合法内容例如标识符字符集[a-zA-Z0-9_-]。当用户编辑时客户端用该正则校验新输入是否合法若合法则把改动应用到所有范围若不合法则拒绝本次编辑。若未提供wordPattern客户端将回退使用语言配置中的 word pattern与单词高亮、双击选词所用的规则一致。当服务端无法在给定位置找到可联动编辑的符号例如光标位于普通标识符上时返回null客户端不做任何联动处理。响应示例{ jsonrpc: 2.0, id: 4, result: { ranges: [ { start: { line: 3, character: 0 }, end: { line: 3, character: 5 } }, { start: { line: 7, character: 8 }, end: { line: 7, character: 13 } } ], wordPattern: [a-zA-Z0-9_-] } }4.3 错误处理Response(error):error: code and message set in case an exception happens during thetextDocument/linkedEditingRangerequest即当服务端在处理该请求过程中抛出异常时响应携带标准的 LSP 错误对象code与message例如-32603Internal Error等客户端应正确处理错误响应不对结果做任何联动编辑。五、客户端与服务端的完整交互流程一次典型的 linked editing 会话按以下步骤进行初始化协商客户端在initialize请求的capabilities.textDocument.linkedEditingRange中声明支持含dynamicRegistration服务端在InitializeResult.capabilities.linkedEditingRangeProvider中声明提供能力boolean/LinkedEditingRangeOptions/LinkedEditingRangeRegistrationOptions。用户触发用户把光标移动到成对符号如 HTML 标签、括号上客户端决定发送请求。发出请求客户端发送textDocument/linkedEditingRange携带文档 URI、光标位置以及可选的workDoneToken。服务端计算服务端定位该位置的符号扫描文档中所有文本内容与之相同的范围返回LinkedEditingRanges或null。客户端联动客户端高亮所有返回的范围用户编辑任一范围时客户端用wordPattern或语言配置的 word pattern校验新内容合法则同步应用到所有范围。在这个过程中wordPattern起到了新内容合法性校验的关键作用——这正是原文所述A rename to one of the ranges can be applied to all other ranges if the new content is valid的实现前提。六、实现要点与实战建议结合仓库中的 metaModel.json 可以核对所有类型的精确形态LinkedEditingRangeRequest请求元数据位于 metaModel.json 第 627 行附近方法名textDocument/linkedEditingRange、结果类型LinkedEditingRangesLinkedEditingRangeParams类型定义位于第 3426 行extends: TextDocumentPositionParamsmixins: WorkDoneProgressParamsLinkedEditingRanges类型定义位于第 3442 行ranges: Range[]、wordPattern?: stringsince 3.16.0LinkedEditingRangeRegistrationOptions位于第 3469 行LinkedEditingRangeOptions位于第 7117 行LinkedEditingRangeClientCapabilities位于第 13135 行。实现服务端时需要注意以下几点范围约束是硬性要求返回的ranges必须等长、文本一致、互不重叠。服务端应基于文档文本内容进行相等性匹配而非符号语义。合理控制返回范围数量如果匹配到的范围过多例如一个超大文档中某个短字符串频繁出现应评估是否全部返回协议没有数量上限但过大的集合会影响客户端高亮与编辑性能实践中可结合上下文如仅匹配同一声明块内收敛结果。与 rename 的协同linked editing 是编辑器内联的同步编辑体验而textDocument/rename是基于符号语义的全局重命名两者互补。服务端可同时声明renameProvider与linkedEditingRangeProvider让用户在快速联动与全局重命名之间按需选择。正确回退 word pattern当服务端无法给出精确的wordPattern时省略该字段即可客户端会自动使用语言配置中的 word pattern切勿返回一个与实际内容不匹配的宽松正则以免误放行非法编辑。七、版本演进与兼容性textDocument/linkedEditingRange自3.16.0引入在 3.17、3.18 与 3.19 三个版本的规范中其文档定义保持一致3.17 版 与 3.19 版 内容完全一致说明该请求的协议面自引入以来保持稳定未发生破坏性变更。在 3.18 版本中该能力完整出现在三层结构中客户端能力TextDocumentClientCapabilities.linkedEditingRange见 initialize.md服务端能力ServerCapabilities.linkedEditingRangeProvider见 initialize.md请求/响应类型LinkedEditingRangeParams、LinkedEditingRanges见 metaModel.json。兼容性前提客户端与服务端均需至少支持 3.16.0 版本的协议才能使用该功能对于更早的客户端服务端不应在能力协商中声明linkedEditingRangeProvider客户端也应忽略未知的 capability 字段按 LSP 规则未知属性应被忽略缺失属性视为不支持。参考文档3.18 linkedEditingRange 规范原文3.18 完整规范specification.md3.18 元模型metaModel.json3.18 元模型 TypeScript 视图metaModel.ts初始化流程与能力协商initialize.mdTextDocumentPositionParams 定义Range 定义Work Done Progress 机制Rename 请求与之互补的全局重命名赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐UI UX Pro Max 开源 AI 技能基于 192 条推理规则的设计系统生成与跨平台 UI/UX 实战指南UI UX Pro Max 开源 AI 技能基于 192 条推理规则的设计系统生成与跨平台 UI/UX 实战指南 本指南围绕开源仓库 ui ux pro ma开发工具LSP TextDocumentPositionParams 详解基于 language-server-protocol 3.18 的位置定位参数协议LSP TextDocumentPositionParams 详解基于 language server protocol 3.18 的位置定位参数协议 导读开发工具深入解析 LSP 的 documentHighlight 请求Language Server Protocol 3.18 文档高亮协议全解深入解析 LSP 的 documentHighlight 请求Language Server Protocol 3.18 文档高亮协议全解 textDocum开发工具创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表