Pixerate 向量編輯器
向量文件是一個工作區域（以文件單位表示的 width x height，Y 軸向下），其中包含一個節點樹：path 節點（一個或多個包含貝茲錨點的子路徑，附帶填色、筆畫及筆畫設定）、text 節點（設為點文字、區域文字或沿路徑排列的字串，使用相同的填色和筆畫繪製）、instance 節點（符號的置入副本）以及 group 節點。群組也可以是動態布林運算、動態混合、遮罩群組，或帶有動態效果堆疊。每個指令都是一個 vector.* 指令，透過 run_command / run_commands 執行（請參閱 pixerate-agent-tools 以了解使用 "$0.id" 引用、atomic: true 及錯誤碼的批次處理）。
- 節點 ID 來自
vector.list以及寫入操作的返回值（{ id }、{ ids }）。 - 錨點 為
{ nodeId, subpath, index }：路徑內的子路徑編號，以及該子路徑內的錨點編號，兩者皆從 0 開始。接受anchors的指令預設使用直接選取工具選取的點；接受ids的指令則預設使用選取範圍。 - 繪料 是一個 CSS 顏色（
null表示無），或是一個漸層物件{ type, stops: [{ offset, color, opacity?, midpoint? }], ... }。 - 外觀：路徑可以堆疊多層填色和筆畫（從下到上；所有填色繪製在所有筆畫之下），每層有自己的
paint、opacity、blendMode和visible，而每個筆畫也有自己的寬度、對齊方式、虛線、端點、接合、箭頭和輪廓，或者一個筆刷筆觸（vector.addBrushstroke、vector.setBrushstroke、vector.listBrushes）沿著輪廓以乾筆或濕筆、混色筆刷、塗抹或調和工具、漸層顏料、隨機抖動和紙張紋理繪製。圖層在其堆疊中以index定址，0 為最底層。vector.setStyle的fill/stroke及筆畫設定是最頂層的簡寫；null則清除堆疊。任何節點也可以有blendMode和filters（下/內陰影、外/內發光、圖層模糊、羽化），這些不會改變幾何形狀。 - 遮罩：遮罩群組的第一個（最底部）子節點是其遮罩；其上的子節點只顯示在遮罩輪廓內部（
clip），或是遮罩明亮處（luminance）或不透明處（alpha）。invert會交換顯示和隱藏區域。vector.list會為遮罩群組提供一個mask{ type, invert, maskId, contents, enabled }；隱藏的遮罩（enabled: false）不會遮罩任何東西。 - 文字 具有基礎
font（字體家族、粗細、斜體、大小、字距、行距、基線偏移、底線、刪除線）、可選的範圍覆蓋（在範圍內覆蓋欄位，start/end以 UTF-16 代碼單位計，加上範圍的fill）、paragraph樣式以及一個frame：point（第一個基線的 x, y 座標）、area（文字環繞的方框）或path（文字沿著的路徑）。 - 符號 是與文件一同儲存的可重複使用藝術品（
vector.listSymbols），透過instance節點繪製，其變換矩陣（不同於其他節點）可以進行縮放和傾斜。編輯一個符號（vector.editSymbol…vector.exitSymbolEdit）會改變所有實例。 - 約束（CAD 風格）在錨點、線段和圓形路徑之間維持幾何關係和尺寸；它們在每次編輯後都會被求解，因此後續的移動會保持這些關係。
- 框架 是帶有
frame矩形（vector.listFrames）的群組：它們繪製背景、裁切子節點，並透過其矩形來選取；頂層框架就是工作區域。當框架調整大小時，其子節點會遵循其縮放限制（水平left/right/leftRight/center/scale，垂直top/bottom/topBottom/center/scale），而不是進行縮放。 - 連接器 是具有
connector的開放路徑，其端點會黏附到其他物件的錨點部位（邊的中點或中心）；它們在每次編輯後會重新計算路徑，因此會跟隨它們所連接的物件。自由端則保持原位。 - 對稱群組 會繪製其子節點以及鏡像或旋轉後的副本。透過
vector.addShape/vector.addPath的parentId將美術物件加入；只會儲存和編輯原始物件。 - 座標 以文件單位計算。旋轉後的節點會在自己的空間中儲存幾何形狀：
vector.list回報的bounds是文件空間，其d則是節點本身的空間。
參數詳細資料（漸層欄位、效果參數、寬度輪廓、封套）請參閱 references/commands.md。
工作流程技能
對於這些工作，請同時載入工作流程技能：其中包含方法、步驟間的檢查與陷阱，並使用下列指令。
pixerate-vector-icon-set：在一個網格上的圖示，統一的筆畫和樣式，清晰，以符號和 SVG 形式呈現。pixerate-vector-logo：透過布林運算建立的標記、標誌組合、色彩變體，以及輪廓化的交付檔案。pixerate-vector-illustration：分塊佈局、漸層與堆疊填色、遮罩、混合、陰影。
工作方法
- 讀取。
vector.list提供工作區域大小、每個節點的深度優先資訊（id、類型、名稱、邊界、旋轉、填色、筆畫、d、效果、混合和布林資訊、堆疊、混合模式和濾鏡）以及選取範圍。vector.getAppearance提供一個節點的完整堆疊和濾鏡。 - 按圖層規劃。 在繪製前決定形狀、它們的堆疊順序（從下到上）以及它們的分組。從基本形狀（
vector.addShape）開始並組合它們；僅在基本形狀無法產生的曲線時才撰寫原始d。 - 批次寫入。 將一個建構序列放入單一的
run_commands中，並設定atomic: true和一個label，鏈結 ID（"$0.id"、"$last.ids"），使其成為一個全有或全無的復原步驟。 - 偏好動態，最後再擴展。 在設計時使用
live: true的布林運算、路徑效果、封套、動態圓角和混合；僅在使用者需要純路徑時，才透過vector.expandAppearance、vector.expandBlend或vector.outlineStroke來烘烤。 - 檢查。 再次使用
vector.list：檢查邊界是否如預期、沒有多餘的節點、命名合理。vector.exportSvg提供最終標記；在交付前進行審查，如果可以的話，進行渲染。
最佳實踐
- 任何需要調整大小的物件都使用框架。 在框架內（
vector.addFrame或vector.frameSelection）建立螢幕、卡片、按鈕和橫幅，使用vector.setResizing設定每個子節點的約束（背景和分隔線設為leftRight，圖示固定在角落，標題設為center），然後使用vector.setFrame調整大小，以從一個設計產生其他尺寸。使用vector.exportFrameSvg匯出每個工作區域。 - 重複的物件使用符號。 當相同的藝術品出現多次時（一組圖示、場景中的樹木、項目符號、標誌標記），建立一次並放置實例（
vector.makeSymbol，然後使用x/y或transform參數的vector.placeSymbol），這樣一個隔離的編輯就能更改所有實例。為每個符號取一個清晰的名稱。使用vector.setInstanceOptions的fill/stroke來製作色彩變體，使用hidden來刪除一部分，而不是分離；僅當一個副本必須永久不同時才進行分離。 - 文字。 標籤和標題使用點文字，任何需要自動換行的內容使用區域文字（
width、height），徽章和印章使用路徑文字。檢查每次文字寫入回傳的摘要中的overflow：隱藏的行或字符表示方框或路徑太小。一個設計中保留一到兩個字體家族（vector.listFonts列出可用的字體；缺失的字體會以備用字體顯示，並出現在missingFonts中）。使用vector.setTextStyle設定樣式範圍，而不是將文字分割成單獨的節點，這樣它仍然可以作為一個段落進行編輯。僅對最終藝術品或不得依賴字體的標誌使用「建立外框」功能；如果文字可能變更，請保留一個文字副本。 - 路徑、筆畫、筆刷筆觸、布林運算、漸層、堆疊、遮罩、陰影、連接器、約束和垂直文字： 請先閱讀 references/best-practices.md。
- 先非破壞性。 動態布林運算（使用
live: true的vector.boolean）、路徑效果和封套保持運算元可編輯。破壞性布林運算或 Pathfinder 會取代其輸入；請最後才執行，並且僅在要求平面輸出時執行。 - 分組和命名。 將一個物件的各部分分組（使用
name參數的vector.group），為重要的路徑命名（add 時使用name），並保持樹狀結構淺層。 - SVG 衛生。 匯出時使用
precision2 或 3（預設為 3）；僅對非常小的工作區域使用更高精度。在將 SVG 交給無法讀取 Pixerate 的data-vector-*屬性的工具之前，請先展開效果、混合和可變寬度筆畫；其他檢視器可以看到繪製的外觀，但無法看到動態來源。
指令
讀取
| 指令 | 用途 |
|---|---|
vector.list | 讀取文件：{ width, height, nodes, selection, tool }。每個節點包含 id、類型、名稱、深度、文件空間的 bounds、rotation（順時針度數）、visible、locked、selected，以及路徑的 fill、stroke、strokeWidth 和 d；群組列出 children、blend、liveBoolean、effects、mask。遮罩群組的 bounds 是其遮罩結果。首先呼叫它，並在任何批次之後呼叫。 |
vector.shapeBuilderFaces | 列出給定路徑將平面劃分成的區域：路徑資料、面積、每個區域內的一點，以及填充該區域的路徑 ID。將這些點與 vector.shapeBuilder 一起使用。 |
vector.exportSvg | 以獨立的 SVG 標記形式取得文件（{ svg }）；precision 0 到 8 位小數（預設為 3）。 |
vector.exportPdf | 以 base64 資料 URL 形式取得準備好列印的向量 PDF：一頁，或每個工作區域一頁（pages: "artboards"）。回傳 { pdf, pages, bytes, notes }；檢查 notes（濾鏡、透明度遮罩和未載入字體的文字會被排除）。 |
vector.exportLottie | 將文件（或 ids）以 Lottie JSON 格式匯出給動畫播放器使用：路徑效果保持為動態的 Lottie 修飾器，漸層保持為漸層填色。回傳 { lottie, notes }；閱讀 notes 了解哪些部分被近似處理（濾鏡、網格漸層、未建立外框的文字）。 |
建立與刪除
| 指令 | 用途 |
|---|---|
vector.traceImage | 將 PNG（data URL）轉換成一個群組中的向量路徑：threshold 模式適用於單色藝術品（標誌、掃描圖、剪影；使用 channel: "alpha" 進行去背），color 模式適用於每種顏色一個堆疊路徑（colors 2 到 32）。提高 tolerance 以減少錨點，cornerRoundness 設為 0 以獲得尖銳的多邊形。使用 x、y、width 放置。回傳 { id, paths }；之後檢查 subpaths 數量並簡化或刪除雜點。 |
vector.mosaicImage | 將 PNG 風格化為馬賽克瓷磚（cell px、shape square / circle、gap、colors）：像素藝術、瓷磚壁畫。回傳 { id, paths }，每種顏色一個複合路徑。 |
vector.halftoneImage | 將 PNG 風格化為網點，放在旋轉的螢幕上（cell、angle、墨水 color 或 null 以使用圖片的顏色）：漫畫和普普藝術風格、印刷效果。 |
vector.lowPolyImage | 將 PNG 風格化為低多邊形三角形（cell、jitter、seed、colors）：幾何肖像和背景。 |
vector.hatchImage | 將 PNG 風格化為雕刻線條，在暗處變粗（cell 間距、angle、墨水 color）：鈔票、木刻版畫和線條藝術風格。 |
vector.addPathByDimensions | 以 CAD 使用者輸入的方式繪製路徑：從 start 開始，每一步為 { length, angle }（在頁面上逆時針度數：0 度向右，90 度向上）、{ dx, dy } 或 { x, y }；closed 連接端點。用於精確的技術輪廓（支架、平面圖、給定的長度和角度），而不是手動計算座標。回傳 { id, anchors }。 |
vector.addShape | 在 x、y、width、height（均為必填；對於線條，width 和 height 是終點的偏移量）處新增一個 kind 為 rect、ellipse、polygon（sides，至少 3）、star（points、innerRatio 0 到 1）或 line 的形狀。cornerRadius 和 cornerKind 提供動態圓角；任何樣式欄位和 name 都會套用。未指定的部分使用編輯器的預設樣式。回傳 { id }。 |
vector.addPath | 從 SVG 路徑資料 d（絕對或相對的 M、L、H、V、C、S、Q、T、A、Z；弧線和二次貝茲曲線會轉換為三次貝茲曲線）以文件單位新增一個路徑，帶有 name 和樣式欄位；未設定的樣式來自編輯器預設值。當 d 沒有點時會失敗。回傳 { id }。 |
vector.importSvg | 將 SVG 標記 svg 的形狀新增到文件頂層，或使用 replace: true 取代文件。讀取路徑、基本形狀、群組、變換、線性和徑向漸層、clip-path / mask 引用（作為遮罩群組） <text>（作為點文字：內容、字體、錨點和填色）和 <use>（作為從其所引用的內容製成的符號實例）；跳過圖像和外來濾鏡。 |
vector.importLottie | 新增 Lottie 動畫（物件或文字）的一個 frame 作為可編輯的群組，或取代文件（replace: true）。修飾器變成動態效果。回傳 { ids, notes }。 |
vector.delete | 刪除節點（ids）。 |
vector.rename | 將節點 id 重新命名為 name（其在「圖層」面板中的名稱）。根據建立的內容為其命名；僅在接受要求時重新命名使用者的圖層。回傳 { id, name }。 |
樣式
| 指令 | 用途 |
|---|---|
vector.setStyle | 設定 ids 的 fill、stroke、strokeWidth、strokeLinecap (butt, round, square)、strokeLinejoin (miter, round, bevel)、strokeDasharray、fillRule (nonzero, evenodd)、strokeAlign (center, inside, outside；僅限封閉形狀)、startArrow / endArrow (triangle, arrow, open, circle, square, bar, 或 null)、arrowAlign (extend, tip)、startArrowScale / endArrowScale (筆畫寬度的倍數，預設為 1)、strokeWidthProfile。套用於群組時，會影響其內部的每個路徑。至少傳入一個欄位。 |
vector.setGradient | 編輯 ids 的填色（target 預設值）或筆畫的漸層：type (linear, radial, conic, reflected, diamond)、stops、angle (度數，0 度向上，順時針)、cx / cy / r、明確的 start / end / width / focal、units、spread、interpolation (srgb 預設, linear, oklab)、smoothness、strokeMode、aspect、reverse。省略的欄位保留其值；純色會變成從該色到白色的漸層。回傳 |
…
[已截斷以進行翻譯]