新增圖像標註：用畫筆、箭頭、圓形標註圖片

學完你能做什麼

• ✅ 在計畫審查或程式碼審查中附加圖像
• ✅ 使用畫筆工具自由繪製標註
• ✅ 使用箭頭工具標註重點區域
• ✅ 使用圓形工具圈選區域
• ✅ 調整標註顏色和筆觸大小
• ✅ 使用快捷鍵快速切換工具和操作

你現在的困境

問題 1：審查 UI 設計稿或流程圖時，文字描述不夠直觀，需要圈出問題區域。

問題 2：想給程式碼審查新增截圖註解，但只能用文字說明「這裡有問題」，無法在圖上直接標記。

問題 3：收到團隊分享的圖片連結，想快速標註回饋，但不想下載到本機用其他工具處理。

Plannotator 能幫你：

• 直接在瀏覽器中標註圖片，無需下載到本機
• 畫筆、箭頭、圓形三種工具，涵蓋所有標註情境
• 五種顏色和五種筆觸大小，靈活調整標註效果
• 快捷鍵操作，提升標註效率

什麼時候用這一招

使用情境：

• 審查 UI 設計稿、流程圖、架構圖時需要標註問題
• 程式碼審查中需要截圖並標註程式碼問題
• 分享帶標註的圖片給團隊成員
• 需要在圖片上圈選重點區域或新增箭頭指引

🎒 開始前的準備

前置條件

本教學假設你已經：

• ✅ 完成了 計畫審查基礎 或 程式碼審查基礎
• ✅ 知道如何開啟計畫審查或程式碼審查頁面
• ✅ 了解基本的註解操作

核心思路

圖像標註的三種工具：

工具	圖示	快捷鍵	用途
畫筆	🖊️	1	自由繪製，適合手寫註解、圈選任意形狀
箭頭	➡️	2	標註重點區域或指示方向，適合點對點標註
圓形	⭕	3	圈選區域，適合突顯某個元素

工作流程：

上傳圖片 → 選擇工具 → 調整顏色和大小 → 在圖片上繪製 → 儲存

跟我做

第 1 步：開啟計畫審查或程式碼審查頁面

為什麼 Plannotator 的圖像標註功能整合在計畫審查和程式碼審查中。

操作

1. 啟動計畫審查（Claude Code 觸發或 OpenCode 呼叫 submit_plan）
2. 或執行 /plannotator-review 命令啟動程式碼審查

你應該看到：

• 瀏覽器開啟審查頁面
• 右上角有「Upload」或「附件」按鈕

第 2 步：上傳圖像

為什麼 需要先上傳圖片才能進行標註。

操作

1. 點擊頁面右上角的「Upload」或「附件」按鈕
2. 選擇要標註的圖片（支援 PNG、JPEG、WebP 格式）
3. 圖片上傳後會顯示在註解清單中

你應該看到：

• 圖片縮圖出現在註解區域
• 點擊縮圖可以開啟標註編輯器

圖片來源

你可以透過以下方式取得圖片：

• 截圖並貼上（Ctrl+V / Cmd+V）
• 從本機檔案選擇
• 拖放圖片到頁面

第 3 步：開啟圖像標註編輯器

為什麼 標註編輯器提供繪圖工具和顏色選擇。

操作

1. 點擊已上傳的圖片縮圖
2. 圖像標註編輯器會在彈出視窗中開啟

你應該看到：

• 圖片置中顯示
• 頂部有一排工具列
• 工具列從左到右：工具選擇、筆觸大小、顏色選擇、復原、清除、儲存

第 4 步：使用畫筆工具自由繪製

為什麼 畫筆工具適合手寫註解或圈選任意形狀。

操作

1. 確保選取了畫筆工具（🖊️ 圖示，預設選取）
2. 按下滑鼠左鍵，在圖片上繪製
3. 放開滑鼠完成繪製

你應該看到：

• 滑鼠移動時跟隨的線條軌跡
• 放開滑鼠後，繪製的形狀固定在圖片上

畫筆特點

• 使用 perfect-freehand 函式庫實現平滑的手繪效果
• 支援壓力感應（如果你的裝置支援）
• 筆觸越粗，線條越平滑

第 5 步：使用箭頭工具標註重點

為什麼 箭頭適合點對點標註，明確指出問題位置。

操作

1. 點擊箭頭工具（➡️ 圖示）或按快捷鍵 2
2. 在圖片上點擊確定箭頭起點
3. 拖曳到目標位置，放開滑鼠完成箭頭繪製

