给右栏「预览」支持一种新文件类型——按文件后缀/内容分派到一个渲染组件,展示(或所见即所得编辑),并提供导出。已用此流程做了 4 个:CrepeEditor(.md 文档 WYSIWYG)、MarpPreview(Marp 幻灯)、SheetPreview(.csv 表格)、HtmlPreview(.html 静态页)。

何时用

要预览/编辑一种新文件类型:.vue、.json、.geojson、图片、Mermaid、.ipynb 等。
agent 产出的是文本(前端能渲染),想让用户看到排版好的效果并导出。

不该用

只是调现有 renderer 的样式 → 直接改那个组件。
要"把整个项目跑起来"(npm dev / 后端服务)→ 那是右侧终端方向(见 docs/design/right-rail-roadmap.md),不是预览渲染器。Docker 跑项目已回滚,别复活。
要渲染二进制 Office 文件(.docx/.xlsx 原文件)→ 需要 raw-bytes fetch(当前 openCodeFile.content 是 UTF-8 文本,二进制会损坏),先评估。

步骤

1. 定文件类型 + 判定

在 apps/web/src/components/preview/DocPreviewPane.tsx 的 docKind(path, content) 决定怎么识别(后缀,必要时看内容,如 Marp 靠 marp: true front-matter)。

2. (如需)装渲染库

pnpm add <lib>。优先纯前端、可离线的库(可移植硬约束)。

3. 写 `XxxPreview.tsx`

apps/web/src/components/preview/XxxPreview.tsx,约定:

props:{ content: string; fileName?: string }(content 来自 store.openCodeFile,代码 tab 编辑会实时镜像过来)。
顶部 toolbar:文件名 + 导出按钮(复用 exportUtils)。
渲染区填满。错误兜底(渲染失败显示错误,不白屏)。
可编辑的(如 crepe):保存 = api.workspaceFileWrite + useStore.getState().bumpWorkspaceFiles()(让 CodeTab 同步,防 stale 覆盖)。

4. 在 `DocPreviewPane` 分派

docKind 加分支 + render 加 if (kind === "xxx") return <XxxPreview content={...} fileName={...} />;。

实时预览(只读)用 debounced content;WYSIWYG 编辑器用 file.content + key={file.path}。

5. 导出复用 `exportUtils.ts`

downloadBlob / downloadText / printAsPdf(片段)/ printHtmlDoc(完整 html 文档)/ csvToXlsxBlob。新格式(如 docx/pptx)在组件里用对应库生成 Blob → downloadBlob。

6. 验证

./node_modules/.bin/tsc -b + 实测:打开该类型文件 → 切「预览」→ 看渲染、编辑、各导出按钮。必要时给纯函数(解析/转换)加 vitest(参考 diffUnified.test.ts)。

关键陷阱

content 是文本:workspaceFileRead 返回 UTF-8;二进制文件(.xlsx/.docx)直接读会乱码 → 二进制要 raw fetch(后续)。
WYSIWYG 别回灌 content:milkdown crepe 只在 mount 读 defaultValue,之后自己持有状态;把 content 当受控 prop 回灌会跟光标打架。切文件用 key={path} 重挂,StrictMode 双挂载要 cancelled 守卫(别销毁半成品 editor)。
双编辑器同步:可编辑 renderer 与 CodeTab 编辑同一文件 → 保存后 bumpWorkspaceFiles,CodeTab 才会重读、不会用旧缓冲覆盖。
iframe 沙箱:渲染用户内容用 sandbox="allow-scripts",别加 allow-same-origin(两者同时会让沙箱失效)。
PDF 导出:完整 <html> 文档(如 .html 页)用 printHtmlDoc(保留其 head/style);body 片段(md 渲染、表格)用 printAsPdf(body, title, "<style>…</style>")。
纯前端导出天花板:.docx 排版会打折、.pptx 丢主题样式;高保真留后端,UI 上如实标注。

add-preview-renderer

来源信息

安装方式

检查来源文件

同仓库更多 Skills

同仓库更多 Skills