在TypeDoc中获取类型参数的纯文本表示

TypeDoc是一个强大的TypeScript文档生成工具，它能够将TypeScript代码中的类型信息转换为结构化的JSON格式。然而，有时开发者需要更简单的类型表示形式，而不是复杂的嵌套结构。

问题背景

在TypeScript代码中，我们经常会遇到泛型类型参数，例如K[]或T[]。当使用TypeDoc生成文档时，这些类型参数会被转换为详细的JSON结构，包含了类型种类、元素类型、引用信息等。虽然这种结构化的表示对于某些用途很有价值，但在某些场景下，开发者可能只需要简单的类型字符串表示。

解决方案

要实现将类型参数转换为纯文本表示，我们需要编写一个自定义的TypeDoc插件。这个插件的主要功能是拦截TypeDoc的类型处理过程，并将复杂的类型结构替换为简单的字符串表示。

插件实现原理

1. 监听创建事件：插件需要监听TypeDoc转换过程中的各种创建事件，如参数创建、声明创建等。

2. 获取类型字符串：对于每个被创建的元素，使用TypeScript编译器API获取其类型的字符串表示。

3. 替换类型信息：将原始的类型结构替换为包含类型字符串的UnknownType对象。

完整插件示例

以下是一个可以处理参数和返回类型等所有位置的完整插件实现：

import td from "typedoc";

export function load(app) {
    const replacements = new Map();

    // 监听所有相关的创建事件
    app.converter.on(td.Converter.EVENT_CREATE_PARAMETER, replaceTypes);
    app.converter.on(td.Converter.EVENT_CREATE_DECLARATION, replaceTypes);
    app.converter.on(td.Converter.EVENT_CREATE_SIGNATURE, replaceTypes);

    app.converter.on(td.Converter.EVENT_RESOLVE_BEGIN, () => {
        for (const [reflection, type] of replacements) {
            reflection.type = type;
        }
        replacements.clear();
    });

    function replaceTypes(context, reflection) {
        const symbol = context.project.getSymbolFromReflection(reflection);
        if (!symbol) return;

        const typeStr = context.checker.typeToString(
            context.checker.getTypeOfSymbol(symbol)
        );
        replacements.set(reflection, new td.UnknownType(typeStr));
    }
}

应用场景

这种技术特别适用于以下场景：

1. 自定义文档生成：当你需要将TypeScript API文档集成到现有文档系统中时，简单的类型字符串可能更易于处理。

2. 快速原型开发：在开发初期，可能只需要基本的类型信息，而不需要完整的类型结构。

3. 简化文档展示：对于某些用户界面，简单的类型表示可能比复杂的嵌套结构更易于阅读和理解。

注意事项

1. 信息丢失：这种方法会丢失原始类型结构中的详细信息，如泛型约束、类型参数关系等。

2. 插件执行时机：需要在TypeDoc解析过程的正确阶段进行类型替换，通常是在创建反射对象之后，但在最终解析之前。

3. 性能考虑：对于大型项目，频繁的类型字符串化操作可能会影响文档生成速度。

通过这种自定义插件的方式，开发者可以灵活地控制TypeDoc输出的类型信息格式，满足各种不同的文档需求。