你應該看到：

• 從起點到終點的一條直線
• 終點有一個箭頭，指向目標位置

箭頭繪製技巧

• 起點是箭頭尾部，終點是箭頭頭部
• 拖曳過程中可以即時預覽箭頭方向
• 適合標註「這裡有問題」或「需要修改這裡」等情境

第 6 步：使用圓形工具圈選區域

為什麼 圓形適合突顯某個元素，圈選範圍清晰。

操作

1. 點擊圓形工具（⭕ 圖示）或按快捷鍵 3
2. 在圖片上點擊確定圓形的一條邊
3. 拖曳到對邊，放開滑鼠完成圓形繪製

你應該看到：

• 一個圓形，起始點到終止點的連線為直徑
• 圓形中心是兩點連線的中點

圓形繪製原理

圓形工具從邊緣到邊緣繪製：

• 第 1 次點擊：圓的某一條邊
• 拖曳：確定圓的直徑
• 放開：繪製完成圓

原始碼實作（utils.ts:95-124）：

// 中心是起點和終點的中點
const cx = (x1 + x2) / 2;
const cy = (y1 + y2) / 2;

// 半徑是兩點距離的一半
const radius = Math.hypot(x2 - x1, y2 - y1) / 2;

第 7 步：調整標註顏色

為什麼 不同顏色可以區分不同類型的標註（如紅色表示錯誤，綠色表示建議）。

操作

1. 在工具列中點擊顏色圓點
2. 可選顏色：紅色、黃色、綠色、藍色、白色

你應該看到：

• 目前選取的顏色圓點會放大顯示
• 所有新繪製的標註都使用目前顏色

顏色使用建議

• 紅色：錯誤、問題、需要刪除的內容
• 黃色：警告、注意、需要確認的地方
• 綠色：建議、最佳化、改進意見
• 藍色：補充說明、備註
• 白色：適用於深色背景的圖片

第 8 步：調整筆觸大小

為什麼 不同大小的筆觸適合不同的標註情境。

操作

1. 點擊工具列中的 - 或 + 按鈕
2. 或觀察目前筆觸大小預覽（一個圓點）

你應該看到：

• 筆觸大小可選：3、6、10、16、24
• 工具列中間顯示目前筆觸大小的預覽圓點

筆觸大小建議

• 3：精確標註小元素（如按鈕、圖示）
• 6：一般標註（預設值）
• 10：粗線條標註，適合圈選較大區域
• 16：非常粗的標註，適合強調重點
• 24：最大筆觸，適合突顯超大區域

第 9 步：復原和清除

為什麼 標註過程中難免出錯，需要復原或重新開始。

操作

1. 復原上一步：點擊復原圖示（↩️）或按 Cmd+Z / Ctrl+Z
2. 清除所有標註：點擊清除圖示（❌）

你應該看到：

• 復原：最後一次繪製的標註消失
• 清除：所有標註被移除，恢復到原始圖片

清除提示

清除操作不可復原，請謹慎使用。建議先用復原逐步回退。

第 10 步：儲存標註

為什麼 儲存標註後，圖片會被合併到註解中，可以在審查中檢視。

操作

1. 點擊工具列右側的儲存圖示（✅）
2. 或按 Esc 或 Enter 鍵
3. 或點擊彈出視窗外部區域

你應該看到：

• 彈出視窗關閉
• 圖片縮圖更新為標註後的版本
• 圖片已附加到目前註解中

儲存機制

• 如果沒有繪製任何標註，直接儲存原始圖片
• 如果有標註，將原始圖片和標註合併為一張新圖片
• 合併後的圖片以 PNG 格式儲存，保持高品質

檢查點 ✅

驗證你的學習成果：

• [ ] 能成功上傳圖片到審查頁面
• [ ] 能使用畫筆、箭頭、圓形三種工具繪製標註
• [ ] 能調整標註顏色和筆觸大小
• [ ] 能使用快捷鍵（1/2/3、Cmd+Z、Esc）快速操作
• [ ] 能復原錯誤的標註
• [ ] 能儲存標註後的圖片

踩坑提醒

問題 1：箭頭方向反了

現象：箭頭指向了錯誤的方向。

原因：箭頭工具從起點（尾部）到終點（頭部）繪製。

解決：

• 重新繪製，確保起點是箭頭尾部，終點是箭頭頭部
• 如果已繪製，復原後重畫

問題 2：圓形位置不對

