ARTICLE DETAIL

资讯详情

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

语言服务器协议(LSP)linked editing range 请求详解:从协议定义到源码实现

语言服务器协议(LSP)linked editing range 请求详解:从协议定义到源码实现 开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读textDocument/linkedEditingRange是 LSPLanguage Server Protocol自 3.16.0 起引入的一项核心语言特性当用户在文档中编辑一个符号时客户端向语言服务器发起请求服务器返回与当前位置符号内容相同、可一并编辑的所有范围range从而实现一次修改、多处同步的联动编辑linked editing。本文以本仓库 _specifications/lsp/3.19/language/linkedEditingRange.md 为骨架结合 3.19 版规格中的 general/initialize.md、metaModel/metaModel.json 等源码级证据完整讲解该请求的客户端/服务端能力声明、参数与响应结构、约束条件及典型应用场景帮助读者在实现语言服务器或客户端时快速落地这一特性。一、什么是 linked editing range联动编辑linked editing是编辑器中的常见交互模式当用户编辑一个符号时文档中所有与该符号内容相同的其他位置被关联起来同步更新。典型场景包括HTML/XML 标签对编辑div的开始标签时/div结束标签同步改名JSX 组件标签MyComponent与/MyComponent联动Markdown 链接/锚点、LaTeX 环境等成对出现的语法结构。LSP 通过textDocument/linkedEditingRange请求将这一能力标准化请求由客户端发送到服务器用于返回文档中给定位置处符号的范围以及所有与该符号内容相同的范围。可选地服务器还可以返回一个wordPattern正则表达式形式的单词模式来描述合法内容。之后用户对其中任一范围的修改只要新内容合法就会被应用到所有其他范围上。如果服务器没有返回请求专属的wordPattern客户端将回退使用客户端语言配置中的 word pattern来校验修改后的内容是否合法。二、能力协商客户端与服务端的握手与所有 LSP 特性一样linked editing range 需要客户端和服务端在initialize阶段互相声明能力。本仓库 general/initialize.md 中同时收录了这两处声明。2.1 客户端能力textDocument.linkedEditingRange客户端能力可选属性定义如下项值property name可选textDocument.linkedEditingRangeproperty typeLinkedEditingRangeClientCapabilitiesexport 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请求动态注册/注销该能力。在源码中该能力出现在 initialize.md 第 259–264 行属于TextDocumentClientCapabilities的一部分/** * Capabilities specific to the textDocument/linkedEditingRange request. * * since 3.16.0 */ linkedEditingRange?: LinkedEditingRangeClientCapabilities;它与publishDiagnostics、foldingRange、selectionRange、callHierarchy、semanticTokens等请求能力并列声明。2.2 服务器能力linkedEditingRangeProvider服务器能力可选属性定义如下项值property name可选linkedEditingRangeProviderproperty typeboolean|LinkedEditingRangeOptions|LinkedEditingRangeRegistrationOptionsLinkedEditingRangeOptions继承自WorkDoneProgressOptionsexport interface LinkedEditingRangeOptions extends WorkDoneProgressOptions { }也就是说服务器可以在能力声明中携带workDoneProgress?: boolean声明该请求是否支持工作进度上报WorkDoneProgressOptions的完整定义见 types/workDoneProgress.md。三种取值方式true简单声明支持该请求不携带任何选项LinkedEditingRangeOptions声明支持并附带workDoneProgress等选项LinkedEditingRangeRegistrationOptions声明支持同时指定注册选项文档筛选器、静态注册 id 等用于动态注册场景。在源码中该能力出现在 initialize.md 第 917–923 行/** * The server provides linked editing range support. * * since 3.16.0 */ linkedEditingRangeProvider?: boolean | LinkedEditingRangeOptions | LinkedEditingRangeRegistrationOptions;2.3 注册选项LinkedEditingRangeRegistrationOptions当客户端支持动态注册时服务器可以在注册/静态声明中给出完整的注册选项export interface LinkedEditingRangeRegistrationOptions extends TextDocumentRegistrationOptions, LinkedEditingRangeOptions, StaticRegistrationOptions { }它同时继承了TextDocumentRegistrationOptions携带documentSelector声明该能力适用于哪些文档语言 id、模式、方案等LinkedEditingRangeOptions携带workDoneProgress等选项StaticRegistrationOptions携带id用于动态注册时的能力标识。这正是客户端能力中dynamicRegistration: true所承诺支持的返回形式——服务器可以返回(TextDocumentRegistrationOptions StaticRegistrationOptions)的组合。三、请求定义方法、参数与响应3.1 请求方法项值methodtextDocument/linkedEditingRangeparamsLinkedEditingRangeParamsresultLinkedEditingRanges|nullerror处理异常时返回带code和message的错误响应3.2 参数LinkedEditingRangeParamsexport interface LinkedEditingRangeParams extends TextDocumentPositionParams, WorkDoneProgressParams { }参数继承自两个基类TextDocumentPositionParams定义见 types/textDocumentPositionParams.mdinterface TextDocumentPositionParams { /** * The text document. */ textDocument: TextDocumentIdentifier; /** * The position inside the text document. */ position: Position; }其中TextDocumentIdentifier携带文档 URIPosition携带零基zero-based的行/列坐标line、character。WorkDoneProgressParams定义见 types/workDoneProgress.mdexport interface WorkDoneProgressParams { /** * An optional token that a server can use to report work done progress. */ workDoneToken?: ProgressToken; }客户端可以在参数中附带workDoneToken让服务器通过$/progress通知上报该请求的处理进度。注意进度令牌只在请求尚未返回响应的期间内有效取消请求即取消进度。一个完整的 JSON-RPC 请求示例{ jsonrpc: 2.0, id: 3, method: textDocument/linkedEditingRange, params: { textDocument: { uri: file:///folder/index.html }, position: { line: 2, character: 5 }, workDoneToken: 1d546990-40a3-4b77-b134-46622995f6ae } }3.3 响应结果LinkedEditingRangesexport 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[]—— 可一并修改的范围列表必须满足三条硬性约束等长identical length所有 range 的字符长度必须一致内容相同identical text content所有 range 覆盖的文本内容必须完全一致不重叠cannot overlaprange 之间互不重叠。Range的定义见 types/range.md以零基起始/结束位置表示end位置是独占的exclusive范围相当于编辑器中的一次选区。例如要覆盖第 5 行第 23 个字符到第 6 行行首含换行符{ start: { line: 5, character: 23 }, end : { line: 6, character: 0 } }wordPattern?: string—— 可选的单词模式正则表达式用于描述这些 range 的合法内容。如果省略客户端将回退使用其语言配置中的 word pattern 校验修改结果。实际开发中的典型做法服务器返回的ranges中包含光标所在位置的那个 range通常排在列表最前这样客户端可以直观地以当前位置为基准执行联动编辑。3.4 错误处理如果textDocument/linkedEditingRange请求处理过程中发生异常服务器将返回带有code和message的错误响应而不是LinkedEditingRanges结果。四、结合源码验证请求的类型模型与元数据本仓库的 metaModel/metaModel.json 是 3.19 版协议的机器可读类型模型其中完整收录了该请求及其类型定义可作为实现语言服务器时的权威参考LinkedEditingRangeParams第 3426–3440 行extends引用TextDocumentPositionParamsmixins引用WorkDoneProgressParams——与协议文档定义完全一致LinkedEditingRanges第 3442–3467 行ranges为Range[]数组wordPattern为可选string并标注since: 3.16.0LinkedEditingRangeRegistrationOptions第 3469–3487 行extends引用TextDocumentRegistrationOptions与LinkedEditingRangeOptionsmixins引用StaticRegistrationOptions此外还包含LinkedEditingRangeRequest请求条目第 627 行附近以及LinkedEditingRangeOptions、LinkedEditingRangeClientCapabilities等类型定义。在 specification.md 第 664 行该请求文档通过{% include_relative language/linkedEditingRange.md %}被收录进 3.19 版完整规格书与本仓库其他语言特性completion、hover、rename 等一并构成 3.19 的协议全貌。从源码结构还可以推断与 linked editing 关系最紧密的既有请求是textDocument/rename——linked editing 负责找出可联动修改的范围真正的批量重命名语义仍由 rename 请求承载两者的能力协商、参数传递与文档筛选机制在initialize.md中采用完全一致的声明模式如selectionRangeProvider、callHierarchyProvider等均在同一结构体中并列声明。五、典型应用场景与实现要点5.1 语言服务器侧Server实现要点能力声明在initialize响应中设置capabilities.linkedEditingRangeProvider true或携带选项对象若客户端dynamicRegistration为真也可通过client/registerCapability动态注册。处理请求收到textDocument/linkedEditingRange后根据position解析出光标所在的符号如 HTML 标签名、Markdown 锚点文本再扫描文档找出所有内容相同、等长、互不重叠的范围。返回校验规则为ranges提供wordPattern如 HTML 标签名的[a-zA-Z][a-zA-Z0-9-]*以覆盖客户端语言配置缺失或不适用的场景。无结果时返回null当当前位置不存在可联动的符号时返回null表示该位置不支持 linked editing。5.2 客户端侧Client实现要点能力声明在initialize参数中设置capabilities.textDocument.linkedEditingRange { dynamicRegistration: true }若支持动态注册。触发时机在用户开始编辑如输入、粘贴或执行改名命令时若光标处存在可编辑范围先请求 linked editing range再在用户输入过程中实时把新文本同步应用到ranges中的所有范围。合法性校验用户输入的新内容需匹配wordPattern若服务器返回否则回退使用客户端语言配置的 word pattern不合法时停止同步并回滚。处理null响应服务器返回null时退化为普通单点编辑不做任何联动。5.3 一个最小化的响应示例假设用户在index.html第 2 行第 5 个字符处div的div内部触发 linked editing服务器可返回{ jsonrpc: 2.0, id: 3, result: { ranges: [ { start: { line: 2, character: 1 }, end: { line: 2, character: 4 } }, { start: { line: 2, character: 10 }, end: { line: 2, character: 13 } } ], wordPattern: [a-zA-Z][a-zA-Z0-9-]* } }此后用户将开始标签的div改为section客户端会把/div同步改为/section实现 HTML 标签的联动编辑。六、版本与适用前提linked editing range 请求自 LSP 3.16.0 起引入请求、LinkedEditingRanges、LinkedEditingRangeClientCapabilities、LinkedEditingRangeOptions、LinkedEditingRangeRegistrationOptions均标注since 3.16.0本文所述的接口形态以本仓库 3.19 版规格为准见 specification.md 与 metaModel.json在 3.17、3.18 版规格中该请求定义与 3.19 保持一致仓库的_specifications/lsp/3.17、_specifications/lsp/3.18目录下同样存在language/linkedEditingRange.md使用前请确认客户端与服务端版本均不低于 3.16.0并完成双方能力协商否则请求可能被客户端或服务器静默忽略。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐LSP Goto Implementation 请求详解textDocument/implementation 协议规范与语言服务端实现指南LSP Goto Implementation 请求详解textDocument/implementation 协议规范与语言服务端实现指南 导读 本文聚焦语开发工具GraphiQL语言服务器LSP协议的GraphQL语言服务实现GraphiQL语言服务器LSP协议的GraphQL语言服务实现 引言GraphQL开发者的智能助手 你是否曾经在编写GraphQL查询时遇到过以下痛点开发工具后端语言服务器协议LSP教程语言服务器协议LSP教程 1. 项目介绍 语言服务器协议Language Server Protocol, LSP 是一个开放标准的JSON RPC协议开发工具上一篇终极dbt选择器与标签指南高效管理大型项目的10个关键技巧下一篇IronClaw Security Review 技能实战AI 驱动的代码安全审计方法论与工程化落地创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表