小編精選 - 技術文章翻譯 · 05月19日

一張 HTML 走天下：CAD-Viewer 首創的「離線 CAD 看圖」

> 不把原始圖紙交給對方，不綁雲端帳號，不裝 AutoCAD —— 一個瀏覽器、一個檔案，照樣能縮放、切圖層、量距離。

寫在前面

傳統分享 CAD 圖紙有兩個選擇：直接發 DWG/DXF 檔案，安全性堪憂；或者轉成 PDF，看起來方便但幾乎不能動手操作。這個「單檔案離線全功能 HTML 檢視器」就是一個折衷又聰明的辦法——既安全又好用，還能維持 CAD 的大部分操作體驗。

核心妙處很簡單：把圖紙資料和瀏覽器執行的工具全都打包在一個 HTML 檔案裡，收件人無需安裝 AutoCAD，也不用上網。你送出去的檔案就像裝了隱形盾牌，資料安全牢靠，不怕外洩。更棒的是，使用者還能平移、縮放、量測，甚至切換圖層，就像在 AutoCAD 裡探險一樣，但不能修改原圖，讓設計者的成果穩如泰山。

這樣一來，分享 CAD 圖紙就像發一張「萬能看圖卡」：誰收到都能看、量測、討論，但絕對不能亂改。對跨團隊、跨公司合作特別友善——安全、省心，還省去軟體安裝的麻煩。

總結一句話：這玩意兒讓 CAD 圖紙既「安全護身」，又「隨手可玩」，讓你在不丟靈魂（和版權）的情況下，輕鬆分享、討論和展示設計成果。

Demo：mlightcad.github.io/cad-viewer/…

背景：交圖紙的「第四種開啟方式」

做專案的人幾乎都經歷過這一幕：圖要給對方看，方式卻總在 洩密、難用、離不開網路 之間三選一。

1.1 三條老路，三個老坑

你怎麼交　對方得到的真實體驗

直接發 DXF / DWG
完整圖紙資料對方能打開、能改、能複製 —— 圖層、塊、屬性、你沒畫出來的東西也可能都在裡面。保密是最大雷區。 往往還得裝一套 CAD。

匯出 PDF
一張「死」圖，發郵件、列印都省心，但 CAD 的靈魂沒了：不好按圖層開關、不好縮到某一類物件、量尺寸也彆扭。適合「看一眼」，不適合「對著圖幹活」。

雲端看圖 / 分享連結
瀏覽器裡的線上預覽圖紙上了別人的伺服器 —— 合規、稽核、客戶保密協議 先過一遍腦。對方還得 一直連網；工地地下室、飛機上、客戶內網隔離？連結還可能過期。

1.2 第四條路：一個 HTML，自帶「迷你 CAD 看圖」

匯出 HTML 是 cad-viewer 非常獨特的招牌能力（業界少見，我們認真做的那種）：

不給原始檔：HTML 裡只有 顯示用幾何快照（頂點、顏色、圖層表），不是 DWG/DXF，對方沒法還原成可編輯原始檔，外洩面小一大截。
不像 PDF 那麼「呆」：離線就能 範圍縮放、拖曳平移、圖層顯示/隱藏、縮放到圖層、兩點測距，中英文介面還能切 —— 真·看圖工作流。
不綁雲端：生成 單個 .html，腳本內聯進去，隨身碟、file://、內網靜態頁都能開，斷網照樣用。
交付極簡：微信、郵件、雲端硬碟丟一個檔案；對方只要有現代瀏覽器，零安裝、零註冊。

一句話定位：在「保密、離線、好用」三角裡找平衡點 —— 不是取代 AutoCAD，而是「把該看的圖，安全、體面地送到對方螢幕上」。

下面開始拆引擎蓋：這套東西在程式碼裡長什麼樣。

設計目標與邊界

2.1 我們想要什麼

目標人話版

離線單檔案：一個 .html 搞定，不依賴後端，也不再把 DWG/DXF 塞進去
體積可控：只帶「畫出來長什麼樣」的批次資料，不帶整庫實體
兩趟班車：匯出在完整 Viewer 裡做；檢視在輕量 Runtime 裡做，各司其職
好維護：型別、編解碼、收集、打包、UI 分檔案；公開 API 統一 AcEx 前綴

2.2 我們刻意不做什麼

不在 HTML 裡復活可編輯的 AcDb 實體
不讓離線頁再去解析 DXF/DWG
不指望它取代完整 Viewer 的 Ribbon、命令列、屬性面板

2.3 兩趟班車：匯出 vs 檢視

班車 A：在 cad-viewer / cad-simple-viewer 裡打開圖，跑 chtml，把目前場景收成快照，再打包進 HTML。
班車 B：對方雙擊 HTML，內聯腳本解壓快照、建立 Three.js 場景，開始縮放圖層量距離。

