开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读LocationLink是 Language Server ProtocolLSP3.14 版本引入的导航结果类型用于在“转到定义 / 声明 / 实现 / 类型定义”等请求中把源位置origin与目标位置target之间的跳转关系以结构化元数据的形式表达出来。本文以本仓库 _specifications/lsp/3.17/types/locationLink.md 为骨架结合Location、Range等基础类型以及textDocument/definition、textDocument/declaration等请求的完整定义讲清每个字段的语义、与普通Location的差异、客户端能力协商方式以及服务端返回时应当遵守的约束。读完本文你将能够在自己的 LSP 语言服务器中正确构造与解析LocationLink并理解编辑器侧如何利用它实现更精细的鼠标交互与跳转高亮。一、为什么需要 LocationLinkLocation 的局限在 LSP 3.14 之前“转到定义”等请求返回的是 _specifications/lsp/3.17/types/location.md 中定义的Locationinterface Location { uri: DocumentUri; range: Range; }它只表达“某个资源uri里的某段范围range”回答的是“去哪”但回答不了三个关键问题从哪来用户鼠标悬停或点击的“源片段”到底是哪个单词区间服务端无法告知编辑器只能自己猜测词边界目标范围细粒度不够目标处如果有注释、JSDoc、类型签名等上下文Location.range只能圈定一个整体范围无法区分“整个符号”与“可被选中跳转的那一小段”例如函数名语义缺失编辑器不知道返回的是一个位置还是一个“链接”也就无法针对链接做更丰富的交互。LocationLink正是为补齐这些元数据而生。它在本仓库的 3.17 规范文档 _specifications/lsp/3.17/types/locationLink.md 中定义如下interface LocationLink { /** * Span of the origin of this link. * * Used as the underlined span for mouse interaction. Defaults to the word * range at the mouse position. */ originSelectionRange?: Range; /** * The target resource identifier of this link. */ targetUri: DocumentUri; /** * The full target range of this link. If the target for example is a symbol * then target range is the range enclosing this symbol not including * leading/trailing whitespace but everything else like comments. This * information is typically used to highlight the range in the editor. */ targetRange: Range; /** * The range that should be selected and revealed when this link is being * followed, e.g the name of a function. Must be contained by the * targetRange. See also DocumentSymbol#range */ targetSelectionRange: Range; }二、字段逐一拆解LocationLink共四个字段其中targetUri、targetRange、targetSelectionRange为必填originSelectionRange为可选。2.1 originSelectionRange可选源端下划线区间含义链接“源”一侧的范围也就是用户鼠标所在位置那个词应该被加下划线并成为可点击热区的区间。默认行为文档注释明确说明——缺省时编辑器会回退到“鼠标位置的 word range”按词边界自动推断的词区间。也就是说即使服务端不填交互也不会彻底失效只是高亮区间可能与词的实际边界不完全一致。典型用法当用户悬停在调用foo()的foo上时originSelectionRange应指向这个foo标识符本身不含括号与参数编辑器据此画下划线若该符号带有泛型参数或路径前缀如module.foo服务端可精确指定只圈住foo。2.2 targetUri必填目标资源标识含义目标位置所在文档的资源标识符类型为DocumentUri即一个遵循 URI 规范的字符串如file:///home/user/src/main.ts。这与Location.uri完全一致。要求目标 URI 必须能唯一确定一个文本资源编辑器据此加载目标文档。2.3 targetRange必填完整目标范围含义目标符号“完整”的范围。文档注释给出精确边界规则——包含符号本身的注释等附着内容但不包含前导/尾随空白。例如一个函数声明targetRange往往覆盖从 JSDoc 注释开头到函数体结束不含缩进空白的多余部分。用途这个范围通常被编辑器用来做高亮例如跳转后把整个函数体框出来让用户一眼看到目标区域。2.4 targetSelectionRange必填跳转后的选中与揭示范围含义当链接被真正“跟随”跳转后编辑器应当选中并滚动揭示的范围例如函数的名字foo。约束必须被targetRange完整包含contained by。这保证选中区始终落在高亮区之内。与DocumentSymbol#range的关系文档注释建议参照 _specifications/lsp/3.17/language/documentSymbol.md 中DocumentSymbol的range/selectionRange二元结构理解——DocumentSymbol同样区分“符号整体范围”与“选中范围”二者的设计意图一致LocationLink只是把这套二元结构扩展到跨文件的跳转场景。2.5 字段约束小结字段类型必填核心约束 / 默认值originSelectionRangeRange否缺省回退为鼠标位置词区间用于下划线热区targetUriDocumentUri是目标资源唯一标识targetRangeRange是覆盖符号及注释、不含首尾空白用于高亮targetSelectionRangeRange是必须包含于targetRange用于选中并揭示其中Range本身由 _specifications/lsp/3.17/types/range.md 定义为零基起始与结束位置结束位置排他exclusiveinterface Range { start: Position; end: Position; }三、LocationLink 出现在哪些请求中LocationLink不会单独作为请求出现它是以下四个“跳转类”请求的结果类型之一。以 3.17 规范为准这四个请求的结构高度一致此处逐一列出关键差异。3.1 Goto DefinitiontextDocument/definition定义见 _specifications/lsp/3.17/language/definition.md客户端能力textDocument.definition.linkSupport自 3.14.0 起响应结果Location | Location[] | LocationLink[] | null部分结果Location[] | LocationLink[]。export interface DefinitionClientCapabilities { dynamicRegistration?: boolean; /** * The client supports additional metadata in the form of definition links. * since 3.14.0 */ linkSupport?: boolean; }3.2 Goto DeclarationtextDocument/declaration定义见 _specifications/lsp/3.17/language/declaration.md客户端能力textDocument.declaration.linkSupport响应结果Location | Location[] | LocationLink[] | null部分结果Location[] | LocationLink[]。3.3 Goto ImplementationtextDocument/implementation定义见 _specifications/lsp/3.17/language/implementation.md自 3.6.0 引入请求linkSupport自 3.14.0 引入客户端能力textDocument.implementation.linkSupport响应结果Location | Location[] | LocationLink[] | null部分结果Location[] | LocationLink[]。3.4 Goto Type DefinitiontextDocument/typeDefinition定义见 _specifications/lsp/3.17/language/typeDefinition.md客户端能力textDocument.typeDefinition.linkSupport响应结果Location | Location[] | LocationLink[] | null部分结果Location[] | LocationLink[]。四个请求共有的要点能力协商是前提规范明确“LocationLink[]结果类型的引入依赖对应客户端能力linkSupport”。也就是说只有在客户端将linkSupport声明为true时服务端才可以放心返回LocationLink[]否则应回退到Location[]。这一规则在 3.16 合并规范 _specifications/specification-3-16.md第 5254、5311、5370、5432 行附近中同样可见。部分结果partial result四个请求都允许以Location[] | LocationLink[]形式流式返回部分结果配合PartialResultParams使用。错误处理异常情况下返回错误码与消息error: code and message。四、从 metaModel 看 LocationLink 的机器可读定义本仓库的 _specifications/lsp/3.17/metaModel/metaModel.json约第 6520 行起为LocationLink提供了与文档等价的结构化定义是生成 SDK 绑定与校验工具的依据{ name: LocationLink, properties: [ { name: originSelectionRange, type: { kind: reference, name: Range }, optional: true, documentation: Span of the origin of this link.\n\nUsed as the underlined span for mouse interaction. Defaults to the word range at\nthe definition position. }, { name: targetUri, type: { kind: base, name: DocumentUri } }, { name: targetRange, type: { kind: reference, name: Range } }, { name: targetSelectionRange, type: { kind: reference, name: Range } } ], documentation: Represents the connection of two locations. Provides additional metadata over normal {link Location locations},\nincluding an origin range. }从该结构可以确认三点实现事实类型引用方式originSelectionRange、targetRange、targetSelectionRange均以reference引用Range类型而targetUri是base类型的DocumentUri——与文档中的 TS 接口完全一一对应唯一可选字段originSelectionRange的optional标记为true其余三个字段均为必填与文档注释一致设计定位metaModel 对LocationLink的概括性描述是“两个位置的连接提供超越普通Location的额外元数据包括一个 origin 范围”这从侧面印证了本章开篇的动机分析。此外同目录的 _specifications/lsp/3.17/metaModel/metaModel.ts 在定义联合类型时也出现了LocationLink例如Location | LocationLink形式的注释而 _data/linkableTypes.yml 将其登记为可链接类型说明它贯穿于类型系统与文档生成链路中。五、服务端实现建议与校验要点综合规范与类型定义在实现 LSP 语言服务器时可以遵循以下实践能力先行在initialize阶段读取客户端能力中的textDocument.definition.linkSupport等四个linkSupport字段据此决定响应是Location[]还是LocationLink[]。客户端能力结构见 definition.md 中的DefinitionClientCapabilities等定义。三个必填字段必须齐全targetUri、targetRange、targetSelectionRange缺一不可缺少任何一个都会使结果不符合规范可能导致编辑器解析失败。满足包含约束targetSelectionRange必须被targetRange包含。常见反例是只设置了targetRange却忘记设置targetSelectionRange导致跳转后选中区间退化或异常。合理使用可选字段originSelectionRange不是必须的但建议在“源端词边界难以推断”的场景例如带命名空间前缀、泛型或装饰器的符号引用主动提供以获得精确的下划线交互。结合部分结果对于跨多个文件的定义/实现结果可以借助PartialResultParams以Location[] | LocationLink[]流式返回改善大结果集的体验。六、结语LocationLink是 LSP 从“简单位置返回”走向“富语义跳转元数据”的关键一步它用targetUritargetRangetargetSelectionRange三元组精确描述“去哪、高亮哪、选中哪”再用可选的originSelectionRange回填“从哪来”。任何实现了definition/declaration/implementation/typeDefinition请求的语言服务器都应在客户端声明linkSupport后优先以LocationLink[]返回结果从而获得更精致的编辑器交互体验。本文所有代码与类型定义均以本仓库 3.17 规范文档及其 metaModel 为准可作为实现与校验的直接依据。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐Language Server Protocol 类型定义跳转深入解析 textDocument/typeDefinition 请求Language Server Protocol 类型定义跳转深入解析 textDocument/typeDefinition 请求 导读 本文以 LSP 规开发工具language-server-protocol 中 Diagnostic 数据结构全解析从 PublishDiagnostics 到 Pull Diagnosticslanguage server protocol 中 Diagnostic 数据结构全解析从 PublishDiagnostics 到 Pull Diagno开发工具language-server-protocol 中的 TextDocumentPositionParamsLSP 文档定位参数类型的完整解析language server protocol 中的 TextDocumentPositionParamsLSP 文档定位参数类型的完整解析 导读 Text开发工具上一篇Redux Thunk最佳实践大厂前端团队都在用的技巧下一篇StatsD集合数据结构详解高效存储唯一值创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考