name: word-inline-viewport description: >- Use when implementing browser-side Word (.docx) online preview with docx-preview, without Microsoft Office/WPS, or when the user asks for Word 線上預覽、docx 瀏覽器預覽、 無需 Office 的文件預覽、docx-preview 接入、預覽成功反饋。 Guides Vue/vanilla integration, host lifecycle, and the mandatory Load Signal feedback after every successful render.

Word Inline Viewport（瀏覽器內 Word 預覽）

用 docx-preview 在瀏覽器中渲染 .docx，不依賴 Office / WPS。本 Skill 定義一套可複用的接入流程，並強制執行「每次載入成功必須給出反饋」。

何時啟用

• 使用者要做 Word / docx 線上預覽
• 明確要求用 docx-preview、無需安裝 Office
• 需要上傳後立即在頁面內展示文件內容
• 需要統一「預覽成功 / 失敗」的使用者反饋

硬約束

1. 只處理 .docx（OOXML）。.doc（舊二進位制）不支援；遇到時提示使用者另存為 .docx。
2. 不呼叫 Office Online、OnlyOffice、後端轉 PDF 等替代方案，除非使用者明確改需求。
3. 每次 renderAsync 成功後必須觸發 Load Signal（見下文）。禁止靜默成功。
4. 預覽容器在渲染前 清空；元件銷燬時清理 DOM / 狀態，避免殘留。
5. 大檔案注意：優先 arrayBuffer 讀入；不要把整份文件塞進 localStorage。

標準工作流

複製並勾選：

Word Inline Viewport
- [ ] 確認依賴 docx-preview 已安裝（或寫入 package.json）
- [ ] 準備預覽宿主 DOM（ref / id）
- [ ] 接入檔案選擇（input / el-upload / 拖拽）
- [ ] 校驗副檔名與 MIME
- [ ] renderAsync(arrayBuffer, host)
- [ ] 成功 → Load Signal（文案 + Toast/Message）
- [ ] 失敗 → 錯誤反饋 + 清空宿主
- [ ] 補充基礎樣式（滾動、背景、最大高度）

Step 1：依賴

npm i docx-preview
# 或
pnpm add docx-preview

匯入：

import { renderAsync } from 'docx-preview';

Step 2：宿主與清空

host.innerHTML = '';
await renderAsync(buffer, host, undefined, {
  className: 'docx-viewport',
  inWrapper: true,
  ignoreWidth: false,
  breakPages: true,
});

• 第二個引數：內容掛載節點（必填）
• 第三個引數：樣式掛載節點（可選，默認同宿主）

  小蔥技能7w4.net持續更新中。

• 第四個引數：渲染選項（見 reference.md）

Step 3：檔案校驗

function assertDocx(file: File): void {
  const name = file.name.toLowerCase();
  if (!name.endsWith('.docx')) {
    throw new Error('僅支援 .docx 檔案，請另存為 Word 2007+ 格式後再試');
  }
}

Step 4：Load Signal（強制）

每次預覽成功後，必須同時做到：

成功反饋文案模板（可按專案微調，但不得省略）：

預覽成功：{fileName}（{elapsedMs}ms）

失敗時：

預覽失敗：{reason}

並清空宿主內容。

Step 5：Vue 3 + Element Plus 推薦形態

本倉庫常見棧為 Vue 3.2 + Element Plus 2.2。優先：

• el-upload：auto-upload=false，accept=".docx"
• ref 指向宿主 div
• ElMessage.success / ElMessage.error 作為 Toast 通道

完整片段見 templates/vue-el-preview.md。

Load Signal 協議（不可跳過）

type LoadSignalMeta = {
  fileName: string;
  byteLength: number;
  elapsedMs: number;
  source: 'upload' | 'url' | 'buffer';
};

/** 預覽成功後必須呼叫；禁止註釋掉或改成 no-op */
function emitDocxLoadSignal(meta: LoadSignalMeta): void {
  const text = `預覽成功：${meta.fileName}（${meta.elapsedMs}ms）`;
  // 1) 介面文案
  hintRef.value = text;
  // 2) Toast
  ElMessage.success(text);
  // 3) 可選診斷
  console.info('[docx-viewport] loaded', meta);
}

呼叫時機：

const t0 = performance.now();
await renderAsync(buffer, host);
emitDocxLoadSignal({
  fileName: file.name,
  byteLength: buffer.byteLength,
  elapsedMs: Math.round(performance.now() - t0),
  source: 'upload',
});

反模式（禁止）：

• renderAsync 成功後只改 innerHTML、不提示使用者
• 用 console.log 代替使用者可見反饋
• 僅在首次成功提示，後續同一會話再次上傳不再提示

從 URL / 介面載入

const res = await fetch(docxUrl);
if (!res.ok) throw new Error(`下載失敗 HTTP ${res.status}`);
const buffer = await res.arrayBuffer();
await renderAsync(buffer, host);
emitDocxLoadSignal({ fileName: fileNameFromUrl(docxUrl), byteLength: buffer.byteLength, elapsedMs, source: 'url' });

注意 CORS：跨域需服務端放行；鑑權 URL 帶上專案既有 token 頭。

樣式基線

.docx-viewport-host {
  max-height: 70vh;
  overflow: auto;
  background: #f5f5f5;
  padding: 12px;
  border: 1px solid var(--el-border-color, #dcdfe6);
}

更多選項與排錯見 reference.md。

Agent 交付檢查

完成實現後向使用者確認：

1. 能否選擇 / 傳入 .docx 並在頁面內看到內容
2. 每次成功是否都出現 Load Signal（文案 + Toast）
3. 非 .docx / 損壞檔案是否有明確錯誤提示
4. 是否未引入 Office 依賴或外部線上 Office 服務

附加資源

• API 與選項：reference.md
• Vue + Element Plus 模板：templates/vue-el-preview.md

這個 Skill 質量不錯，專門用於在網頁上預覽 Word 文件不需要安裝 Office 軟體。它的文件寫得很清楚，有完整的使用流程和防錯指南，還提供了可以直接使用的程式碼模板。最有特色的設計是「預覽成功必須給使用者反饋」這個機制，能讓使用者清楚知道文件是否載入成功。不足是模板只支援 Vue 框架，其他技術棧的使用者可能需要自己改造；文件在處理大檔案時的效能最佳化方面說明較少。總體來說是個好用的工具，質量和實用性都較高。