在 CAD-Viewer 裡匯出

如果你已經用上 @mlightcad/cad-viewer 模組，照這樣做：

3.1 三步走，不用獻祭

先把圖打開 —— DWG/DXF 都可以，等線都畫出來、別還一片黑。
呼叫匯出 —— 任選其一：
- Ribbon / 主選單裡找 Export HTML（原始碼在 MlRibbonCommands.vue、MlMainMenu.vue，迷路別找我）。
- 命令列輸入 chtml（跟 sendStringToExecute('chtml') 是同一回事，鍵盤派友善）。
等轉圈結束 —— 瀏覽器會下載 xxx.html。名稱多半跟圖紙走，副檔名一定是 .html，不會突然變成 .exe（那就離譜了）。

3.2 匯出前默念三句

事項｜人話

圖得真的有打開：匯出的是螢幕上已經畫出來的，不是「我猜你 C 槽有個檔案」。
圖層別裝死：凍結/關掉的圖層，快照裡就當它們不存在。
語言會一起打包：匯出時 Viewer 是什麼語言，離線頁預設就跟什麼；想英文介面就先切英文。
第一次整合要把 viewer-runtime.iife.js 安頓到靜態資源裡，見第 6 章，不然匯出會跟你抱怨找不到 runtime。

用命令列匯出 DXF / DWG

不愛點介面、偏愛黑框和游標閃爍？@mlightcad/cad-html-exporter-cli 奉陪 —— 背後 Playwright 開著 Chromium 偷偷幹和瀏覽器裡一樣的活，你只是看不見而已。

4.1 第一次：先讓瀏覽器安裝一下

pnpm install
pnpm export:html:setup        # 裝 Chromium，只要一次，別跳過

4.2 根目錄三條咒語（試用首選）

咒語｜用途

pnpm export:html：build CLI + 用範例 minimal-line.dxf 輸出 tmp/minimal-line.html
pnpm export:html:run -- <輸入> -o <輸出>：已 build 過？直接對你自己的圖下手
pnpm export:html:setup：上面那條裝瀏覽器，忘了就再來

摸魚試用：

pnpm export:html
# 瀏覽器打開 tmp/minimal-line.html，跟同事吹「看，一條線也能離線」

對自己的圖動刀：

pnpm export:html:run -- D:\drawings\plan.dwg -o D:\out\plan.html
pnpm export:html:run -- drawing.dxf -o drawing.html --locale zh --title "一層平面圖"

4.3 在套件目錄裡念咒

pnpm --filter @mlightcad/cad-html-exporter-cli build
pnpm exec cad-html-exporter path/to/file.dxf -o out/viewer.html

4.4 參數表（背不下來就翻）

參數｜說明

<input>：必填，.dxf 或 .dwg，別的副檔名會被拒絕
-o, --output：輸出路徑；不寫就「同名換 .html」，懶人友善
--locale：en / zh 等，嵌進離線頁
--title：視窗標題 / 中繼資料，顯得專業

4.5 命令列碎碎念

Node ≥ 20；第一次要連網（Chromium + 字型 CDN，和範例 Viewer 同款）。
export:html 會順手 build；只跑 export:html:run 的話，記得先 build 過至少一次。
大圖匯出慢是正常的 —— 別狂按 Ctrl+C，Chromium 也會委屈。

更囉嗦的見 packages/cad-html-exporter-cli/README.md。

打開並使用匯出的 HTML

5.1 怎麼開

姿勢｜做法

本機土豪：雙擊，或拖進 Chrome / Edge / Firefox
伺服器土豪：丟靜態網站，給一個 URL

file:// 也行；瀏覽器偶爾會囉嗦幾句安全提示，一般無視即可。不必裝 CAD、不必裝 Node、不必旁邊再蹲一個 viewer-runtime.iife.js —— 都焊在 HTML 裡了。

5.2 左邊那一排按鈕

按鈕｜用途

範圍縮放：一眼看全圖，省得滾輪搓出火星
測距：點兩下出距離；再點或換模式收工
圖層抽屜：拉開，勾選人生
語言中英切換：localStorage 幫你記

5.3 圖層面板

勾選 = 顯示/隱藏；「全顯 / 全隱」拯救圖層太多的絕望。
縮放到圖層：只盯這一層；層裡沒東西？按鈕會變灰，不騙你點。
手機窄螢幕時抽屜會自動靠邊，盡量不擋你的圖（舊 HTML 擋螢幕？重新匯出一版）。

5.4 測量

數字會跟著匯出時的圖紙單位走。小數位怪怪的？回去在 匯出前 把原圖打開看清楚 —— 別怪 HTML，它只是個誠實的顯示器。匯出為 HTML 後的頁面中的測量功能還在進一步完善中，目前只支援距離測量。

