一句话定位

为 DSH better-sidebar 文件浏览器补回 Word/Excel/PPT 三种 Office 文件的浏览器内预览,把原本内联在主包里的 docx-preview、Univer、SheetJS、pptx-renderer 等渲染库拆成独立客户端 bundle,让不需要看 Office 文件的用户保持主包精简。

核心能力

• 在 better-sidebar 文件资源管理器中点击 .docx 文件直接渲染预览(样式、图片、表格保留),支持 Alt + 滚轮 50%-200% 缩放
• 在 better-sidebar 文件资源管理器中点击 .xlsx 文件渲染为带公式编辑能力的电子表格,自动适配浏览器语言(中/英),保留合并单元格与列宽行高
• 在 better-sidebar 文件资源管理器中点击 .pptx 文件逐页翻看演示稿,提供上一页/下一页按钮
• 在 Side card 设置页中作为 docx/xlsx/pptx 三张独立卡片出现,可单独启用或禁用
• 预览加载或解析失败时自动回退到"下载查看"链接,保证用户始终能拿到文件
• 把 docx-preview、Univer、SheetJS、pptx-renderer 这些体积庞大的渲染库隔离在自身 bundle 中,让 better-sidebar 主包瘦身约 3.8MB

技术实现

• 语言: TypeScript + React 18 (JSX/TSX 客户端代码)
• 关键依赖: docx-preview (Word 渲染)、@univerjs/preset-sheets-core + @univerjs/presets + xlsx (Excel 转换渲染)、@aiden0z/pptx-renderer (PPT 翻页)
• 架构模式: Cordis 客户端插件,通过 ctx.betterSidebar.registerFileViewer 注册三个 FileViewerDescriptor 替换 better-sidebar 0.6.0 之后移除的内置 Office viewer,id/扩展名/fetchStrategy/priority 与原内置完全一致以保证文件路由不变
• 入口文件: src/index.ts (Node 端空壳,仅占位使 main 字段可解析) + src/client/index.tsx (实际工作全部在此,通过 window.__ModuleLoader__.load({ id, factory }) 注入浏览器)

适用场景

日常需要在 better-sidebar 文件浏览器里直接看 Office 文档、又不想为偶尔的 Word/Excel/PPT 预览承担额外主包体积的 DSH 用户。典型场景:打开一个 .docx 项目说明、一个 .xlsx 数据表、或一个 .pptx 方案稿,免去下载到本地再用 Office 打开的来回。如果你只编辑代码、Markdown 或文本文件,完全不必安装这个插件,保持主包精简。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:HuanLinOTO/dsh-plugin-better-sidebar-plugin-office

配置项

本插件无需额外配置 —— Config 接口被刻意留空,所有能力开关在 better-sidebar 的 Side card 设置页里通过三个 viewer 卡片分别控制(启用/禁用 docx、xlsx、pptx 预览)。

常见问题

Q: 安装后还需要做什么配置吗?

A: 不需要,也不存在配置项;在 profile 中安装完成后,重启 dsh web 进程并对浏览器做硬刷新(Ctrl+Shift+R)即可生效,Office 文件预览会自动接管。

Q: 和 better-sidebar 内置的 Office 预览冲突吗?

A: 必须配合 better-sidebar >=0.6.0 (该版本已移除内置的 docx/xlsx/pptx viewer);若使用更早的版本,会因为 id 重复触发 already registered 报错。

Q: 支持旧格式 .doc/.xls/.ppt 吗?

A: 不支持。本插件只识别 .docx、.xlsx、.pptx 三种扩展名,与 better-sidebar 路由约定的扩展名匹配一致;旧版二进制格式需先用 Office 另存为新格式。

Q: Excel 预览能保留原来的样式吗?

A: v1 只还原单元格数据、公式、合并单元格、列宽、行高;字体、填充、边框、对齐、条件格式、图表等样式不在支持范围(SheetJS 社区版不解析这些,Pro 版是商业付费),需要看原貌请用错误兜底或工具栏里的"下载查看"链接。

Q: 预览失败怎么办?

A: 渲染或解析失败会自动降级到"下载查看"链接,你可以直接下载到本地用 Office 打开;常见原因是文件损坏、受密码保护或体积过大。

Q: 怎么单独禁用某个类型的预览?

A: 进入 better-sidebar 的 Side card 设置页,"文件预览"清单中会出现 docx、xlsx、pptx 三张独立卡片,每张卡片都可以单独开启或关闭,关闭后该扩展名会回退到通用 binary 下载视图。

