API 參考
圖片編輯器
讀取、儲存及刪除圖片編輯專案,查詢專案摘要清單,並廣播編輯更新。
文件格式
text
PlainApp image editor document
Encoding
SQLite image_editor_projects.state_b64 = standard Base64(Yjs encodeStateAsUpdate(document))
The GraphQL field is stateB64. The SQLite field is state_b64.
This is the complete editable project, not the exported PNG or plain JSON.
The binary codec is Yjs Update V1. The content version is meta.formatVersion = 1.
These are separate version identifiers. Neither is a Pixi serialization.
The current reader rejects missing or unsupported content versions before replacing the active project.
There are no older-format readers, migrations, field aliases, or version fallbacks.
Root shared types
meta: Y.Map<scalar>
layers: Y.Array<Y.Map<field>> — ordered from back to front
images: Y.Map<string> — image-layer ID → embedded PNG data URL
meta
formatVersion: 1
canvasWidth, canvasHeight: positive document pixels
bgColor: CSS color or transparent
imgOffsetX, imgOffsetY: source-image top-left offset in document pixels
imgAlpha: source-image opacity, 0–100
sourceImage: embedded PNG data URL; absent when there is no source image
An untouched field uses the current document's defined initial value:
canvasWidth=1920, canvasHeight=1080, bgColor=transparent,
imgOffsetX=0, imgOffsetY=0, imgAlpha=100.
Starting a blank canvas explicitly sets bgColor=#ffffff.
Every layer
id: stable UUIDv7 string
type: ARROW | RECT | ELLIPSE | HIGHLIGHT | MOSAIC | TEXT | IMAGE | FREEHAND | STICKER
visible: boolean
name: display label
Coordinates and sizes use document pixels, independent of viewport, zoom and pixel density.
rotation uses degrees around the layer center. Positive angles rotate clockwise.
Colors use CSS #RRGGBB or rgba(r,g,b,a); rgba alpha is 0–1.
Persist enum values exactly as listed. SEMIBOLD renders as font weight 600.
ARROW
x1, y1, x2, y2: endpoint coordinates
color: CSS color; lineWidth: document pixels; rotation: degrees
RECT
x, y: top-left; w, h: size; color: CSS color; lineWidth: document pixels
ELLIPSE
cx, cy: center; rx, ry: radii; color: CSS color; lineWidth: document pixels
HIGHLIGHT
x, y: top-left; w, h: size; color: CSS color
MOSAIC
x, y: top-left; w, h: size; blockSize: document pixels
Pixelation operates on the composite below this layer, including earlier mosaic layers.
FREEHAND
points: Y.Array<[x, y]>; color: CSS color; lineWidth: document pixels
TEXT
x, y: center; text: string; maxWidth: wrapping width in document pixels
fontSize: document pixels; fontFamily: CSS font-family list
fontWeight: NORMAL | BOLD | SEMIBOLD; fontStyle: NORMAL | ITALIC
textAlign: LEFT | CENTER | RIGHT; textDecoration: NONE | UNDERLINE
letterSpacing: document pixels; color: CSS color; glow: boolean; rotation: degrees
textStroke: Y.Map { width: document pixels, color: CSS color }
textShadow: Y.Map { offsetX, offsetY, blur: document pixels, color: CSS color }
IMAGE
x, y: center; w, h: size; opacity: 0–1; rotation: degrees
Resource bytes are stored in images[id], not in the layer or a browser handle.
STICKER
x, y: center; w, h: size; text: string; color: CSS color
fontSize: document pixels; fontWeight: NORMAL | BOLD | SEMIBOLD; fontStyle: NORMAL | ITALIC
rotation: degrees
Resources and rendering
Persist sourceImage and images[id] as self-contained data:image/png;base64,... resources.
File and URL imports decode and serialize their pixels before changing the document.
Never persist blob URLs, device paths, resource handles, GPU textures, or Pixi objects.
Selection, hover, tool settings, zoom, pan, pixel density and open popups are temporary UI state.
Thumbnail is a replaceable list preview, not an authoritative document or full-resolution export.
Mobile readers use this same document coordinate system, stacking order and embedded resources.
Mobile font rendering requires an available font from fontFamily; absent fonts may change layout.
Storage and evolution
saveImageEditorProject stores a complete binary state, not an incremental collaboration update.
canvasWidth and canvasHeight outside stateB64 are summary fields derived from the document.
Core stores the binary payload without interpreting its Yjs content; clients own document decoding.
Incremental collaboration updates are Yjs updates for the same document; they are not standalone saves.
Current native saves rebuild typed known fields; they do not preserve arbitrary unknown fields.
Keep Web and native writers on the same content contract. Do not deploy an added field to only one writer.
Any persisted structure change, including added fields, requires a content-version review and tests for every writer.
Changes to field meaning, units or structure require a new content version and updated readers.
Version markers identify incompatibility; they do not make breaking changes compatible.
Released-data upgrades need a separate explicit design; the current development format has no migrations.
Update writers, readers, independent fixtures and this reference together; do not infer missing versions.
Raster exports are PNG, JPEG or WebP; export pixels are separate from the editable document.
實際儲存記錄(SQLite)
state_b64 儲存完整可編輯專案;尺寸和縮圖用於清單展示。以下是包含九種圖層和內嵌 PNG 圖片的合成範例。
json
{
"id": "019b0470-0000-7000-8000-000000000010",
"state_b64": "AX0HACgBBG1ldGENZm9ybWF0VmVyc2lvbgF9ASgBBG1ldGELY2FudmFzV2lkdGgBfYAKKAEEbWV0YQxjYW52YXNIZWlnaHQBfaAHKAEEbWV0YQdiZ0NvbG9yAXcHI2ZmZmZmZigBBG1ldGEKaW1nT2Zmc2V0WAF9BCgBBG1ldGEKaW1nT2Zmc2V0WQF9CCgBBG1ldGEIaW1nQWxwaGEBfZABKAEEbWV0YQtzb3VyY2VJbWFnZQF3dmRhdGE6aW1hZ2UvcG5nO2Jhc2U2NCxpVkJPUncwS0dnb0FBQUFOU1VoRVVnQUFBQUVBQUFBQkNBWUFBQUFmRmNTSkFBQUFEVWxFUVZSNG5HUDR6OER3SHdBRkFBSC9pWms5SFFBQUFBQkpSVTVFcmtKZ2dnPT0HAQZsYXllcnMBKAAHCAJpZAF3JDAxOWIwNDcwLTAwMDAtNzAwMC04MDAwLTAwMDAwMDAwMDAwMSgABwgEdHlwZQF3BUFSUk9XKAAHCAd2aXNpYmxlAXgoAAcIBG5hbWUBdwVhcnJvdygABwgCeDEBfQooAAcIAnkxAX0UKAAHCAJ4MgF9pAEoAAcIAnkyAX2QASgABwgFY29sb3IBdwcjZWY0NDQ0KAAHCAlsaW5lV2lkdGgBfQQoAAcICHJvdGF0aW9uAX0PhwcIASgABxQCaWQBdyQwMTliMDQ3MC0wMDAwLTcwMDAtODAwMC0wMDAwMDAwMDAwMDIoAAcUBHR5cGUBdwRSRUNUKAAHFAd2aXNpYmxlAXgoAAcUBG5hbWUBdwRyZWN0KAAHFAF4AX0UKAAHFAF5AX0eKAAHFAF3AX2QASgABxQBaAF9KCgABxQFY29sb3IBdwcjMjJjNTVlKAAHFAlsaW5lV2lkdGgBfQKHBxQBKAAHHwJpZAF3JDAxOWIwNDcwLTAwMDAtNzAwMC04MDAwLTAwMDAwMDAwMDAwMygABx8EdHlwZQF3B0VMTElQU0UoAAcfB3Zpc2libGUBeCgABx8EbmFtZQF3B2VsbGlwc2UoAAcfAmN4AX2WAigABx8CY3kBfZABKAAHHwJyeAF9KCgABx8CcnkBfRQoAAcfBWNvbG9yAXcHIzNiODJmNigABx8JbGluZVdpZHRoAX0EhwcfASgAByoCaWQBdyQwMTliMDQ3MC0wMDAwLTcwMDAtODAwMC0wMDAwMDAwMDAwMDQoAAcqBHR5cGUBdwlISUdITElHSFQoAAcqB3Zpc2libGUBeCgAByoEbmFtZQF3CWhpZ2hsaWdodCgAByoBeAF9KCgAByoBeQF9uAEoAAcqAXcBfaQBKAAHKgFoAX0oKAAHKgVjb2xvcgF3E3JnYmEoMjU1LDI1NSwwLDAuNCmHByoBKAAHNAJpZAF3JDAxOWIwNDcwLTAwMDAtNzAwMC04MDAwLTAwMDAwMDAwMDAwNSgABzQEdHlwZQF3Bk1PU0FJQygABzQHdmlzaWJsZQF4KAAHNARuYW1lAXcGbW9zYWljKAAHNAF4AX2MAigABzQBeQF9uAEoAAc0AXcBfaQBKAAHNAFoAX0oKAAHNAlibG9ja1NpemUBfQyHBzQBKAAHPgJpZAF3JDAxOWIwNDcwLTAwMDAtNzAwMC04MDAwLTAwMDAwMDAwMDAwNigABz4EdHlwZQF3BFRFWFQoAAc+B3Zpc2libGUBeCgABz4EbmFtZQF3BHRleHQoAAc+AXgBfYgDKAAHPgF5AX2IAygABz4EdGV4dAF3DVBvcnRhYmxlIHRleHQoAAc+CGZvbnRTaXplAX0YKAAHPgVjb2xvcgF3ByMwMDAwMDAoAAc+CmZvbnRGYW1pbHkBdwpzYW5zLXNlcmlmKAAHPgpmb250V2VpZ2h0AXcEQk9MRCgABz4JZm9udFN0eWxlAXcGSVRBTElDKAAHPgl0ZXh0QWxpZ24BdwRMRUZUKAAHPg1sZXR0ZXJTcGFjaW5nAX0CKAAHPg50ZXh0RGVjb3JhdGlvbgF3CVVOREVSTElORScABz4KdGV4dFN0cm9rZQEoAAdOBXdpZHRoAX0CKAAHTgVjb2xvcgF3ByNlZjQ0NDQnAAc+CnRleHRTaGFkb3cBKAAHUQdvZmZzZXRYAX0CKAAHUQdvZmZzZXRZAX0EKAAHUQRibHVyAX0IKAAHUQVjb2xvcgF3D3JnYmEoMCwwLDAsMC43KSgABz4EZ2xvdwF4KAAHPghyb3RhdGlvbgF9CigABz4IbWF4V2lkdGgBfbADhwc+ASgAB1kCaWQBdyQwMTliMDQ3MC0wMDAwLTcwMDAtODAwMC0wMDAwMDAwMDAwMDcoAAdZBHR5cGUBdwVJTUFHRSgAB1kHdmlzaWJsZQF4KAAHWQRuYW1lAXcFaW1hZ2UoAAdZAXgBfZAGKAAHWQF5AX2IAygAB1kBdwF9gAIoAAdZAWgBfaABKAAHWQdvcGFjaXR5AXw/AAAAKAAHWQhyb3RhdGlvbgF9FIcHWQEoAAdkAmlkAXckMDE5YjA0NzAtMDAwMC03MDAwLTgwMDAtMDAwMDAwMDAwMDA4KAAHZAR0eXBlAXcIRlJFRUhBTkQoAAdkB3Zpc2libGUBeCgAB2QEbmFtZQF3CGZyZWVoYW5kJwAHZAZwb2ludHMACAAHaQN1An0KfawEdQJ9FH22BHUCfSh9gAUoAAdkBWNvbG9yAXcHIzhiNWNmNigAB2QJbGluZVdpZHRoAX0IhwdkASgAB28CaWQBdyQwMTliMDQ3MC0wMDAwLTcwMDAtODAwMC0wMDAwMDAwMDAwMDkoAAdvBHR5cGUBdwdTVElDS0VSKAAHbwd2aXNpYmxlAXgoAAdvBG5hbWUBdwdzdGlja2VyKAAHbwF4AX2QBigAB28BeQF9ngUoAAdvAXcBfbgBKAAHbwFoAX2QASgAB28EdGV4dAF3BE5vdGUoAAdvBWNvbG9yAXcHI2ZlZjA4YSgAB28IZm9udFNpemUBfRQoAAdvCmZvbnRXZWlnaHQBdwhTRU1JQk9MRCgAB28JZm9udFN0eWxlAXcGTk9STUFMKAAHbwhyb3RhdGlvbgF9BSgBBmltYWdlcyQwMTliMDQ3MC0wMDAwLTcwMDAtODAwMC0wMDAwMDAwMDAwMDcBd3ZkYXRhOmltYWdlL3BuZztiYXNlNjQsaVZCT1J3MEtHZ29BQUFBTlNVaEVVZ0FBQUFFQUFBQUJDQVlBQUFBZkZjU0pBQUFBRFVsRVFWUjRuR1A0ejhEd0h3QUZBQUgvaVprOUhRQUFBQUJKUlU1RXJrSmdnZz09AA==",
"thumbnail": null,
"canvas_width": 640,
"canvas_height": 480,
"created_at": "2026-11-17T00:00:00Z",
"updated_at": "2026-11-17T00:00:00Z"
}解碼後的完整結構:九種圖層
Base64 解碼後得到 Yjs 二進位資料,套用到 Y.Doc,再讀取 meta.toJSON()、layers.toJSON() 和 images.toJSON(),即可查看以下結構。這是方便檢視的 JSON 展示,並非實際儲存格式。
json
{
"meta": {
"formatVersion": 1,
"canvasWidth": 640,
"canvasHeight": 480,
"bgColor": "#ffffff",
"imgOffsetX": 4,
"imgOffsetY": 8,
"imgAlpha": 80,
"sourceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
},
"layers": [
{
"id": "019b0470-0000-7000-8000-000000000001",
"type": "ARROW",
"visible": true,
"name": "arrow",
"x1": 10,
"y1": 20,
"x2": 100,
"y2": 80,
"color": "#ef4444",
"lineWidth": 4,
"rotation": 15
},
{
"id": "019b0470-0000-7000-8000-000000000002",
"type": "RECT",
"visible": true,
"name": "rect",
"x": 20,
"y": 30,
"w": 80,
"h": 40,
"color": "#22c55e",
"lineWidth": 2
},
{
"id": "019b0470-0000-7000-8000-000000000003",
"type": "ELLIPSE",
"visible": true,
"name": "ellipse",
"cx": 150,
"cy": 80,
"rx": 40,
"ry": 20,
"color": "#3b82f6",
"lineWidth": 4
},
{
"id": "019b0470-0000-7000-8000-000000000004",
"type": "HIGHLIGHT",
"visible": true,
"name": "highlight",
"x": 40,
"y": 120,
"w": 100,
"h": 40,
"color": "rgba(255,255,0,0.4)"
},
{
"id": "019b0470-0000-7000-8000-000000000005",
"type": "MOSAIC",
"visible": true,
"name": "mosaic",
"x": 140,
"y": 120,
"w": 100,
"h": 40,
"blockSize": 12
},
{
"id": "019b0470-0000-7000-8000-000000000006",
"type": "TEXT",
"visible": true,
"name": "text",
"x": 200,
"y": 200,
"text": "Portable text",
"fontSize": 24,
"color": "#000000",
"fontFamily": "sans-serif",
"fontWeight": "BOLD",
"fontStyle": "ITALIC",
"textAlign": "LEFT",
"letterSpacing": 2,
"textDecoration": "UNDERLINE",
"textStroke": {
"width": 2,
"color": "#ef4444"
},
"textShadow": {
"offsetX": 2,
"offsetY": 4,
"blur": 8,
"color": "rgba(0,0,0,0.7)"
},
"glow": true,
"rotation": 10,
"maxWidth": 240
},
{
"id": "019b0470-0000-7000-8000-000000000007",
"type": "IMAGE",
"visible": true,
"name": "image",
"x": 400,
"y": 200,
"w": 128,
"h": 96,
"opacity": 0.5,
"rotation": 20
},
{
"id": "019b0470-0000-7000-8000-000000000008",
"type": "FREEHAND",
"visible": true,
"name": "freehand",
"points": [
[
10,
300
],
[
20,
310
],
[
40,
320
]
],
"color": "#8b5cf6",
"lineWidth": 8
},
{
"id": "019b0470-0000-7000-8000-000000000009",
"type": "STICKER",
"visible": true,
"name": "sticker",
"x": 400,
"y": 350,
"w": 120,
"h": 80,
"text": "Note",
"color": "#fef08a",
"fontSize": 20,
"fontWeight": "SEMIBOLD",
"fontStyle": "NORMAL",
"rotation": 5
}
],
"images": {
"019b0470-0000-7000-8000-000000000007": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
}
}型別定義
graphql
type Mutation {
broadcastImageEditorUpdate(id: ID!, update: String!): Boolean!
deleteImageEditorProject(id: ID!): Boolean!
saveImageEditorProject(id: ID!, input: ImageEditorProjectInput!): ImageEditorProject!
}
type Query {
imageEditorProject(id: ID!): ImageEditorProject
imageEditorProjects: [ImageEditorProjectSummary!]!
}
type ImageEditorProject {
id: ID!
stateB64: String!
thumbnail: String
canvasWidth: Int!
canvasHeight: Int!
createdAt: Instant!
updatedAt: Instant!
}
input ImageEditorProjectInput {
stateB64: String!
thumbnail: String
canvasWidth: Int!
canvasHeight: Int!
}
type ImageEditorProjectSummary {
id: ID!
thumbnail: String
canvasWidth: Int!
canvasHeight: Int!
updatedAt: Instant!
}
scalar Instant操作
mutation
broadcastImageEditorUpdate
向觀察指定圖片專案的用戶端廣播編輯器更新。
graphql
mutation broadcastImageEditorUpdate($id: ID!, $update: String!) {
broadcastImageEditorUpdate(id: $id, update: $update)
}mutation
deleteImageEditorProject
刪除已儲存的圖片編輯器專案。
graphql
mutation deleteImageEditorProject($id: ID!) {
deleteImageEditorProject(id: $id)
}mutation
saveImageEditorProject
儲存圖片編輯器專案,並回傳其儲存狀態。
graphql
mutation saveImageEditorProject($id: ID!, $input: ImageEditorProjectInput!) {
saveImageEditorProject(id: $id, input: $input) { id stateB64 thumbnail canvasWidth canvasHeight createdAt updatedAt }
}query
imageEditorProject
讀取已儲存的圖片編輯器專案;不存在時回傳 null。
graphql
query imageEditorProject($id: ID!) {
imageEditorProject(id: $id) { id stateB64 thumbnail canvasWidth canvasHeight createdAt updatedAt }
}query
imageEditorProjects
列出已儲存的圖片編輯器專案摘要。
graphql
query imageEditorProjects {
imageEditorProjects { id thumbnail canvasWidth canvasHeight updatedAt }
}