# 截圖與視覺檢查

> 結合資料回讀、真實渲染截圖與簡報版面檢查。

- Human documentation: [https://docs.univer.ai/zh-TW/overview/features/shared/visual-inspection](https://docs.univer.ai/zh-TW/overview/features/shared/visual-inspection)

- Agent Markdown: [https://docs.univer.ai/zh-TW/overview/features/shared/visual-inspection.md](https://docs.univer.ai/zh-TW/overview/features/shared/visual-inspection.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.3.0`

- Source: [features/shared/visual-inspection.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/visual-inspection.zh-TW.mdx)

---

視覺檢查將內容模型轉換為可驗證的影像與版面證據。Agent 先檢查資料與公式，再檢查真正渲染出的文字、圖形與頁面；發現問題後透過 Facade 修正，再驗證新的內容狀態。

## 三類證據，回答不同問題

| 證據 | 可確認的內容 |
| --- | --- |
| 結構化讀回 | 原始值、公式與結果、段落和物件屬性。 |
| PNG 截圖 | 可見內容、裁切、圖表、顏色與整體排版。 |
| 版面診斷 | 依渲染幾何回傳規則、物件 ID、邊界與問題位置，方便定向修正。 |

## 準備內容狀態與依賴

截圖與 Layout Lint 接收已物化 UnitData，不負責連線遠端 target 或解讀 changeset。協作內容先 `pull()`，公式修改後等待計算套用，再 `exportUnitData()`。Worktree 必須取對應草稿；應用程式可隨報告儲存目標、revision 與範圍，明確指出審閱狀態。

主 Unit Snapshot 不包含所有依賴。跨 Unit 公式以 `formulaReferenceUnits` 提供 Sheet/Relational Table 來源，嵌入內容以 `embeddedUnits` 提供子 Unit。Render Page 先物化依賴再建立宿主。UUID 圖片可由 `resolveUnitScreenshotImageAssets()` 與應用程式 resolver 補齊；這是 best-effort 解析，仍需核查遺漏資源。

## 從內容到穩定畫面

```mermaid
flowchart LR
A["明確內容狀態<br/>UnitData + 依賴"]
B["Render Runtime<br/>瀏覽器與頁面協定"]
C["Render Page<br/>Univer 原生排版"]
D["等待就緒<br/>計算與畫面穩定"]
E["PNG / 版面事實<br/>Agent 與人類審閱"]
A --> B --> C --> D --> E
```

`univer-render-runtime` 在 Node.js 託管應用程式建置的 Render Page 並啟動瀏覽器，頁面透過產品外掛還原內容，雙方驗證協定版本。同一 Runtime 的操作進入循序佇列，可跨多輪檢查重用，最後由擁有者 `close()`。

就緒條件依產品而異。公式形狀等待結果離開 pending，必要時等待連續影格像素穩定，避免擷取中間動畫；Relational Table 等待字型、計算、活動 table/view 與 DOM/Canvas 版面穩定。離開 pending 仍可能是錯誤結果，必須核對值與狀態。

目前以主 UnitData、公式來源與嵌入內容的序列化結果產生雜湊，作為渲染工作階段 key。同 Unit ID 的資料變更也會產生不同 key，避免只按 ID 重用舊畫面。

## 依產品選擇範圍

| 產品 | 範圍與輸出 |
| --- | --- |
| Sheet | 指定工作表與 A1 範圍，輸出區域 PNG；重要結果宜明確指定範圍。 |
| Doc | 選擇或列舉頁面，輸出逐頁 PNG。 |
| Slide | 以 1 起始頁碼或 page ID 選擇，可額外產生 contact sheet。 |
| Relational Table | 以瀏覽器 DOM + Canvas 擷取開啟後的活動表格／檢視工作台。 |
| Canvases | 全頁內容邊界，或互斥的 region / elementIds；可加 padding 並回傳版面證據。 |

`unit-screenshot` 回傳 bytes、尺寸、頁面／區域身分與建議檔名，由應用程式儲存。Scale 為 0.1–4，可設定 `maxPages` 與單圖 `maxPixels`。放大兩倍約有四倍像素，大量內容宜分區檢查。PDF 不屬於此五產品入口。

## 截圖與版面檢查共用內容狀態

以下對同一 Slide 資料與公式來源截圖並執行 Layout Lint。`renderRuntime` 是既有渲染 Runtime，`slideData` 為準備好的快照。能力本身不寫檔案，頁面建置與關閉方式見 [AI SDK 視覺檢查](https://docs.univer.ai/zh-TW/ai/visual-inspection.md)。

```ts
import { createUnitScreenshot } from '@univer-cli/unit-screenshot'
import { createUnitLayoutLint } from '@univer-cli/unit-layout-lint'

const source = {
  unitType: 'slide' as const,
  unitData: slideData,
  formulaReferenceUnits,
}
const screenshot = createUnitScreenshot({ runtime: renderRuntime })
const lint = createUnitLayoutLint({ runtime: renderRuntime })

const capture = await screenshot.capture({
  ...source,
  target: { kind: 'slide-pages', pages: [1], scale: 2 },
})
const report = await lint.lint({ ...source, pages: [1] })
```

## Slide：以字形墨跡定位問題

Layout Lint 使用瀏覽器產生的版面事實：`declared` 是模型宣告框，文字 `ink` 是字形實際墨跡範圍，結合排版、對齊與旋轉映射至頁面座標。文字框未越界，不代表字形也未越界。

| 目前規則 | 檢查依據 |
| --- | --- |
| `text-off-page` | 實際文字 ink 超出頁面。 |
| `text-escapes-container` | 文字明顯溢出匹配到的較小不透明容器。 |
| `text-overlaps-text` | 兩段實際文字 ink 顯著重疊。 |

報告的 `coverage.pages` 與 `coverage.rules` 標明檢查範圍。Finding 帶 `pageId`、元素 `id`、`text.ink`，以及相關 `overflow`、`container` 或 `other`，穩定 `fingerprint` 可比對修復輪次。目前 finding 都是供搭配截圖複查的 warning；空清單僅代表所選範圍未觸發這些規則。

## Canvases：驗證實際連線路徑

Canvases 截圖額外回傳 `layoutAnalysis`，包含瀏覽器解析的 routes、issues 與 summary，與僅支援 Slide 的 `unit-layout-lint` 為不同入口。模型中的自動連線可能尚未解析，應以 `source: 'rendered'` 檢查最終路徑。

診斷可指出連線穿越元素、交叉、箭頭碰撞或標籤衝突，提供 `connectorIds`、`elementIds` 與 `focusBounds`。Agent 可修正對應物件，再做 region 或 elementIds 局部截圖，最後回到全圖確認，將視覺問題落實為具體 Facade 修改。

## 將檢查證據帶入交付

```mermaid
flowchart LR
A["Facade 修改"]
B["讀回資料與公式"]
C["截圖 + 版面診斷"]
D["依物件 ID 修正"]
E["重查新狀態"]
F["人類審閱 / 交付"]
A --> B --> C --> D --> E --> F
D --> B
```

一併保留結構化結果、範圍與頁面資訊、圖片及診斷。截圖不能證明公式正確，Lint 也不能取代視覺判斷。工具列、焦點與彈出選單等完整互動仍應在 Web 編輯器驗收，跨 Unit 依賴也要確認載入。

在 [Worktree](https://docs.univer.ai/zh-TW/overview/features/shared/worktree.md) 標記 Ready 前完成檢查，讓審閱者對照內容變更與視覺證據。執行機制見[無頭與伺服器計算](https://docs.univer.ai/zh-TW/overview/features/shared/server-calculation.md)，編排見 [Agent 與自動化](https://docs.univer.ai/zh-TW/overview/features/shared/agents.md)。

[返回功能總覽](https://docs.univer.ai/zh-TW/overview/features.md)