TypeDoc 0.27 版本深度解析：类型转换与主题增强

2025-05-28 05:29:36作者：段琳惟

TypeDoc 作为 TypeScript 项目的文档生成工具，在其 0.27 版本中带来了多项重要改进。本次更新主要聚焦于类型转换的灵活性和默认主题的增强，同时也引入了一些输出格式的变化。

类型转换的灵活性提升

TypeDoc 通过编译器获取文档成员的类型信息，并将其转换为简化的结构用于渲染。0.27 版本在类型转换方面提供了更多控制选项：

@expand 标签：当应用于类型别名或接口时，引用该类型的文档会显示其属性的详细信息。这在需要全面展示类型结构时非常有用，但需注意可能显著增加文档体积。
@inline 标签：使 TypeDoc 将类型引用替换为被引用类型的副本，实现类型内容的直接内联展示。
@useDeclaredType 标签：指示 TypeDoc 使用 TypeScript 的 getDeclaredType 方法获取类型进行转换，特别适用于映射类型的场景。

这些标签为开发者提供了更精细的控制能力，可以根据文档需求灵活调整类型展示方式。

默认主题的显著改进

模块页面重构

模块/命名空间页面经过重新设计，变得更加实用：

新增 @summary 标签支持，用于定义"简短摘要"
引入 useFirstParagraphOfCommentAsSummary 选项，自动使用注释首段作为摘要
重新导出项现在会显示指向规范导出的箭头标识

智能代码渲染

TypeDoc 改进了类型渲染算法：

采用类似 Prettier 的换行策略，通过 typePrintWidth 选项控制
更智能地决定是否深入类型内部展示细节
特别优化了函数参数和返回值的展示方式

告警支持

新增对 GitHub 风格告警/提示框的支持，可以在注释和 Markdown 文档中使用标准格式突出重要信息。

输出格式增强

TypeDoc 现在支持定义多个输出目标：

{
    "outputs": [
        {
            "name": "html",
            "path": "../docs"
        },
        {
            "name": "json",
            "path": "../docs/docs.json"
        }
    ]
}