Q: 安装后体积会不会反而变大?

A: 主包 better-sidebar 因此瘦身近 3.8MB(从约 5.9MB 全套降到约 2.2MB 压缩);只有真正需要 Office 预览的 profile 才承担自身约 23MB 的客户端 bundle,属于按需取舍。

上手难度

入门 — 安装一行命令、重启即用,没有任何配置项或环境变量需要设置;Office 文件在文件浏览器中点击即预览。

已知问题与限制

• Excel 预览不还原单元格样式(字体、填充、边框、对齐)、条件格式、图表 —— 源码 src/client/xlsx-to-univer.ts 明确标注 v1 范围,且受限于 SheetJS 社区版能力
• 必须在 better-sidebar >=0.6.0 版本下使用,否则与内置 viewer 重复注册;更早的 better-sidebar 用户需先升级
• 客户端 bundle 体积较大(约 23MB,内含 docx-preview、Univer、SheetJS、pptx-renderer 全部代码);仅建议确实需要 Office 预览的 profile 安装
• 仅支持 .docx/.xlsx/.pptx 新格式,旧版 .doc/.xls/.ppt 二进制格式不在支持范围
• 构建配置中 tsdown.config.ts 为 SheetJS/JSZip 配置了 browser-entry alias、为 pptx-renderer 屏蔽了 import.meta.resolve,升级这几个依赖版本时需同时验证产物不含 Node builtin 引用

📌 本插件已收录于 dshfind 插件超市，点击上方徽章直达主页。

dsh-better-sidebar-plugin-office

DSH web 插件：为 better-sidebar 的编辑器提供 Office 三件套文件预览（.docx / .xlsx / .pptx）。

背景

better-sidebar 曾内置这三个 viewer，但 docx-preview / Univer（+ SheetJS）/ pptx-renderer 会把 client bundle 撑到约 23MB。本插件把它们拆成独立 bundle，better-sidebar 本体不再内联 Office 渲染库（约 5.9MB 全套 → 2.2MB 压缩），需要 Office 预览的用户单独安装本插件即可。

功能

• 通过 ctx.betterSidebar.registerFileViewer 注册 3 个 viewer（id 与内置一致）：
  • docx：.docx，docx-preview 保真渲染（样式/图片/表格，Alt+滚轮缩放）
  • xlsx：.xlsx，Univer sheets 预设（数据 + 公式 + 合并单元格 + 列宽/行高）
  • pptx：.pptx，@aiden0z/pptx-renderer 浏览器原生预览（翻页导航）
• viewer 描述符形状与原内置完全一致（mediaUrl 策略、priority 0、title/icon），因此：
  • 既有文件路由行为不变（扩展名匹配优先于 binary-download / code 兜底）
  • Side card 设置页自动显示这三个 viewer 的启用开关
  • 加载/渲染失败回退到「下载查看」链接
• 客户端组件自包含：自带 locale（中/英）与 CSS，不依赖 better-sidebar 的 client 内部实现

依赖 better-sidebar 版本

需要 better-sidebar >= 0.6.0（已移除内置 office viewer 的版本），否则会与内置 docx/xlsx/pptx 注册冲突（already registered）。

开发

pnpm install
pnpm run typecheck   # 类型门禁（需先构建 DSH-better-sidebar 的 lib/types）
pnpm test            # vitest（xlsx→Univer 转换 + 注册描述符）
pnpm run build       # tsdown 双产物（lib/index.js + lib/client.js）

tsdown.config.ts 含 jszip / xlsx 的 browser-entry alias（SheetJS/JSZip 在 CJS 降级后残留 Node builtin 引用）与 import.meta.resolve 空定义（pptx-renderer 的 PDF.js 探测）。改动这些库版本时需一并验证 client bundle 不含 Node builtin。

安装（profile）

# 从 npm 安装（推荐）：
dsh plugin --profile web add @huanlin/dsh-plugin-better-sidebar-plugin-office

# 本地开发（link: 热更新）
dsh plugin --profile web add "link:D:/Projects/deepseek-harness/dsh-better-sidebar-plugin-office"

安装后重启 dsh web 进程并浏览器硬刷新（Ctrl+Shift+R）。

运行

• 打开侧边栏 → 在文件资源管理器中打开任意 .docx / .xlsx / .pptx，预览器自动命中。
• Side card 设置页 →「文件预览」清单中可见 docx / xlsx / pptx 三张卡片，可单独启用/禁用。

检查