# 插件与多维表格工作台

## 使用

在「设置 → 插件」下载 Word、Excel、PowerPoint、PDF、CAD、EPUB、Notability、Goodnotes 阅读或多维表格工作台插件。新安装默认关闭，勾选「启用」才正式加载，启用即时生效。缺少插件的文件页也可跳转设置安装。更新保留开关状态，新包完整落盘后删除旧版；下载失败保留原版。卸载只删除插件程序，文档和工作台配置保留。首次发布前，在线下载会明确提示官方插件尚未发布。

查看格式：Word `.doc/.docx`、Excel `.xls/.xlsx`、PowerPoint `.ppt/.pptx`、PDF `.pdf`。查看器不编辑或保存原文件，提供文字选择、复制和对应的浏览操作。Excel 使用文件中保存的公式结果，不计算公式、不执行宏；合并单元格、工作表切换、键盘及触屏连续选区可用，复杂样式、图表不保证与 Excel 完全一致。Word/PPT 的复杂排版、特殊图形与旧版二进制格式存在渲染边界，需要使用实际文件核对；不承诺与 Office 像素一致。加密 Office 文档不提供解密界面，PDF 扫描件不提供 OCR。

在多维表格的视图「＋」中创建工作台。插件缺失时提供就地安装入口；已有工作台配置仍保存在 `.bitable/.table` 文件的视图中。个人工作台、项目驾驶舱、知识与灵感和空白模板不向真实表格插入样例记录。

「自定义」中添加、复制、删除和排序组件，调整宽高、字段绑定、筛选、排序和统计；保存布局后提交到当前文档，沿用软件现有保存策略，取消丢弃草稿。支持指标、任务、日历、笔记、统计图、数据表、Markdown 文本、快捷入口和完成进度。按住组件左上角拖手拖动排序（指针事件实现，宿主开启文件拖入时原生拖放不可用），触屏同样可拖，聚焦拖手后方向键可微调，组件设置中也可上移、下移；窄屏指标并列、内容单列展示。组件设置只列出该组件用到的项，字段下附一句用途说明，下拉只给出类型匹配的字段（日期、数值、状态）；宽屏时设置面板停靠右侧，边改边预览。统计图按多选字段的每个选项分组；选项、勾选框字段可直接从下拉中选筛选值。缺少必要绑定（分组、数值、完成状态等）时组件内明确提示，不显示误导性的结果。

工作台支持当前表格和最多 8 个外部表格文件。每个组件可独立选择数据源。引用保存为相对路径，整组文件应一起同步；跨盘文件须移至同一存储位置，移动或改名导致失联后可重新绑定。外部文件每个上限 10 MB、十万条记录；组件最多 64 个。当前表格更新即时反映，外部来源可通过「刷新数据」重新读取。当前表格任务可直接切换状态；外部记录通过原编辑器打开修改，避免覆盖其它文件的未保存内容。

插件界面继承应用主题、字体和字号。Office/PDF 原页面保留文档原色和字体，缺失字体回退到应用字体；Word 可切换阅读排版。单个预览文件上限 50 MB，OpenXML 解压总量上限 64 MB、内部项目上限 5000，PDF 上限 2000 页。图片 PDF 的文字选择取决于原文件是否带文字层。

添加组件时可先选择数据源，再选「今日待办、逾期提醒、未来三天、状态分布、目标进度、快捷笔记、日程月历、常用入口、今日专注」预设。预设仍是可自由修改的基础组件，不写入样例行。缺少日期字段时明确提示绑定，不把全部记录误算为今日或逾期。

CAD 支持 `.dwg/.dxf` 二维图纸，只读平移、缩放与适合窗口。CAD 1.2.1 移除独立文字列表、复制文字和开源代码入口，图中的文字标注仍正常显示。DWG 的 LibreDWG WASM 和 DXF 文本解析均在独立 Worker 中运行，资源随包离线提供，不上传图纸。CAD 1.2.0 将插件文件预算提高至 50 MB，与桌面及网页宿主保持一致；场景预算为 100 万源实体、200 万展开实体、400 万几何数据项、1200 万估算绘制点、2 万个实际引用块和 32 层块嵌套；源实体不再重复计算模型空间定义、块名别名或未引用块。解析后在线程内剔除无用块及非显示缓存，降低跨线程和块变换的内存开销，图纸源文件不变。文件字节数不能反映块展开和线型细分后的复杂度，达到文件预算以内也可能触发场景预算。

超过 5 万展开实体或 20 万几何数据项的图纸需要 WebGL 硬件加速，采用 GPU 分批、视口裁剪、48 段曲线细分上限和最多 800 个可见文字标签；小文字放大后显示。小图纸仍可回退到 Canvas2D。解析限时 120 秒，加载时显示当前阶段；首次 GPU 场景构建仍可能短暂占用主线程，不保证超复杂图纸即时打开。保存视口为空时尝试补偿目标点偏移，仍无内容则回退完整范围，避免打开后只看到空白。

