开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读LocationLink是 LSPLanguage Server Protocol3.14 起引入、在 3.18 规范中完整保留的一种结果类型用于在转到定义Go to Definition、转到声明Go to Declaration、转到实现Go to Implementation与转到类型定义Go to Type Definition等请求中表达从源位置到目标位置之间的链接关系。相比仅包含uri与range的Location它额外携带来源选区与目标选区信息让编辑器能实现更精确的悬停下划线、目标高亮与跳转选中行为。读完本文你将掌握LocationLink的全部字段语义、与Location的取舍、客户端能力协商方式以及可直接套用的 JSON 响应示例。LocationLink 是什么按照本仓库 3.18 规范文档 _specifications/lsp/3.18/types/locationLink.md 的定义LocationLink表示一个源位置与一个目标位置之间的链接Represents a link between a source and a target location。其完整 TypeScript 接口如下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 is, for example, a * symbol, then the 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由四个字段组成一个可选来源区间originSelectionRange与三个必填目标字段targetUri、targetRange、targetSelectionRange。其中三个Range字段共同描述了从哪一段文字出发、跳到哪个文件中的哪一段、跳转后高亮并选中哪一段的完整交互闭环。字段逐项详解originSelectionRange可选来源端下划线区间originSelectionRange是链接来源源位置一侧的区间类型为Range可选。它的作用是当用户在编辑器中对来源文字执行悬停或点击时编辑器用这个区间来渲染鼠标交互时的下划线underlined span。规范文档特别指出如果该字段缺省则默认使用鼠标所在位置的**单词区间word range**作为下划线区间。也就是说服务端可以不提供它由客户端用文本分析推断单词边界而提供它则可以精确控制哪些字符被视为可点击/可悬停的链接起点例如把下划线精确限定在标识符本身而非其前后缀。在 3.18 元模型 _specifications/lsp/3.18/metaModel/metaModel.json第 6749 行起中该字段被建模为{ 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. }元模型中的optional: true与规范文档中的?标记相互印证同时文档注释里defaults to the word range的表述也保持一致元模型措辞为 the word range at the definition position。targetUri必填目标资源标识targetUri是链接目标所在的资源标识符类型为DocumentUri必填。它与Location.uri语义一致指向目标位置所在文件的 URI。targetRange必填目标完整区间targetRange是链接的完整目标区间必填。规范文档给出了非常具体的语义当目标是例如一个符号symbol时targetRange是包围该符号的完整区间——不包含首尾空白但包含注释等其他内容。这段区间通常被编辑器用来在跳转前高亮整个符号。举例来说如果目标是如下函数/** * 计算两个数的和 */ function add(a: number, b: number): number { ... }那么targetRange应覆盖从 JSDoc 注释开头到函数体结束的完整范围不含前后空白而不是只覆盖add这个标识符。这样用户按下 CtrlClick 后编辑器能把整个函数区域高亮起来。targetSelectionRange必填跳转后选中并揭示的区间targetSelectionRange是跳转后应当被选中并揭示reveal的区间必填。规范明确要求它必须被targetRange包含Must be contained by thetargetRange并提示可参考DocumentSymbol#range的语义。还是以上面的add函数为例targetSelectionRange应精确覆盖add这个标识符本身。当用户跳转过去时编辑器会把这个区间滚动到可视区域并选中光标直接落在符号名上。三个区间之间的关系originSelectionRange来源端可选鼠标交互的下划线区间缺省时回退到单词区间targetRange目标端必填整个目标符号的包围区间用于高亮targetSelectionRange目标端必填⊆targetRange用于跳转后的选中与揭示。三者的配合使得一次转到定义交互在来源与目标两侧都能获得精确的视觉反馈。与 Location 的对比何时使用哪一个LocationLink与Location是两个常被放在一起讨论的结果类型。本仓库 3.18 规范文档 _specifications/lsp/3.18/types/location.md 对Location的定义是interface Location { uri: DocumentUri; range: Range; }两者的差异可以概括为维度LocationLocationLink字段urirangetargetUritargetRangetargetSelectionRange 可选originSelectionRange来源端信息无来源由请求参数TextDocumentPositionParams隐含有可通过originSelectionRange显式指定目标端粒度单一range无法区分高亮范围与选中范围targetRange与targetSelectionRange分离交互更精细引入版本基础类型3.14.0 引入用于 definition/declaration/implementation/typeDefinition 等请求前提条件无需额外能力需要客户端声明对应请求的linkSupport: true实践中的取舍很直观如果服务端只返回Location[]客户端只能把整个range同时用于高亮与选中如果返回LocationLink[]客户端就能区分整个符号高亮与精确选中符号名。因此凡是需要精细交互体验的现代语言服务端都倾向于在客户端支持时返回LocationLink[]。支撑类型DocumentUri、Range 与 PositionLocationLink依赖三个基础类型理解它们才能正确构造字段值。DocumentUri即目标文档的 URI 字符串DocumentUri类型通常形如file:///path/to/file.ts或untitled:Untitled-1。Range本仓库 3.18 规范 _specifications/lsp/3.18/types/range.md 定义Range由零基的start与end两个Position组成end是**排他exclusive**的——类比编辑器中的选区。若想包含某一行连同行尾换行符应把end指向下一行的起始处例如{ start: { line: 5, character: 23 }, end : { line: 6, character: 0 } }Position_specifications/lsp/3.18/types/position.md 定义Position是文档中两个字符之间的位置由零基的line与零基的character组成不支持-1之类的特殊值character的语义由初始化时协商的PositionEncodingKind决定utf-8/utf-16默认服务端必须支持/utf-32若character超过行长度则默认回退到行长度。构造targetRange与targetSelectionRange时必须遵守targetSelectionRange被targetRange包含的约束而这两者内部又要使用排他的end语义精确切分区间。使用场景四个跳转类请求LocationLink在本仓库 3.18 规范中作为结果类型出现在四个请求的响应里请求方法名文档位置客户端能力Go to DefinitiontextDocument/definition_specifications/lsp/3.18/language/definition.mdtextDocument.definition.linkSupportGo to DeclarationtextDocument/declaration_specifications/lsp/3.18/language/declaration.mdtextDocument.declaration.linkSupportGo to ImplementationtextDocument/implementation_specifications/lsp/3.18/language/implementation.mdtextDocument.implementation.linkSupportGo to Type DefinitiontextDocument/typeDefinition_specifications/lsp/3.18/language/typeDefinition.mdtextDocument.typeDefinition.linkSupport这四个请求的响应类型均为Location | Location[] | LocationLink[] | null部分结果partial result类型为Location[] | LocationLink[]。以定义请求为例_specifications/lsp/3.18/language/definition.md 中完整给出了请求定义方法textDocument/definition参数DefinitionParams继承TextDocumentPositionParams、WorkDoneProgressParams、PartialResultParams结果Location | Location[] | LocationLink[] | null部分结果Location[] | LocationLink[]错误异常时返回错误码与消息服务端一侧的对应 server capability 为definitionProvider: boolean | DefinitionOptions声明请求为declarationProvider: boolean | DeclarationOptions | DeclarationRegistrationOptions实现请求为implementationProvider类型定义请求为typeDefinitionProvider。返回LocationLink[]之前服务端必须确认客户端已在initialize阶段声明了对应的linkSupport: true。客户端能力协商linkSupportLocationLink[]自 3.14.0 引入且依赖对应客户端能力linkSupport。以定义请求为例_specifications/lsp/3.18/language/definition.md 中的客户端能力定义为export interface DefinitionClientCapabilities { /** * Whether definition supports dynamic registration. */ dynamicRegistration?: boolean; /** * The client supports additional metadata in the form of definition links. * * since 3.14.0 */ linkSupport?: boolean; }声明、实现、类型定义请求的客户端能力DeclarationClientCapabilities、ImplementationClientCapabilities、TypeDefinitionClientCapabilities均包含同名的linkSupport?: boolean字段。服务端只有在读取到对应linkSupport: true时才应返回LocationLink[]否则应回退到Location[]或Location以保证与旧客户端兼容。实战示例一次完整的转到定义响应综合上面的字段语义假设用户在src/main.ts的鼠标位置悬停/点击了add服务端返回如下的LocationLink[]响应textDocument/definition{ jsonrpc: 2.0, id: 3, result: [ { originSelectionRange: { start: { line: 10, character: 8 }, end: { line: 10, character: 11 } }, targetUri: file:///workspace/src/math.ts, targetRange: { start: { line: 5, character: 0 }, end: { line: 15, character: 1 } }, targetSelectionRange: { start: { line: 6, character: 9 }, end: { line: 6, character: 12 } } } ] }其中originSelectionRange精确圈定了src/main.ts第 10 行第 8~11 字符的add调用处作为鼠标悬停下划线targetUri指向目标文件src/math.tstargetRange覆盖整个add函数含 JSDoc 注释从第 5 行到第 15 行供编辑器高亮整个函数targetSelectionRange第 6 行add标识符被targetRange包含跳转后光标与选中精确落在函数名上。从元模型看结构一致性3.18 的元模型 _specifications/lsp/3.18/metaModel/metaModel.json 将LocationLink描述为Represents the connection of two locations. Provides additional metadata over normalLocations, including an origin range并在其properties数组中逐一建模了四个字段originSelectionRangeoptional: true引用Range、targetUri基础类型DocumentUri、targetRange引用Range、targetSelectionRange引用Range。这份机器可读的元模型既用于生成各语言 SDK 的类型定义也印证了规范文档 _specifications/lsp/3.18/types/locationLink.md 中接口定义的字段名、类型与可选性完全一致。同一结构的LocationLink也保留在 3.17 的 _specifications/lsp/3.17/types/locationLink.md 中说明它是跨版本稳定的核心类型。使用注意事项小结版本前提LocationLink[]作为结果类型自 3.14.0 引入务必先通过linkSupport能力确认客户端支持再返回该类型。区间包含关系targetSelectionRange必须被targetRange包含否则客户端行为未定义可能产生错误的高亮/选中。端语义Range的end是排他的构造含整行的区间时应让end指向下一行第 0 字符。回退策略客户端不支持linkSupport时服务端应回退返回Location/Location[]保持协议兼容。字符偏移语义Position.character的计数单位取决于协商的PositionEncodingKind服务端需与客户端保持一致避免多字节字符下偏移错位。综上LocationLink用四个字段把来源下划线、目标 URI、目标高亮区间、目标选中区间完整建模是 LSP 3.14 跳转类请求实现精细交互体验的核心类型正确实现它需要同时理解Position/Range/DocumentUri基础类型、四个跳转请求的响应契约以及linkSupport能力协商流程。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐Language Server Protocol 3.18 Document Link 请求规范文档链接定位与解析完整指南Language Server Protocol 3.18 Document Link 请求规范文档链接定位与解析完整指南 导读 本文基于 language开发工具LSP linkedEditingRange 深度解析Language Server Protocol 3.18 链接编辑范围协议详解LSP linkedEditingRange 深度解析Language Server Protocol 3.18 链接编辑范围协议详解 本文以 Languag开发工具Language Server Protocol 3.18 交互式消息请求 window/showMessageRequest 完整指南Language Server Protocol 3.18 交互式消息请求 window/showMessageRequest 完整指南 本指南深入解析 LSP开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考