企业官网建设流程全解析

智能组件库文档自动生成：从TypeScript类型到交互Playground

在自建 UI 组件库或设计系统（Design System）的维护过程中，“编写和同步组件文档”常常是让前端团队最头疼的苦力活：

• 每次组件重构新增了一个 Props（例如<Button loadingText="string" />），文档站往往忘记同步更新，导致业务方在群里频繁询问用法；
• 静态的 Markdown 示例只能看不能改，业务方无法实时调试不同 Props 组合下的视觉反馈。

为了实现**“组件源码即文档、零人工维护、实时双向可交互调试”**，我们设计了一套基于 TypeScript AST 静态类型提取 + AI 自动生成交互式 Playground 文档站的工业级流水线。

架构流水线：从 TSX 源码到交互式文档

[ 组件源码 Button.tsx (含 JSDoc 注释 & TS 类型) ] │ ▼ (步骤 1: TypeDoc / TS Compiler API 提取 AST) ┌─────────────────────────────────────────────────────────────┐ │ 提取结构化类型元数据 (JSON Schema): │ │ - Props 列表、类型、默认值、JSDoc 中文描述 │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ (步骤 2: 注入智能文档生成器) ┌─────────────────────────────────────────────────────────────┐ │ 自动生成三大核心模块: │ │ 1. 动态 Props 属性参数表 (实时受控切换控件) │ │ 2. 在线代码实时编译 Playground (基于 Sandpack / Sucrase) │ │ 3. 典型业务最佳实践与无障碍规范代码片段 │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ [ 渲染为现代化组件交互文档站: /docs/components/button ]

核心实现一：TypeScript 类型元数据自动化提取器

利用 TypeScript Compiler API 编写轻量解析脚本，精准提取组件的 Props 契约与注释：

// scripts/extractComponentMeta.ts import * as ts from 'typescript'; export interface PropMeta { name: string; type: string; defaultValue?: string; description: string; required: boolean; } export function extractComponentProps(filePath: string): PropMeta[] { const program = ts.createProgram([filePath], { target: ts.ScriptTarget.ES2020 }); const checker = program.getTypeChecker(); const sourceFile = program.getSourceFile(filePath); const propsList: PropMeta[] = []; if (!sourceFile) return propsList; function visit(node: ts.Node) { if (ts.isInterfaceDeclaration(node) && node.name.text.endsWith('Props')) { const type = checker.getTypeAtLocation(node); const properties = type.getProperties(); for (const prop of properties) { const propType = checker.getTypeOfSymbolAtLocation(prop, node); const docComment = ts.displayPartsToString(prop.getDocumentationComment(checker)); const isOptional = (prop.flags & ts.SymbolFlags.Optional) !== 0; propsList.push({ name: prop.name, type: checker.typeToString(propType), description: docComment || '暂无描述', required: !isOptional }); } } ts.forEachChild(node, visit); } visit(sourceFile); return propsList; }

核心实现二：交互式 Playground 运行时组件

在前端文档站中，利用提取出的 Props 元数据，动态渲染控制面板（Control Panel）与实时预览画布：

// docs/components/ComponentPlayground.tsx import React, { useState } from 'react'; import { Button, ButtonProps } from '@/components/ui/Button'; export const ButtonDocsPlayground = () => { const [variant, setVariant] = useState<ButtonProps['variant']>('default'); const [size, setSize] = useState<ButtonProps['size']>('md'); const [isLoading, setIsLoading] = useState(false); const [buttonText, setButtonText] = useState('立即生成周报'); return ( <div className="border border-slate-200 rounded-2xl overflow-hidden shadow-sm my-6 bg-white"> {/* 顶部实时渲染视窗 */} <div className="p-12 bg-slate-50/70 flex items-center justify-center min-h-[200px] border-b border-slate-200"> <Button variant={variant} size={size} isLoading={isLoading}> {buttonText} </Button> </div> {/* 底部交互式控制面板与属性表格 */} <div className="p-6 bg-white space-y-4"> <h4 className="font-bold text-slate-800 text-sm">🎛️ 实时属性调节 (Interactive Props)</h4> <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 text-xs"> <div> <label className="block text-slate-500 mb-1">variant (视觉风格)</label> <select value={variant} onChange={(e: any) => setVariant(e.target.value)} className="w-full p-2 border rounded-lg bg-white" > <option value="default">default (品牌主色)</option> <option value="secondary">secondary (次要灰)</option> <option value="outline">outline (线框镂空)</option> <option value="ghost">ghost (幽灵透明)</option> </select> </div> <div> <label className="block text-slate-500 mb-1">size (尺寸规格)</label> <select value={size} onChange={(e: any) => setSize(e.target.value)} className="w-full p-2 border rounded-lg bg-white" > <option value="sm">sm (小号)</option> <option value="md">md (中号/默认)</option> <option value="lg">lg (大号)</option> </select> </div> <div> <label className="block text-slate-500 mb-1">isLoading (加载态)</label> <label className="flex items-center space-x-2 mt-2"> <input type="checkbox" checked={isLoading} onChange={e => setIsLoading(e.target.checked)} className="rounded text-blue-600" /> <span className="text-slate-700">开启 Loading 旋转</span> </label> </div> <div> <label className="block text-slate-500 mb-1">children (按钮文案)</label> <input type="text" value={buttonText} onChange={e => setButtonText(e.target.value)} className="w-full p-1.5 border rounded-lg" /> </div> </div> </div> </div> ); };

自动化工程收益

1. 彻底终结文档滞后事故：文档直接与 TS 类型声明和 JSDoc 注释强绑定，CI 构建时自动更新文档站，Props 变动 0 遗漏；
2. 极大降低沟通成本：业务方工程师在文档站里随手点选几下就能直观看到样式与交互表现，并一键复制代码片段；
3. 沉淀出高标准的工程标杆：让自研的组件库在专业度上比肩 Ant Design 和 Tailwind UI 等一线开源体系。