TypeDoc 分组标签深度指南：用 @group 系列标签掌控 API 文档的组织结构

开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载TypeDoc 生成的 API 文档默认会把类、模块等容器的子成员按 TypeScript 的 kind属性、方法、变量等自动分节展示。当你希望按业务语义例如Events生命周期重新组织成员列表、为分组编写说明、控制分组是否出现在侧边导航或在小模块中彻底关闭分组时group.md 文档介绍的group、groupDescription、showGroups、hideGroups与disableGroups五个标签就是核心工具。读完本文你将掌握这五个标签的完整用法、它们在 GroupPlugin 中的实现原理以及与groupOrder、navigation.includeGroups等配置项的配合方式。五个分组标签总览group、groupDescription、showGroups、hideGroups和disableGroups标签共同用于控制 TypeDoc 如何组织一个文档项容器 Reflection的子成员标签类型作用位置用途groupBlock 标签子成员的注释把相关 API 项归到公共标题下可多次指定groupDescriptionBlock 标签父容器注释为某个分组提供额外说明showGroups/hideGroups修饰符标签父容器注释按父容器覆盖导航树是否显示分组disableGroups修饰符标签父容器注释按父容器关闭整个分组机制这些标签只在容器的子成员索引列表中生效group决定成员归入哪个标题而showGroups、hideGroups、disableGroups作用于包含它们的父级注释。group把成员挂到自定义标题下基本用法group是 Block 标签即标签自身携带内容用于在页面索引中将若干相关 API 项置于同一个标题之下。它可以在一个注释里指定多次让同一个成员出现在多个标题下/** * groupDescription Events * Events are for... * showGroups */ export class App extends EventEmitter { /** * group Events */ static readonly BEGIN begin; /** * The event tag is equivalent to group Events * event */ static readonly PARSE_OPTIONS parseOptions; /** * The eventProperty tag is equivalent to group Events * eventProperty */ static readonly END end; }上面的示例同时演示了三个要点BEGIN显式使用group Events会出现在 Events 分组标题下event与eventProperty这类修饰符标签在语义上等价于group Events因此PARSE_OPTIONS和END也会进入 Events 组类注释上的groupDescription Events为 Events 组补充了说明文字。与category标签的关键区别在于未指定group的成员也会被自动分组——TypeDoc 会根据成员的 kind 自动创建 VariablesFunctionsMethods 等标题而category只有在至少一个子成员显式使用category时才会产生分类。正因如此group常被用来模拟自定义成员类型例如把所有事件常量统一挂到 Events 组下而不是散落在 Properties 组里。实现原理从注释到 ReflectionGroup分组的实际工作由 GroupPlugin 在转换的 resolve 阶段完成。它在RESOLVE_END与REVIVE事件上注册了处理器GroupPlugin.ts#L64-L76对每个容器 Reflection 执行分组。单个成员归属哪些组的判定逻辑在静态方法getGroups中GroupPlugin.ts#L157-L208遍历该 Reflection 注释以及其各签名注释中的groupBlock 标签把标签内容作为组名收集进一个Set对于type为 reflection 的变量如export const x someClass展开出的声明还会读取被引用声明的注释Markdown 外部文档则读取 frontmatter 中的group字段如果没有收集到任何组名就回退到默认行为把成员的 kind 转换为复数形式作为组名如ReflectionKind.pluralString(reflection.kind)得到 VariablesMethods对ReferenceReflectionre-export有特判当groupReferencesByType选项开启时按目标成员所在组归类否则统一进入 References 组见 organization.md 中groupReferencesByType说明。容器级的组装发生在getReflectionGroupsGroupPlugin.ts#L218-L258把每个子成员放入其组名下同一个成员可以出现在多个组中——这正是可多次指定group的底层支撑。最终的组结构保存在 ReflectionGroup 模型中包含title组名、description来自groupDescription和children成员列表并会序列化进 JSON 输出供主题渲染ReflectionGroup.ts#L47-L58。仓库中的测试佐证groupTag.ts 定义了一个模块包含Agroup A、B同时group A和group B、Cgroup With Spaces和未标组的D模块注释上给出三个groupDescription。对应的断言在 behavior.c2.test.ts#L469-L490项目级分组标题为[Variables, A, B, With Spaces]——未标组的D落入默认的 Variables 组B同时出现在 A 组与 B 组的children中验证了多组归属各组的description分别为 Variables descA description、空、With spaces desc验证了groupDescription的挂载。另外 groupInheritance.ts 验证了接口继承场景类实现了带group Group的接口属性且类自身未重写注释时group标签会从接口声明继承过来——测试断言Cls的分组为[Constructors, Group]prop归入 Groupbehavior.c2.test.ts#L492-L503。这说明当文档注释缺失时TypeDoc 会回退读取类型来源声明上的分组信息。groupDescription为分组写说明groupDescription是 Block 标签用于给一组 Reflection 提供额外上下文。它必须放在包含这些子成员的父 Reflection 注释中例如模块、命名空间或类的注释而不是放在子成员自己的注释里。解析规则与源码Comment.splitPartsToHeaderAndBody的处理一致第一行作为分组名必须与某个实际存在的组名完全一致后续行作为该分组的描述文本渲染在该分组标题之下。在 GroupPlugin.getReflectionGroups 中可以看到TypeDoc 遍历父注释的groupDescription标签按头部名称查找分组找到则写入description若找不到对应分组组名拼写错误、没有任何子成员属于该组TypeDoc 会输出警告日志提示该注释包含了不属于任何子成员分组的描述。编写时请确保组名与group内容逐字一致大小写、空格敏感测试用例中的 With Spaces 组名即演示了含空格组名的正确匹配方式。/** * groupDescription Events * Events are fired when the app lifecycle changes. * module */ export const BEGIN begin;导航树定制navigation.includeGroups 与 showGroups / hideGroups分组默认只影响页面内容区的成员索引不影响左侧导航树。若希望分组出现在导航中需要在配置里开启// typedoc.json { navigation: { includeGroups: true } }该行为可以通过父 Reflection 注释中的showGroups/hideGroups修饰符标签按容器覆盖。这两个标签只影响导航树不影响页面内容中的分组显示。从 DefaultTheme.tsx#L397-L401 的shouldShowGroups实现可以确认其优先级function shouldShowGroups(reflection: Reflection, opts: { includeCategories: boolean; includeGroups: boolean }) { if (opts.includeGroups) { return !reflection.comment?.hasModifier(hideGroups); } return reflection.comment?.hasModifier(showGroups) true; }即全局navigation.includeGroups: true时默认导航显示分组单个容器可用hideGroups关闭全局未开启时单个容器可用showGroups单独打开。注意这与 navigation 选项文档 中的一致性描述相同includeCategories、includeGroups等全局值可被showGroups、hideGroups、showCategories、hideCategories按 Reflection 覆盖。disableGroups按父容器关闭分组对于成员很少的小模块按 kind 拆成 VariablesFunctions 多个小节反而显得臃肿。此时可以在该容器的注释上使用disableGroups选择性地禁用分组机制/** * This is a very small module where separating members into groups by type * doesnt make sense. * module * disableGroups */ export const variable 123; export function fn() {}实现上GroupPlugin.group 在生成groups属性之前会检查reflection.comment?.hasModifier(disableGroups)GroupPlugin.ts#L134-L136命中则直接返回、不设置分组数据页面成员列表将以无标题的平铺形式呈现。文档同时提醒不存在对应的disableCategories标签因为分类只有在显式使用category时才会被创建天然按需无需关闭开关。分组顺序、排序与相关配置groupOrder 控制组的显示顺序分组之间按 GroupPlugin.sortGroupCallback 排序先用groupOrder选项GroupPlugin.WEIGHTS中的权重索引比较未列出的组按*通配符位置落位仍无法区分时按组名字母序。// typedoc.json { groupOrder: [Variables, Functions, Events, *] }当不指定groupOrder时默认顺序来自 defaultGroupOrderDocuments、Modules、Namespaces、Enums、EnumMembers、Classes、Interfaces、TypeAliases然后是 Constructors、Properties、Variables、Functions、Accessors、Methods、References。另外名为none不区分大小写的组会被默认主题特殊处理渲染在分组列表之前且不显示组标题见 organization.md 中groupOrder小节。与 categorizeByGroup 的交互categorizeByGroup选项默认false决定category分类是建立在每个分组内部还是所有成员之上。CategoryPlugin 在RESOLVE_END上以更低优先级-200晚于 GroupPlugin 的-100执行即先分组、后分类。当该选项开启时CategoryPlugin.groupCategorize 会为每个组单独生成分类使得同一分类下的方法与属性可以合并显示关闭时则在全部子成员上做一次扁平分类。搜索加权group还可以影响站内搜索的相关性排序通过 searchGroupBoosts 选项为指定组名设置权重如Classes: 1.5命中该组名的搜索结果会获得更高的相关性分值。group 路由router 选项中内置了group路由器按 Reflection 的group值创建文件夹结构。例如export function initialize(): void; /** group Opts */ export class Options {} export namespace TypeDoc { export const VERSION: string; }使用--router group时输出目录大致为docs ├── Opts │ └── Options.html ├── Functions │ └── initialize.html ├── Namespaces │ └── TypeDoc.html └── Variables └── TypeDoc.VERSION.html可见未标注group的成员同样按 kind 的复数形式落位FunctionsVariables与页面内分组逻辑完全同源。实践建议与常见坑组名必须精确一致groupDescription的第一行、groupOrder与searchGroupBoosts里的组名都需要与group标签内容逐字匹配找不到对应组会收到警告而非报错。成员可以同时属于多个组多次group会让同一成员出现在多个分组标题下适合常用入口式的重复展示但会增加页面长度需权衡。re-export 的归属默认情况下 re-export 统一进入 References 组若希望它们随目标成员一起分组开启groupReferencesByType。小模块用disableGroups而不是逐条group none前者一次关闭整个容器的分组语义更清晰且none组本身也有无标题展示的特殊行为可按需利用。与category的组合默认categorizeByGroup: false分类跨越所有分组呈现打开后分类嵌套在各分组内部。修改时注意 navigation 选项 中includeCategories/includeGroups的联动行为。继承场景类实现接口且未重写注释时成员会继承接口声明上的group编写跨接口的公共文档时要留意这一行为groupInheritance.ts 即为该行为的固化用例。小结group系列标签是 TypeDoc 在按 kind 自动分节这一默认行为之上提供的语义化组织层group决定成员归属groupDescription补充组说明showGroups/hideGroups精细控制导航disableGroups提供逃生通道。它们的实现在 GroupPlugin 与 CategoryPlugin 中以先分组、后分类的插件链完成结果由 ReflectionGroup 模型承载并进入 JSON/HTML 输出配合 organization.md 的groupOrder、output.md 的navigation与searchGroupBoosts选项可以完整掌控生成站点中成员的组织、顺序、导航呈现与搜索权重。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc category 标签详解为 API 文档组织分类、排序与导航TypeDoc category 标签详解为 API 文档组织分类、排序与导航 category 是 TypeDoc 提供的一个块标签Block Tag开发工具文档Papermerge DMS标签系统深度解析用彩色标签高效组织文档的完整指南Papermerge DMS标签系统深度解析用彩色标签高效组织文档的完整指南 Papermerge是一款开源文档管理系统DMS专为数字档案尤其是扫描文后端TypeDoc 外部 Markdown 文档实战用 document 标签、projectDocuments 选项与 Frontmatter 组织长文指南TypeDoc 外部 Markdown 文档实战用 document 标签、projectDocuments 选项与 Frontmatter 组织长文指南开发工具文档上一篇ice.js 小程序组件使用指南内置组件、JSX 语法与 HTML 标签兼容方案下一篇Android性能优化终极指南Sunflower Macrobenchmark实战解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考