現象：圓形沒有圈選到目標區域。

原因：圓形工具從邊緣到邊緣繪製，中心是兩點���點。

解決：

• 第一次點擊在目標區域的邊緣
• 拖曳到對邊，確保目標區域在圓內
• 調整時可以復原重畫

問題 3：筆觸太粗或太細

現象：標註效果不理想。

原因：筆觸大小不適合目前情境。

解決：

• 使用工具列的 - 或 + 按鈕調整筆觸大小
• 小元素用 3-6，大區域用 10-24

問題 4：顏色看不清

現象：在深色背景上使用黑色筆觸，看不清標註。

原因：顏色選擇不當。

解決：

• 深色背景使用白色或黃色
• 淺色背景使用紅色、綠色或藍色

快捷鍵速查

快捷鍵	功能
1	切換到畫筆工具
2	切換到箭頭工具
3	切換到圓形工具
Cmd+Z / Ctrl+Z	復原上一步
Esc / Enter	儲存標註

本課小結

本課你學會了：

1. 上傳圖片：透過上傳按鈕或貼上到審查頁面
2. 三種標註工具：
   • 畫筆（1）：自由繪製，適合手寫註解
   • 箭頭（2）：點對點標註，適合指示重點
   • 圓形（3）：圈選區域，適合突顯
3. 調整標註樣式：5 種顏色、5 種筆觸大小
4. 復原和清除：修正錯誤的標註
5. 儲存標註：將標註合併到圖片中

下一課預告

下一課我們學習 程式碼審查基礎。

你會學到：

• 如何使用 /plannotator-review 命令審查 git diff
• 在 side-by-side 和 unified 檢視間切換
• 點擊行號選擇程式碼範圍
• 新增行級註解（comment/suggestion/concern）
• 切換不同的 diff 類型
• 將回饋傳送給 AI Agent

---

附錄：原始碼參考

點擊展開檢視原始碼位置

更新時間：2026-01-24

功能	檔案路徑	行號
工具類型定義	packages/ui/components/ImageAnnotator/types.ts	1-40
渲染函式	packages/ui/components/ImageAnnotator/utils.ts	1-148
主元件	packages/ui/components/ImageAnnotator/index.tsx	1-233
工具列元件	packages/ui/components/ImageAnnotator/Toolbar.tsx	1-219
Annotation 介面	packages/ui/types.ts	11-33

關鍵類型：

Tool（工具類型）：

export type Tool = 'pen' | 'arrow' | 'circle';

Point（座標點）：

export interface Point {
  x: number;
  y: number;
  pressure?: number;
}

Stroke（筆觸）：

export interface Stroke {
  id: string;
  tool: Tool;
  points: Point[];
  color: string;
  size: number;
}

AnnotatorState（標註器狀態）：

export interface AnnotatorState {
  tool: Tool;
  color: string;
  strokeSize: number;
  strokes: Stroke[];
  currentStroke: Stroke | null;
}

COLORS（顏色陣列）：

export const COLORS = [
  '#ef4444', // red
  '#eab308', // yellow
  '#22c55e', // green
  '#3b82f6', // blue
  '#ffffff', // white
] as const;

STROKE_SIZES（筆觸大小）：

const STROKE_SIZES = [3, 6, 10, 16, 24];

關鍵函式：

renderPenStroke()（渲染畫筆筆觸）：

• 使用 perfect-freehand 函式庫實現平滑手繪效果
• 支援壓力感應（pressure 欄位）

renderArrow()（渲染箭頭）：

• 從起點繪製直線到終點
• 在終點繪製箭頭頭部

renderCircle()（渲染圓形）：

• 計算兩點中點作為圓心
• 計算兩點距離的一半作為半徑

renderStroke()（根據工具類型渲染）：

• 根據 tool 欄位呼叫對應的渲染函式
• 支援縮放（scale 參數）

Annotation.imagePaths（附加圖片欄位）：

export interface Annotation {
  // ...
  imagePaths?: string[]; // Attached images (local paths or URLs)
}

快捷鍵處理（index.tsx:33-59）：

// 1/2/3 to switch tools
if (e.key === '1') setState(s => ({ ...s, tool: 'pen' }));
if (e.key === '2') setState(s => ({ ...s, tool: 'arrow' }));
if (e.key === '3') setState(s => ({ ...s, tool: 'circle' }));

// Cmd+Z to undo
if ((e.metaKey || e.ctrlKey) && e.key === 'z') {
  e.preventDefault();
  handleUndo();
}