PlainApp
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 }
}