复杂图纸、三维实体、缺失 SHX 字体或外部参照需在专业 CAD 软件中核对。关闭文档释放线程、Blob URL 和图形上下文；更新插件后也可重启应用以释放旧模块的浏览器缓存。

EPUB 阅读支持 `.epub` 电子书（EPUB 2/3 可重排版式），提供目录跳转、章节翻页、字号调节（Ctrl/⌘ + 滚轮）和本机阅读进度记忆。解析基于 JSZip，正文经 DOMPurify 净化后在独立 Shadow DOM 中渲染：不执行书内脚本，不加载远程图片、样式或字体，外部链接点击只复制地址；书内 CSS 保留排版，文字与背景色跟随应用主题。正文或图片受 DRM 加密的书籍会明确拒绝，字体混淆可正常阅读；固定版式（预排版）电子书按单页流式显示，效果可能与原书不同。解压总量上限 256 MB、内部文件上限 1 万个、单章上限 8 MB。

Notability 与 Goodnotes 分别提供独立插件，支持 `.note` 与 `.goodnotes` 的**只读兼容解析**，复用桌面、网页、Android / iOS 的插件宿主。可以查看可识别的手写笔迹、翻页、缩放、适合宽度及触屏双指缩放；Notability 的连续笔迹保持长纸显示。不会编辑或保存原生格式，不实现两款应用的账号同步。

两种格式均为私有结构，当前并非完整保真阅读：Notability 按固定笔宽显示，正文文字、纸张、图片和 PDF 背景未合成；Goodnotes 的文字、图形、擦除、图片和 PDF 背景可能缺失，页面日志不识别时会明确提示页序和纸张大小的回退。界面始终显示这些边界，无法解析的记录另行提示。文件中的预览通常仅有首页，明确标记为“内嵌预览（通常仅首页）”；PDF / 图片作为独立附件查看，不冒充带批注的完整页面。需要准确完整的内容时，请在原应用导出 PDF，再使用 PDF 查看插件。不支持 `.ntb`、加密/未知版本或其他应用的同名 `.note`。

单个原生笔记沿用宿主 50 MB 文件限制，解压总量最多 64 MB、内部文件最多 10000 个；笔迹最多 100 万点，Goodnotes 最多 2000 页。资源在本地内存解析，不上传笔记，不执行附件脚本；切换附件和关闭页面会释放 Blob URL、PDF 线程和观察器。两个插件的 PDF 查看资源独立内嵌，不要求另外安装 PDF 插件。首次使用仍需在“设置 → 插件”分别下载并启用；离线可继续使用已安装版本。

