开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载导读sortStrategy是 TypeDoc 提供的一个块级标签Block Tag允许开发者在单个模块、命名空间、类或接口的注释上局部覆盖全局--sort排序策略从而让不同声明采用不同的成员展示顺序。本文以 TypeDoc 仓库gh_mirrors/ty/typedoc中的 sortStrategy 标签文档 为核心结合src/lib/utils/sort.ts、GroupPlugin.ts、CategoryPlugin.ts等源码实现与测试用例完整讲解该标签的用法、作用范围、全部可用策略及底层排序机制帮助你在需要按源码顺序展示 API、而非默认按字母排序等场景下精准控制文档输出。标签概览与适用场景sortStrategy是一个块级标签关于块级标签与行内标签的区别参见 tags 文档其作用是在局部覆盖 sort 选项 配置的全局排序策略。它适用于以下四种容器声明模块module命名空间namespace类class接口interface典型场景当某个类的成员方法有明确的使用顺序如先看常用方法再看不常用方法按源码顺序阅读更符合人的直觉而全局的字母序排序反而会打乱这种逻辑时即可用该标签单独调整这一类声明的排序而不影响其他声明。作用范围仅限直接子级sortStrategy的排序覆盖只作用于声明自身的直接子级direct children。若该声明下存在一个又包含子级的嵌套声明例如嵌套命名空间那么这些孙级成员不会按照该标签的规则排序。例如在如下结构中/** * sortStrategy source-order */ export namespace Outer { export const z 1; export namespace Inner { export const a 1; // 不会被 Outer 上的 sortStrategy 影响 export const b 2; // 不会被 Outer 上的 sortStrategy 影响 } }Outer的直接子级z与Inner按源码顺序排序而Inner内部成员a、b仍遵循全局默认排序策略。用法示例官方文档给出的经典示例是一个类的方法更适合按源码顺序阅读而不是按字母排序。/** * sortStrategy source-order */ export class Class { commonMethod(): void; commonMethod2(): void; lessCommonMethod(): void; uncommonMethod(): void; }加上该标签后TypeDoc 渲染Class时其成员将按照commonMethod → commonMethod2 → lessCommonMethod → uncommonMethod的源码出现顺序排列而不是按字母顺序。标签的写法注意点标签必须位于声明前的 JSDoc/TSDoc 注释块内值需为合法的排序策略名称多个策略之间可以用逗号或空白分隔例如sortStrategy static-first, alphabetical写法上既支持单行/** sortStrategy source-order */也支持多行块注释见上面示例。全部可用排序策略从源码 SORT_STRATEGIES 定义 可以确认TypeDoc 当前支持的全部排序策略如下该列表与 organization 选项文档 中列出的策略一一对应策略名称排序规则source-order按文件、再按文件内位置排序即源码顺序alphabetical按名称字母序localeCompare排序alphabetical-ignoring-documents字母序但忽略不移动文档类反射enum-value-ascending仅对枚举成员生效按枚举值升序enum-value-descending仅对枚举成员生效按枚举值降序enum-member-source-order仅对枚举成员生效按源码顺序static-first静态成员排在实例成员之前instance-first实例成员排在静态成员之前visibility按可见性排序public → protected → privaterequired-first必选成员排在可选成员之前kind按kindSortOrder选项定义的反射类型顺序external-last外部符号排在最后documents-first文档类反射排在最前documents-last文档类反射排在最后需要注意其中enum-value-ascending、enum-value-descending、enum-member-source-order等策略仅对枚举类容器有意义源码实现中它们会先判断a.kind ReflectionKind.EnumMember非枚举成员时返回false不参与排序在其他声明上使用不会产生预期的枚举排序效果。与全局 sort 选项的关系sortStrategy本质上是 sort 选项 的局部覆盖。全局配置默认值为{ sort: [ kind, instance-first, alphabetical-ignoring-documents ] }该默认值定义在 defaults.ts 中先按反射类型kind顺序由kindSortOrder决定、再静态成员优先instance-first、最后忽略文档按字母序alphabetical-ignoring-documents。全局--sort选项支持多个策略按顺序叠加例如$ typedoc --sort static-first --sort alphabetical规则是策略按顺序依次应用若较早的策略已经能确定两个反射的相对顺序后面的策略不再参与比较这与getSortFunction中sortReflections的循环比较实现一致见 sort.ts。同理sortStrategy标签内若给出多个策略如sortStrategy source-order, static-first也会按同样逻辑处理——只不过source-order几乎总能给出非等比较因此后续策略实际很少生效官方文档亦指出[source-order, static-first]等价于[source-order]。此外还有两个相关选项值得了解sortEntryPointstypedoc.ts默认true控制是否对页面顶层成员应用sort排序设为false可禁用顶层排序kindSortOrdertypedoc.ts当排序策略中包含kind时用于指定反射类型的相对顺序默认顺序同样定义在 defaults.ts。源码实现解析标签如何被解析与生效sortStrategy的解析与生效涉及两条主要代码路径。1. 标签声明注册该标签在 tsdoc-defaults.ts 中被列入 TypeDoc 支持的 TSDoc 标签集合因此它既能被/** ... */块注释识别也能被行注释等 TypeDoc 支持的注释形式识别。2. 排序策略的读取与生效GroupPlugin负责生成分组与 CategoryPlugin负责生成分类中各自实现了getSortFunction方法。以 GroupPlugin.ts 为例通过reflection.comment?.getTag(sortStrategy)读取标签内容用Comment.combineDisplayParts将标签文本合并为字符串按/[,\s]/逗号或空白切分得到策略列表用partition(strategies, isValidSortStrategy)分离合法与非法策略非法策略名会通过logger.warn输出警告提示某个注释指定了不存在的排序策略合法的策略传入getSortFunction(this.application.options, valid)生成排序函数。CategoryPlugin.ts 的逻辑类似区别在于它不再对非法策略重复告警注释写明GroupPlugin 先运行并已告警只做过滤。3. 排序函数与比较器getSortFunction位于 sort.ts它会把kindSortOrder字符串数组映射为ReflectionKind枚举数组并补齐未指定的类型然后返回sortReflections闭包。比较时对每个策略依次调用sortss与sortss前者为真则a排前返回 -1后者为真则b排前返回 1全部策略都无法区分则返回 0保持原有相对顺序。以source-order策略的实现为例sort.ts它通过getSymbolIdFromReflection取得反射对应的符号先比较packageName再比较packagePath最后比较pos源码中的位置从而还原按文件、按文件内位置的源码顺序若符号缺失例如反射已被移出项目则保守地返回false不重排。测试用例验证仓库提供了针对该标签的行为测试 sortStrategyTag.ts覆盖了主要用法/** sortStrategy source-order */ export namespace A { export const b 1; export function c() {} export const a 2; } /** sortStrategy alphabetical */ export namespace B { export function c() {} export const b 1; export const a 1; } /** sortStrategy invalid, source-order, invalid2 */ export namespace E {}该测试验证了命名空间A指定source-order后成员按b → c → a的源码顺序输出命名空间B指定alphabetical后成员按字母序输出未加标签的命名空间C保持全局默认排序证明覆盖是局部的命名空间E的标签中包含invalid、invalid2等非法策略时会触发日志警告但不会导致转换失败合法策略source-order仍被应用。实践建议确认容器类型sortStrategy只在模块、命名空间、类、接口上有效放在普通成员如方法、属性上不会产生排序效果。明确作用层级只影响直接子级若需让嵌套命名空间也按自定义顺序需在嵌套声明上再单独加标签。策略名务必拼写正确非法策略名会在构建时输出 warningcomment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid且不会参与排序。与分组/分类联动该标签同时影响 GroupPlugin 与 CategoryPlugin 内部成员的排序因此在开启分组或分类时同样生效。相关文档与源码索引标签文档site/tags/sortStrategy.md全局排序选项site/options/organization.md#sort排序策略定义与比较器实现src/lib/utils/sort.ts标签解析与告警src/lib/converter/plugins/GroupPlugin.ts、src/lib/converter/plugins/CategoryPlugin.ts选项声明与校验src/lib/utils/options/sources/typedoc.ts默认排序策略src/lib/utils/options/defaults.ts行为测试src/test/converter2/behavior/sortStrategyTag.ts赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc private 标签详解成员可见性覆盖、ReflectionFlag.Private 与 --excludePrivate 排除机制TypeDoc private 标签详解成员可见性覆盖、ReflectionFlag.Private 与 excludePrivate 排除机制 本文以 T开发工具文档SaaS Boilerplate代码覆盖率目标与实现策略SaaS Boilerplate代码覆盖率目标与实现策略 你还在为SaaS应用的测试漏洞担忧一文解决代码覆盖率难题 在SaaS应用开发中测试覆盖率是衡量代前端后端认证鉴权AI 技能Hello 算法桶排序Bucket Sort原理、代码实现与均匀分桶策略详解Hello 算法桶排序Bucket Sort原理、代码实现与均匀分桶策略详解 桶排序Bucket Sort是《Hello 算法》hello algo教程文档示例工程教育上一篇OpenSpeedy开源游戏变速工具在Windows上的3分钟终极指南下一篇Dify 工作流 DSL 模板导入完整指南40 模板开箱即用5 分钟跑通第一个流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考