集成到自己的應用

要把「匯出 HTML」塞進自家產品前端的同學，坐穩了。

6.1 你需要的

依賴：@mlightcad/cad-simple-viewer（裡頭已經勾著 @mlightcad/cad-html-exporter）。
使用者命令：chtml（AcApExportHtmlCmd → AcApHtmlConvertor，名字拗口但好用）。

6.2 別忘了 Viewer Runtime（不然匯出會哭）

匯出時會去 fetch viewer-runtime.iife.js 全文，再焊進 HTML。預設找：

./viewer-runtime.iife.js

MlCadViewer / AcApDocManager.createInstance 可改：

htmlViewerRuntimeUrl?: string | URL  // 例如 './assets/viewer-runtime.iife.js'

整合 checklist（打勾再上線，省得半夜被叫起來）：

pnpm --filter @mlightcad/cad-html-exporter build
把 packages/cad-html-exporter/dist/viewer-runtime.iife.js 複製到靜態目錄，路徑和 htmlViewerRuntimeUrl 對得上。
開發/發布時這個 URL 真的能存取（Vite 複製外掛是你的好朋友）。
改了 exporter 或 Runtime？舊 HTML 不會自己進化，請讓使用者重新匯出。

抄作業：cad-simple-viewer-example / cad-viewer-example 的 vite.config.ts 裡 vite-plugin-static-copy。

6.3 已有快照只想打包（大佬玩法）

手上已經有 AcExSnapshotV1？AcApHtmlConvertor.packSnapshot() 或直接呼叫 packHtml(snapshot, { viewerRuntime })，跳過場景收集，直接裝箱。

常見問題

你看到的怪樣子八成是

找不到 runtime：沒 build 或路徑跑掉了。build exporter；確認 htmlViewerRuntimeUrl
工具列只剩一行英文、圖示蒸發：舊 HTML 或 i18n 把按鈕文案「一鍋端」了。重新匯出；目前版本已用 data-i18n-text 保命
打開白屏：快照壞了或 Runtime 沒焊牢。F12 看主控台；HTML 裡應有兩坨大 <script>
file:// 一直唸安全：瀏覽器的職業病，通常可繼續；確認是完整單檔案
CLI 說 Chromium 沒裝：沒裝 Playwright 瀏覽器。pnpm export:html:setup
CLI「Failed to open」：壞檔案、副檔名不對、worker 沒 build。認準 .dxf / .dwg；先 build CLI
手機圖層擋螢幕：上古 CSS。重新匯出，時代不同了
測量小數位離譜：原圖單位 / 精度問題。匯出前在 Viewer 裡把圖看明白

原理與實作（開發者一章）

日常用法上面夠了；下面給要拆引擎的人。一章講完，不拆成九堂微課。

8.1 背景：交圖的「第四條路」

老辦法槽點

直接發 DWG/DXF：洩密像開閘，對方還得裝 CAD
PDF：好看難用，圖層？測量？下次一定
雲端連結：要網路、要帳號、要看合規警告

HTML 匯出：單檔案、不帶原始格式、能切層能測距 —— 在「保密、離線、好用」三角裡找個能坐的位子。不是 AutoCAD 殺手，是「體面地把圖送到對方螢幕上」。

9.2 設計邊界

做：

離線單檔案
只帶顯示幾何
匯出 / 檢視兩班車
AcEx 前綴統一

不做：

HTML 裡改實體
離線再解析 DXF/DWG
取代完整 Viewer

9.3 套件分工

套件｜用途

cad-html-exporter：快照、壓縮、抠幾何、packHtml、外殼、Runtime
cad-simple-viewer：chtml、Builder、Convertor
cad-viewer：Ribbon、htmlViewerRuntimeUrl
cad-html-exporter-cli：Node + Playwright 批次處理
three-renderer：批次物件型別，供收集器辨識

產物重點：dist/viewer-runtime.iife.js —— 匯出時要 fetch 來內聯的那一坨。

9.4 資料流（應用內）

CLI：Playwright 打開 dist-runner → exportCadToHtml() → 同一套 Builder + packHtml → 寫入磁碟。

9.5 技術要點

快照 AcExSnapshotV1：meta、圖層表、版面 + 批次、目前版面 id。
塞進 HTML：gzip + Base64 躺在 <script id="mlcad-snapshot">；內聯 JS 前把 </script> 轉義，不然 HTML 會提前「劇終」。
收集：DFS 場景樹，揪 AcTrBatchedLine / AcTrBatchedMesh。
Runtime：解碼 → i18n → WebGL → 按層 Group。
i18n 血淚史：別對裝著按鈕的父節點 textContent = …，用 data-i18n-text 那套，不然工具列會變成單行公告欄。