尧图网页设计 
开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读本文围绕 Language Server ProtocolLSP规范中Folding Range 折叠范围请求textDocument/foldingRange展开该功能自协议 3.10.0 版本引入用于让语言服务器返回给定文本文档中的所有折叠范围使编辑器能够对代码块、注释、import 区域等进行折叠/展开操作。阅读本文后你将掌握折叠范围请求的客户端能力声明、服务端能力声明、请求参数与响应结构、预定义折叠范围类型Kind以及 3.17 新增的collapsedText自定义折叠标签等完整实战知识并能直接对照当前仓库的规范文档_specifications/lsp/3.17/language/foldingRange.md与机器可读元模型metaModel.json进行落地实现。一、请求概览客户端如何获取折叠范围Folding Range 请求由客户端编辑器发送给服务器语言服务器用于获取给定文本文档内所有可折叠的区域。其核心信息如下项目内容引入版本3.10.0since 3.10.0方向Client → Server方法名methodtextDocument/foldingRange请求参数FoldingRangeParams正常响应结果FoldingRange[] \| null部分结果partial resultFoldingRange[]错误响应请求执行过程中发生异常时返回 code 与 message其中“部分结果”意味着该请求支持PartialResultParams混入客户端可以通过进度机制增量接收部分折叠范围避免大文档一次性阻塞传输。在仓库中的 3.17 规范总文件 _specifications/lsp/3.17/specification.md 中折叠范围请求小节以{% include_relative language/foldingRange.md %}的方式被内联引用同时该文件的变更记录第 810 行附近还记载了“Add support for folding ranges as a valid response to atextDocument/foldingRangerequest”这一演进条目说明折叠范围是 3.10 之后持续完善的成熟能力。二、客户端能力声明FoldingRangeClientCapabilities客户端编辑器在initialize握手阶段通过initialize请求的capabilities.textDocument.foldingRange属性可选向服务器声明自己对折叠范围功能的支持程度。其属性名property name为textDocument.foldingRange类型为FoldingRangeClientCapabilities定义如下export interface FoldingRangeClientCapabilities { /** * Whether implementation supports dynamic registration for folding range * providers. If this is set to true the client supports the new * FoldingRangeRegistrationOptions return value for the corresponding * server capability as well. */ dynamicRegistration?: boolean; /** * The maximum number of folding ranges that the client prefers to receive * per document. The value serves as a hint, servers are free to follow the * limit. */ rangeLimit?: uinteger; /** * If set, the client signals that it only supports folding complete lines. * If set, client will ignore specified startCharacter and endCharacter * properties in a FoldingRange. */ lineFoldingOnly?: boolean; /** * Specific options for the folding range kind. * * since 3.17.0 */ foldingRangeKind? : { /** * The folding range kind values the client supports. When this * property exists the client also guarantees that it will * handle values outside its set gracefully and falls back * to a default value when unknown. */ valueSet?: FoldingRangeKind[]; }; /** * Specific options for the folding range. * since 3.17.0 */ foldingRange?: { /** * If set, the client signals that it supports setting collapsedText on * folding ranges to display custom labels instead of the default text. * * since 3.17.0 */ collapsedText?: boolean; }; }各字段的实战含义如下dynamicRegistration可选boolean客户端是否支持折叠范围提供者的动态注册。若为true客户端同时支持服务器在能力中返回FoldingRangeRegistrationOptions允许运行期通过client/registerCapability动态注册/注销折叠范围提供者而无需重启会话。rangeLimit可选uinteger客户端希望每个文档最多接收的折叠范围数量。注意它只是一个提示hint服务器可以自由决定是否遵守该上限。常用于限制超大文档的返回规模避免客户端界面渲染压力。lineFoldingOnly可选boolean若设置表示客户端只支持按整行折叠此时客户端会忽略服务器返回的FoldingRange中的startCharacter与endCharacter属性。许多编辑器如经典代码折叠实现仅做整行折叠此字段让服务器可以省去计算字符级偏移的开销。foldingRangeKind.valueSet可选FoldingRangeKind[]since 3.17.0客户端支持的折叠范围种类kind值集合。当该属性存在时客户端还保证对集合之外未知的 kind 值会**优雅降级gracefully handle**并回退到默认值不会报错。foldingRange.collapsedText可选booleansince 3.17.0若设置表示客户端支持在折叠范围上设置collapsedText以显示自定义标签代替默认的折叠文本例如将一整个函数折叠后显示为自定义摘要文本。对应地在仓库的初始化规范 _specifications/lsp/3.17/general/initialize.md 第 222–227 行可以看到该能力被挂载在客户端能力树上的确切位置与注释“Capabilities specific to thetextDocument/foldingRangerequest. since 3.10.0”。三、服务器能力声明foldingRangeProvider服务器在initialize响应的capabilities中通过属性foldingRangeProvider可选声明自己提供折叠范围能力。其类型为boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions其中FoldingRangeOptions定义如下当前为占位扩展继承自WorkDoneProgressOptions即支持工作进度上报选项export interface FoldingRangeOptions extends WorkDoneProgressOptions { }在仓库 _specifications/lsp/3.17/general/initialize.md 第 785–791 行对应声明为“The server provides folding provider support. since 3.10.0”字段foldingRangeProvider?: boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions。三种声明形式的选择策略boolean直接给true表示服务器支持折叠范围但不提供任何额外选项最简声明。FoldingRangeOptions需要表达工作进度等选项时使用。FoldingRangeRegistrationOptions当客户端dynamicRegistration为true时服务器可以在初始化时直接返回注册选项或在运行期通过动态注册机制提供折叠范围能力。其定义如下export interface FoldingRangeRegistrationOptions extends TextDocumentRegistrationOptions, FoldingRangeOptions, StaticRegistrationOptions { }它同时继承了TextDocumentRegistrationOptions通过documentSelector指定该提供者生效的文档范围可为null表示沿用客户端侧的文档选择器FoldingRangeOptions工作进度相关选项StaticRegistrationOptions提供id字段便于后续client/unregisterCapability动态注销时引用同一个注册 id。四、请求参数FoldingRangeParams请求方法为textDocument/foldingRange请求参数类型为FoldingRangeParamsexport interface FoldingRangeParams extends WorkDoneProgressParams, PartialResultParams { /** * The text document. */ textDocument: TextDocumentIdentifier; }参数要点textDocument: TextDocumentIdentifier必填目标文本文档的标识。按仓库中的类型文档 _specifications/lsp/3.17/types/textDocumentIdentifier.md文本文档使用 URI 标识协议层面 URI 以字符串传递JSON 结构为{ uri: DocumentUri }。混入WorkDoneProgressParams可选携带workDoneToken服务器可用该 token 通过$/progress通知上报请求进度例如在大型文档中报告“正在计算折叠范围 42%”支持客户端发起或服务器发起两种进度模式。混入PartialResultParams可选携带partialResultToken服务器可增量推送部分折叠范围结果客户端可提前渲染。一个完整的请求示例JSON-RPC{ jsonrpc: 2.0, id: 3, method: textDocument/foldingRange, params: { textDocument: { uri: file:///folder/file.ts }, workDoneToken: 1d546990-40a3-4b77-b134-46622995f6ae, partialResultToken: 3f8d2e6a-7c4b-4e1a-9d2f-0a1b2c3d4e5f } }从仓库元模型 _specifications/lsp/3.17/metaModel/metaModel.json第 2476–2497 行可以确认FoldingRangeParams的唯一自有属性为textDocument引用TextDocumentIdentifier并混入WorkDoneProgressParams与PartialResultParams其文档注释为“Parameters for a FoldingRangeRequest”与规范文档完全一致。五、响应结果FoldingRange 与 FoldingRangeKind5.1 响应形态请求成功时服务器返回resultFoldingRange[] | null无折叠范围时可返回null或空数组支持partial resultFoldingRange[]通过partialResultToken分块发送若请求处理过程中发生异常返回带有 code 和 message 的error响应。5.2 预定义折叠种类FoldingRangeKindFoldingRangeKind是一组预定义的折叠范围种类用于对折叠区域分类方便客户端实现“折叠所有注释Fold all comments”之类的命令。其类型本身是string因为取值集合是可扩展的服务器可以返回自定义 kind 字符串客户端按前面valueSet约定优雅降级。/** * A set of predefined range kinds. */ export namespace FoldingRangeKind { /** * Folding range for a comment */ export const Comment comment; /** * Folding range for imports or includes */ export const Imports imports; /** * Folding range for a region (e.g. #region) */ export const Region region; } /** * The type is a string since the value set is extensible */ export type FoldingRangeKind string;三个预定义取值及典型场景常量字符串值典型场景Commentcomment多行注释块、Javadoc/文档注释Importsimportsimport/include 语句块如#include、import ... fromRegionregion显式折叠区域标记如 C# 的#region/#endregion、TypeScript 的//#region5.3 折叠范围对象FoldingRangeFoldingRange代表一个可折叠区域。有效性约束起始行与结束行必须大于零即 ≥ 0 的合法行号且小于文档总行数客户端可以自由忽略无效范围。/** * Represents a folding range. To be valid, start and end line must be bigger * than zero and smaller than the number of lines in the document. Clients * are free to ignore invalid ranges. */ export interface FoldingRange { /** * The zero-based start line of the range to fold. The folded area starts * after the lines last character. To be valid, the end must be zero or * larger and smaller than the number of lines in the document. */ startLine: uinteger; /** * The zero-based character offset from where the folded range starts. If * not defined, defaults to the length of the start line. */ startCharacter?: uinteger; /** * The zero-based end line of the range to fold. The folded area ends with * the lines last character. To be valid, the end must be zero or larger * and smaller than the number of lines in the document. */ endLine: uinteger; /** * The zero-based character offset before the folded range ends. If not * defined, defaults to the length of the end line. */ endCharacter?: uinteger; /** * Describes the kind of the folding range such as comment or region. * The kind is used to categorize folding ranges and used by commands like * Fold all comments. See FoldingRangeKind for an * enumeration of standardized kinds. */ kind?: FoldingRangeKind; /** * The text that the client should show when the specified range is * collapsed. If not defined or not supported by the client, a default * will be chosen by the client. * * since 3.17.0 */ collapsedText?: string; }字段逐项说明startLine必填uinteger折叠范围的起始行0 起始。折叠区域从该行最后一个字符之后开始。startCharacter可选uinteger折叠范围起始处的字符偏移。未定义时默认取起始行的行长即整行折叠。endLine必填uinteger折叠范围的结束行0 起始。折叠区域以该行最后一个字符结束。有效性要求与startLine相同必须 ≥ 0 且小于文档总行数。endCharacter可选uinteger折叠范围结束位置之前的字符偏移。未定义时默认取结束行的行长整行折叠。kind可选FoldingRangeKind折叠范围种类如comment、region用于分类客户端可据此实现“折叠全部注释”等命令。collapsedText可选stringsince 3.17.0折叠后客户端显示的自定义文本。未定义或客户端不支持时由客户端自行选择默认显示内容。仓库元模型 _specifications/lsp/3.17/metaModel/metaModel.json 第 2500–2556 行的FoldingRange结构定义与上述完全对应其中collapsedText被标记为since 3.17.0进一步佐证该字段是 3.17 版本新增的能力。5.4 完整响应示例{ jsonrpc: 2.0, id: 3, result: [ { startLine: 1, startCharacter: 0, endLine: 5, endCharacter: 30, kind: comment }, { startLine: 7, startCharacter: 0, endLine: 10, endCharacter: 0, kind: region, collapsedText: region: init }, { startLine: 12, endLine: 20, kind: imports } ] }注意第三个条目省略了startCharacter/endCharacter此时客户端按规范默认采用对应行的行长实现整行折叠——这正好对应客户端声明lineFoldingOnly: true时服务器的优化写法。六、从规范到实现协议演进与元模型佐证6.1 能力挂载位置initialize 握手折叠范围能力是initialize握手中文本同步能力族的一员仓库源码中的确切挂载点客户端侧initialize.md 第 222–227 行TextDocumentClientCapabilities.foldingRange?: FoldingRangeClientCapabilities标注since 3.10.0服务端侧initialize.md 第 785–791 行ServerCapabilities.foldingRangeProvider?: boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions同样标注since 3.10.0。6.2 机器可读元模型metaModel当前仓库为 3.17 提供了机器可读的元模型文件方便工具链如代码生成器、类型推导器直接消费_specifications/lsp/3.17/metaModel/metaModel.jsonJSON 结构包含FoldingRangeParams第 2476 行、FoldingRange第 2500 行、FoldingRangeRegistrationOptions第 2559 行、FoldingRangeOptions第 6729 行、FoldingRangeKind第 13250 行以及FoldingRangeClientCapabilities第 12396 行等完整类型定义_specifications/lsp/3.17/metaModel/metaModel.schema.json元模型自身的 JSON Schema用于校验元模型文件的合法性_specifications/lsp/3.17/metaModel/metaModel.ts元模型的 TypeScript 类型定义可供直接以类型安全方式遍历元模型。在实现语言服务器时可以基于FoldingRangeParams的元模型定义自动生成请求处理器的类型签名再结合FoldingRange的字段约束行号有效性、字符偏移默认值规则编写折叠区域计算逻辑。6.3 3.10 → 3.17 的能力演进小结版本演进点3.10.0引入textDocument/foldingRange请求、FoldingRangeClientCapabilities、FoldingRangeOptions与FoldingRange3.17.0新增客户端foldingRangeKind.valueSet、foldingRange.collapsedText能力新增FoldingRange.collapsedText字段支持自定义折叠标签七、服务端实现检查清单在语言服务器中实现折叠范围支持建议按以下清单逐项落地声明能力在initialize响应中返回foldingRangeProvider: true或FoldingRangeOptions/FoldingRangeRegistrationOptions若客户端dynamicRegistration为真可延迟到client/registerCapability动态注册。读取客户端约束读取FoldingRangeClientCapabilities中的lineFoldingOnly决定是否输出字符级偏移、rangeLimit决定是否截断返回数量、foldingRangeKind.valueSet决定 kind 取值范围、foldingRange.collapsedText决定是否输出自定义折叠标签。解析请求从FoldingRangeParams.textDocument.uri定位文档可选支持workDoneToken进度上报与partialResultToken增量推送。计算折叠区域至少识别注释块、import 块、#region区域三类预定义 kind对行号做有效性校验≥ 0 且 文档行数可省略字符偏移以简化整行折叠场景。组织响应返回FoldingRange[]无结果返回null计算期间若需上报进度通过$/progress通知携带workDoneToken发送。异常处理解析或计算异常时返回带 code 与 message 的 error 响应。结语折叠范围请求是 LSP 文本折叠功能的核心契约客户端通过textDocument.foldingRange能力声明约束服务器通过foldingRangeProvider声明支持二者在initialize握手阶段完成协商随后以FoldingRangeParams→FoldingRange[]的请求-响应模型交付可折叠区域并支持部分结果与进度上报。3.17 引入的foldingRangeKind.valueSet与collapsedText进一步提升了折叠体验的定制空间。实现者可同时参考本仓库的规范文档 _specifications/lsp/3.17/language/foldingRange.md、初始化握手文档 _specifications/lsp/3.17/general/initialize.md 与元模型文件 _specifications/lsp/3.17/metaModel/metaModel.json确保实现与协议语义逐字段对齐。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐komorebi快捷键完全清单15个whkd热键组合打造纯键盘平铺工作流komorebi快捷键完全清单15个whkd热键组合打造纯键盘平铺工作流 komorebi https://link.gitcode.com/i/eb079e开发工具UI UX Pro Max 开源 AI 技能基于 192 条推理规则的设计系统生成与跨平台 UI/UX 实战指南UI UX Pro Max 开源 AI 技能基于 192 条推理规则的设计系统生成与跨平台 UI/UX 实战指南 本指南围绕开源仓库 ui ux pro ma开发工具Language Server Protocol 3.17 Code Lens 完整指南请求、解析与刷新机制详解Language Server Protocol 3.17 Code Lens 完整指南请求、解析与刷新机制详解 Code Lens代码透镜是 LSPL开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Language Server Protocol Folding Range 折叠范围请求完整指南（3.17）
开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读本文围绕 Language Server ProtocolLSP规范中Folding Range 折叠范围请求textDocument/foldingRange展开该功能自协议 3.10.0 版本引入用于让语言服务器返回给定文本文档中的所有折叠范围使编辑器能够对代码块、注释、import 区域等进行折叠/展开操作。阅读本文后你将掌握折叠范围请求的客户端能力声明、服务端能力声明、请求参数与响应结构、预定义折叠范围类型Kind以及 3.17 新增的collapsedText自定义折叠标签等完整实战知识并能直接对照当前仓库的规范文档_specifications/lsp/3.17/language/foldingRange.md与机器可读元模型metaModel.json进行落地实现。一、请求概览客户端如何获取折叠范围Folding Range 请求由客户端编辑器发送给服务器语言服务器用于获取给定文本文档内所有可折叠的区域。其核心信息如下项目内容引入版本3.10.0since 3.10.0方向Client → Server方法名methodtextDocument/foldingRange请求参数FoldingRangeParams正常响应结果FoldingRange[] \| null部分结果partial resultFoldingRange[]错误响应请求执行过程中发生异常时返回 code 与 message其中“部分结果”意味着该请求支持PartialResultParams混入客户端可以通过进度机制增量接收部分折叠范围避免大文档一次性阻塞传输。在仓库中的 3.17 规范总文件 _specifications/lsp/3.17/specification.md 中折叠范围请求小节以{% include_relative language/foldingRange.md %}的方式被内联引用同时该文件的变更记录第 810 行附近还记载了“Add support for folding ranges as a valid response to atextDocument/foldingRangerequest”这一演进条目说明折叠范围是 3.10 之后持续完善的成熟能力。二、客户端能力声明FoldingRangeClientCapabilities客户端编辑器在initialize握手阶段通过initialize请求的capabilities.textDocument.foldingRange属性可选向服务器声明自己对折叠范围功能的支持程度。其属性名property name为textDocument.foldingRange类型为FoldingRangeClientCapabilities定义如下export interface FoldingRangeClientCapabilities { /** * Whether implementation supports dynamic registration for folding range * providers. If this is set to true the client supports the new * FoldingRangeRegistrationOptions return value for the corresponding * server capability as well. */ dynamicRegistration?: boolean; /** * The maximum number of folding ranges that the client prefers to receive * per document. The value serves as a hint, servers are free to follow the * limit. */ rangeLimit?: uinteger; /** * If set, the client signals that it only supports folding complete lines. * If set, client will ignore specified startCharacter and endCharacter * properties in a FoldingRange. */ lineFoldingOnly?: boolean; /** * Specific options for the folding range kind. * * since 3.17.0 */ foldingRangeKind? : { /** * The folding range kind values the client supports. When this * property exists the client also guarantees that it will * handle values outside its set gracefully and falls back * to a default value when unknown. */ valueSet?: FoldingRangeKind[]; }; /** * Specific options for the folding range. * since 3.17.0 */ foldingRange?: { /** * If set, the client signals that it supports setting collapsedText on * folding ranges to display custom labels instead of the default text. * * since 3.17.0 */ collapsedText?: boolean; }; }各字段的实战含义如下dynamicRegistration可选boolean客户端是否支持折叠范围提供者的动态注册。若为true客户端同时支持服务器在能力中返回FoldingRangeRegistrationOptions允许运行期通过client/registerCapability动态注册/注销折叠范围提供者而无需重启会话。rangeLimit可选uinteger客户端希望每个文档最多接收的折叠范围数量。注意它只是一个提示hint服务器可以自由决定是否遵守该上限。常用于限制超大文档的返回规模避免客户端界面渲染压力。lineFoldingOnly可选boolean若设置表示客户端只支持按整行折叠此时客户端会忽略服务器返回的FoldingRange中的startCharacter与endCharacter属性。许多编辑器如经典代码折叠实现仅做整行折叠此字段让服务器可以省去计算字符级偏移的开销。foldingRangeKind.valueSet可选FoldingRangeKind[]since 3.17.0客户端支持的折叠范围种类kind值集合。当该属性存在时客户端还保证对集合之外未知的 kind 值会**优雅降级gracefully handle**并回退到默认值不会报错。foldingRange.collapsedText可选booleansince 3.17.0若设置表示客户端支持在折叠范围上设置collapsedText以显示自定义标签代替默认的折叠文本例如将一整个函数折叠后显示为自定义摘要文本。对应地在仓库的初始化规范 _specifications/lsp/3.17/general/initialize.md 第 222–227 行可以看到该能力被挂载在客户端能力树上的确切位置与注释“Capabilities specific to thetextDocument/foldingRangerequest. since 3.10.0”。三、服务器能力声明foldingRangeProvider服务器在initialize响应的capabilities中通过属性foldingRangeProvider可选声明自己提供折叠范围能力。其类型为boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions其中FoldingRangeOptions定义如下当前为占位扩展继承自WorkDoneProgressOptions即支持工作进度上报选项export interface FoldingRangeOptions extends WorkDoneProgressOptions { }在仓库 _specifications/lsp/3.17/general/initialize.md 第 785–791 行对应声明为“The server provides folding provider support. since 3.10.0”字段foldingRangeProvider?: boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions。三种声明形式的选择策略boolean直接给true表示服务器支持折叠范围但不提供任何额外选项最简声明。FoldingRangeOptions需要表达工作进度等选项时使用。FoldingRangeRegistrationOptions当客户端dynamicRegistration为true时服务器可以在初始化时直接返回注册选项或在运行期通过动态注册机制提供折叠范围能力。其定义如下export interface FoldingRangeRegistrationOptions extends TextDocumentRegistrationOptions, FoldingRangeOptions, StaticRegistrationOptions { }它同时继承了TextDocumentRegistrationOptions通过documentSelector指定该提供者生效的文档范围可为null表示沿用客户端侧的文档选择器FoldingRangeOptions工作进度相关选项StaticRegistrationOptions提供id字段便于后续client/unregisterCapability动态注销时引用同一个注册 id。四、请求参数FoldingRangeParams请求方法为textDocument/foldingRange请求参数类型为FoldingRangeParamsexport interface FoldingRangeParams extends WorkDoneProgressParams, PartialResultParams { /** * The text document. */ textDocument: TextDocumentIdentifier; }参数要点textDocument: TextDocumentIdentifier必填目标文本文档的标识。按仓库中的类型文档 _specifications/lsp/3.17/types/textDocumentIdentifier.md文本文档使用 URI 标识协议层面 URI 以字符串传递JSON 结构为{ uri: DocumentUri }。混入WorkDoneProgressParams可选携带workDoneToken服务器可用该 token 通过$/progress通知上报请求进度例如在大型文档中报告“正在计算折叠范围 42%”支持客户端发起或服务器发起两种进度模式。混入PartialResultParams可选携带partialResultToken服务器可增量推送部分折叠范围结果客户端可提前渲染。一个完整的请求示例JSON-RPC{ jsonrpc: 2.0, id: 3, method: textDocument/foldingRange, params: { textDocument: { uri: file:///folder/file.ts }, workDoneToken: 1d546990-40a3-4b77-b134-46622995f6ae, partialResultToken: 3f8d2e6a-7c4b-4e1a-9d2f-0a1b2c3d4e5f } }从仓库元模型 _specifications/lsp/3.17/metaModel/metaModel.json第 2476–2497 行可以确认FoldingRangeParams的唯一自有属性为textDocument引用TextDocumentIdentifier并混入WorkDoneProgressParams与PartialResultParams其文档注释为“Parameters for a FoldingRangeRequest”与规范文档完全一致。五、响应结果FoldingRange 与 FoldingRangeKind5.1 响应形态请求成功时服务器返回resultFoldingRange[] | null无折叠范围时可返回null或空数组支持partial resultFoldingRange[]通过partialResultToken分块发送若请求处理过程中发生异常返回带有 code 和 message 的error响应。5.2 预定义折叠种类FoldingRangeKindFoldingRangeKind是一组预定义的折叠范围种类用于对折叠区域分类方便客户端实现“折叠所有注释Fold all comments”之类的命令。其类型本身是string因为取值集合是可扩展的服务器可以返回自定义 kind 字符串客户端按前面valueSet约定优雅降级。/** * A set of predefined range kinds. */ export namespace FoldingRangeKind { /** * Folding range for a comment */ export const Comment comment; /** * Folding range for imports or includes */ export const Imports imports; /** * Folding range for a region (e.g. #region) */ export const Region region; } /** * The type is a string since the value set is extensible */ export type FoldingRangeKind string;三个预定义取值及典型场景常量字符串值典型场景Commentcomment多行注释块、Javadoc/文档注释Importsimportsimport/include 语句块如#include、import ... fromRegionregion显式折叠区域标记如 C# 的#region/#endregion、TypeScript 的//#region5.3 折叠范围对象FoldingRangeFoldingRange代表一个可折叠区域。有效性约束起始行与结束行必须大于零即 ≥ 0 的合法行号且小于文档总行数客户端可以自由忽略无效范围。/** * Represents a folding range. To be valid, start and end line must be bigger * than zero and smaller than the number of lines in the document. Clients * are free to ignore invalid ranges. */ export interface FoldingRange { /** * The zero-based start line of the range to fold. The folded area starts * after the lines last character. To be valid, the end must be zero or * larger and smaller than the number of lines in the document. */ startLine: uinteger; /** * The zero-based character offset from where the folded range starts. If * not defined, defaults to the length of the start line. */ startCharacter?: uinteger; /** * The zero-based end line of the range to fold. The folded area ends with * the lines last character. To be valid, the end must be zero or larger * and smaller than the number of lines in the document. */ endLine: uinteger; /** * The zero-based character offset before the folded range ends. If not * defined, defaults to the length of the end line. */ endCharacter?: uinteger; /** * Describes the kind of the folding range such as comment or region. * The kind is used to categorize folding ranges and used by commands like * Fold all comments. See FoldingRangeKind for an * enumeration of standardized kinds. */ kind?: FoldingRangeKind; /** * The text that the client should show when the specified range is * collapsed. If not defined or not supported by the client, a default * will be chosen by the client. * * since 3.17.0 */ collapsedText?: string; }字段逐项说明startLine必填uinteger折叠范围的起始行0 起始。折叠区域从该行最后一个字符之后开始。startCharacter可选uinteger折叠范围起始处的字符偏移。未定义时默认取起始行的行长即整行折叠。endLine必填uinteger折叠范围的结束行0 起始。折叠区域以该行最后一个字符结束。有效性要求与startLine相同必须 ≥ 0 且小于文档总行数。endCharacter可选uinteger折叠范围结束位置之前的字符偏移。未定义时默认取结束行的行长整行折叠。kind可选FoldingRangeKind折叠范围种类如comment、region用于分类客户端可据此实现“折叠全部注释”等命令。collapsedText可选stringsince 3.17.0折叠后客户端显示的自定义文本。未定义或客户端不支持时由客户端自行选择默认显示内容。仓库元模型 _specifications/lsp/3.17/metaModel/metaModel.json 第 2500–2556 行的FoldingRange结构定义与上述完全对应其中collapsedText被标记为since 3.17.0进一步佐证该字段是 3.17 版本新增的能力。5.4 完整响应示例{ jsonrpc: 2.0, id: 3, result: [ { startLine: 1, startCharacter: 0, endLine: 5, endCharacter: 30, kind: comment }, { startLine: 7, startCharacter: 0, endLine: 10, endCharacter: 0, kind: region, collapsedText: region: init }, { startLine: 12, endLine: 20, kind: imports } ] }注意第三个条目省略了startCharacter/endCharacter此时客户端按规范默认采用对应行的行长实现整行折叠——这正好对应客户端声明lineFoldingOnly: true时服务器的优化写法。六、从规范到实现协议演进与元模型佐证6.1 能力挂载位置initialize 握手折叠范围能力是initialize握手中文本同步能力族的一员仓库源码中的确切挂载点客户端侧initialize.md 第 222–227 行TextDocumentClientCapabilities.foldingRange?: FoldingRangeClientCapabilities标注since 3.10.0服务端侧initialize.md 第 785–791 行ServerCapabilities.foldingRangeProvider?: boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions同样标注since 3.10.0。6.2 机器可读元模型metaModel当前仓库为 3.17 提供了机器可读的元模型文件方便工具链如代码生成器、类型推导器直接消费_specifications/lsp/3.17/metaModel/metaModel.jsonJSON 结构包含FoldingRangeParams第 2476 行、FoldingRange第 2500 行、FoldingRangeRegistrationOptions第 2559 行、FoldingRangeOptions第 6729 行、FoldingRangeKind第 13250 行以及FoldingRangeClientCapabilities第 12396 行等完整类型定义_specifications/lsp/3.17/metaModel/metaModel.schema.json元模型自身的 JSON Schema用于校验元模型文件的合法性_specifications/lsp/3.17/metaModel/metaModel.ts元模型的 TypeScript 类型定义可供直接以类型安全方式遍历元模型。在实现语言服务器时可以基于FoldingRangeParams的元模型定义自动生成请求处理器的类型签名再结合FoldingRange的字段约束行号有效性、字符偏移默认值规则编写折叠区域计算逻辑。6.3 3.10 → 3.17 的能力演进小结版本演进点3.10.0引入textDocument/foldingRange请求、FoldingRangeClientCapabilities、FoldingRangeOptions与FoldingRange3.17.0新增客户端foldingRangeKind.valueSet、foldingRange.collapsedText能力新增FoldingRange.collapsedText字段支持自定义折叠标签七、服务端实现检查清单在语言服务器中实现折叠范围支持建议按以下清单逐项落地声明能力在initialize响应中返回foldingRangeProvider: true或FoldingRangeOptions/FoldingRangeRegistrationOptions若客户端dynamicRegistration为真可延迟到client/registerCapability动态注册。读取客户端约束读取FoldingRangeClientCapabilities中的lineFoldingOnly决定是否输出字符级偏移、rangeLimit决定是否截断返回数量、foldingRangeKind.valueSet决定 kind 取值范围、foldingRange.collapsedText决定是否输出自定义折叠标签。解析请求从FoldingRangeParams.textDocument.uri定位文档可选支持workDoneToken进度上报与partialResultToken增量推送。计算折叠区域至少识别注释块、import 块、#region区域三类预定义 kind对行号做有效性校验≥ 0 且 文档行数可省略字符偏移以简化整行折叠场景。组织响应返回FoldingRange[]无结果返回null计算期间若需上报进度通过$/progress通知携带workDoneToken发送。异常处理解析或计算异常时返回带 code 与 message 的 error 响应。结语折叠范围请求是 LSP 文本折叠功能的核心契约客户端通过textDocument.foldingRange能力声明约束服务器通过foldingRangeProvider声明支持二者在initialize握手阶段完成协商随后以FoldingRangeParams→FoldingRange[]的请求-响应模型交付可折叠区域并支持部分结果与进度上报。3.17 引入的foldingRangeKind.valueSet与collapsedText进一步提升了折叠体验的定制空间。实现者可同时参考本仓库的规范文档 _specifications/lsp/3.17/language/foldingRange.md、初始化握手文档 _specifications/lsp/3.17/general/initialize.md 与元模型文件 _specifications/lsp/3.17/metaModel/metaModel.json确保实现与协议语义逐字段对齐。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐komorebi快捷键完全清单15个whkd热键组合打造纯键盘平铺工作流komorebi快捷键完全清单15个whkd热键组合打造纯键盘平铺工作流 komorebi https://link.gitcode.com/i/eb079e开发工具UI UX Pro Max 开源 AI 技能基于 192 条推理规则的设计系统生成与跨平台 UI/UX 实战指南UI UX Pro Max 开源 AI 技能基于 192 条推理规则的设计系统生成与跨平台 UI/UX 实战指南 本指南围绕开源仓库 ui ux pro ma开发工具Language Server Protocol 3.17 Code Lens 完整指南请求、解析与刷新机制详解Language Server Protocol 3.17 Code Lens 完整指南请求、解析与刷新机制详解 Code Lens代码透镜是 LSPL开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考