格式依据及兼容边界参考 [Notability 格式分析](https://cable729.github.io/inkterop/docs/formats/notability/) 与 [Goodnotes 格式分析](https://github.com/cable729/inkterop/blob/main/docs/formats/goodnotes.md)。解析器按这些已公开的字段事实实现，不依赖原应用或原生转换工具。真实 Goodnotes 测试样例使用作者明确以 CC0 提供的导出文件，来源见 `plugins/test/fixtures/README.md`。

新版本读取插件目录 `catalog-v2.json`，并忽略本版本不认识的插件；`catalog.json` 只保留最初六个插件，供 0.5.9 及更早版本继续检查更新。

CAD 构建将固定版本的 Embind 动态调用器替换为普通闭包，保持主界面禁止 JavaScript 字符串执行，仅允许 WASM 编译；上游绑定文件哈希变化时构建会明确失败并要求审查。适配原理参见 [Emscripten DYNAMIC_EXECUTION](https://emscripten.org/docs/tools_reference/settings_reference.html#dynamic-execution)。

「字体」区域提供 Maple Mono Normal NF CN（中文推荐）和 JetBrains Mono（西文推荐），共用原有 v1.0.0 增强包，一次下载约 19 MB。已有应用字体直接复用原位置，系统已安装同名字体时可直接使用。字体在应用内登记并按实际引用加载，不安装到操作系统。排版页提供跳转入口；字体区可整包卸载，卸载前把引用这两款字体的排版设置切回系统字体。移除手动导入和启动推荐弹窗。字体资源版本目前随主程序清单维护；查看器与工作台插件可独立更新。

系统字体检测：Windows 使用进程内 GDI；Linux 使用 fc-list 并回退 font-kit；macOS 使用 font-kit 回退。移动端只列保证存在的通用字体族，可下载应用字体。网页支持 Local Font Access 时在用户打开下拉后请求权限，受限浏览器通过字形度量检测常见字体；也可输入名称。浏览器检测不保证获得完整系统字体清单。

## 开发与发布

源码位于本仓库 `plugins/`，不新建仓库。主程序仅包含轻量宿主；渲染库、PDF Worker、中文 CMap 与标准字体随独立插件包下载并在本地使用。Windows 安装发布版在 `%LOCALAPPDATA%/com.crazyfigure.noteboard/` 下并列使用 `plugins/` 和原有 `font-packs/`；免安装版改用 EXE 同目录 `data/NoteBoard/` 的对应子目录。开发版及其他原生端继续使用各自应用数据目录的对应子目录。网页端在服务器数据卷使用同名目录，按部署实例共享。插件列表仅读取轻量元数据，实际打开文档才完整校验、加载；同版本多文档复用模块。安装状态不作为笔记同步数据，工作台布局和数据源文件按原有同步机制同步。

```powershell
pnpm --dir plugins install --frozen-lockfile
pnpm --dir plugins test
pnpm --dir plugins build
```

`plugins/versions.json` 分别管理各插件的三段版本与更新说明。程序版本、插件版本、宿主 API 版本、工作台配置版本分别维护。`.nbplugin` 为含清单、完整许可和自包含 JavaScript 的 JSON 文件，安装前验证官方标识、最低软件版本、API 版本、包摘要和代码摘要。包大小上限 32 MB，完整写入后才切换激活指针；失败保留旧版。

当前仅支持本项目维护的官方插件，插件代码与主程序同级信任，不能视为任意第三方脚本的沙箱。远程目录固定在本仓库 GitHub Release 的 `plugins` 标签中，通过 HTTPS 获取；摘要用于完整性检查，不等同于独立签名。离线后继续使用已安装版本。

人工运行 GitHub Actions「Official plugins」构建并发布。发布先检查已有同版本包，内容不同则失败并要求提高版本号；新包上传后最后更新 `catalog.json`，避免目录指向未上传的资产。插件发布不使用应用的 `v*` 标签，不触发主程序版本更新。GitHub 发布本身须在提交、推送获得用户授权之后执行。

采用的组件及许可随包完整分发：docx-preview（Apache-2.0）、msdoc-viewer / @file-viewer/doc（MIT）、SheetJS CE 0.20.3（Apache-2.0）、Web-PPT（MIT）、PDF.js（Apache-2.0）、JSZip、Marked 与 DOMPurify 各自许可。CAD 采用 @flyfish-dev/cad-viewer（AGPL-3.0-only）与 LibreDWG（GPL-3.0-only），CAD 插件整体遵循 AGPL-3.0-only，完整源码、构建脚本和锁文件随本仓库提供；其上游源码见 https://github.com/flyfish-dev/cad-viewer 与 https://github.com/mlightcad/libredwg-web 。字体遵循 SIL OFL 1.1。未接入商业旧版 PPT 引擎、在线 Office 转码或 AI 服务。

开发预览使用 `?mock=1`，从 `plugins/dist` 加载真实构建包，模拟的仅为安装存储与文件系统。生产构建不包含该下载源。验证记录应分别区分浏览器样例、桌面/网页构建、原生测试和实机安装；浏览器模拟不能替代各系统实机验收。

## 本次验收（2026-10-20）

- Windows NSIS 安装包与网页生产构建通过，所有本次改动的 TS / MJS 文件通过 ESLint，`git diff --check` 通过。
- 前端定向测试 167 项及新增浏览器字体权限测试 2 项通过；Rust 101 项通过；网页服务 12 项、独立插件 3 项通过。跨实例 WebDAV 集成测试 1 项因缺少外部环境跳过。
- 使用 Kimi WebBridge 查看飞书个人工作台参考，并在真实网页生产环境验证旧版 DOC / XLS / PPT、中文 PDF、DWG / DXF、外部表格模块绑定、手动保存和恢复标签；开发预览另验证 DOCX / XLSX / PPTX。检查桌面、390px 移动布局、浅色与深色主题。移动端字体跳转可直接看到两款字体卡片，未出现横向溢出。
- 官方字体归档已实际下载，网页端解压、逐文件 SHA 校验和字体资源读取通过；历史字体目录复用保留。浏览器权限测试确认后台检测不弹权限，只在明确打开字体下拉时允许请求本机字体清单。
- 首屏未引入查看器重依赖。体积门禁仍超限：本次 JS 约 1204 KiB / CSS 165.9 KiB；干净 HEAD 基线约 1203.8 KiB / 166.2 KiB，既定上限为 1200 / 160 KiB，未调高预算。
- 未在 macOS、Linux、Android、iOS 实机安装验收，也未承诺所有复杂 Office / CAD 文件都能保真显示。Windows 此处确认的是安装包构建，原生安装运行仍需验收。
- 源码仅作本地提交，未推送或发布官方插件资源。在线安装目录须在推送另获授权、源代码合并后发布；本地构建包在 `plugins/dist/`，Windows 验收安装包在 `src-tauri/target/release/bundle/nsis/`。