---

name: photopea-embedded-editor description: 使用 photopea.js 在 Web 应用中嵌入 Photopea。涵盖嵌入、文件 I/O、脚本编写、导出、图层、文本、滤镜和完整的 Photoshop 兼容 API。 risk: safe source: community source_repo: yikuansun/PhotopeaAPI source_type: community license: MIT license_source: "https://github.com/yikuansun/PhotopeaAPI/blob/master/LICENSE" date_added: 2026-05-20

Photopea 嵌入式编辑器技能

在网站和应用中使用 photopea.js (yikuansun/PhotopeaAPI)

---

何时使用此技能

在涉及以下所有任务时使用此技能：

• 在网页或 Web 应用中嵌入 Photopea 作为图像编辑器
• 从 JavaScript 代码控制嵌入的 Photopea 实例
• 从宿主页面自动化图像编辑工作流（打开文件、运行脚本、导出结果）
• 使用 Photopea 作为引擎在产品中构建图像编辑功能
• 编写脚本操作文档、图层、文本、选区、滤镜、颜色和路径

不要使用原始 postMessage 连接 — 始终使用 photopea.js 作为封装器。

---

库：photopea.js

photopea.js 是基于 Promise 的 JavaScript 封装器，封装了 Photopea Live Messaging API。 仓库：https://github.com/yikuansun/PhotopeaAPI npm 包：https://www.npmjs.com/package/photopea

安装

CDN（无需构建步骤）

<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>

自托管

<script src="./photopea.min.js"></script>

npm (Webpack / Vite / Rollup)

npm install photopea

import Photopea from "photopea";

---

核心 API：Photopea 类

| 方法 | 描述 | |--------|-------------| | Photopea.createEmbed(container) | 创建并注入 iframe，就绪时 resolve | | new Photopea(window.parent) | 插件模式：封装父窗口 | | pea.runScript(script) | 在 Photopea 内运行 JS 字符串；返回输出数组 | | pea.loadAsset(arrayBuffer) | 加载二进制文件（图像、字体、画笔等） | | pea.openFromURL(url, asSmart) | 以新文档或智能对象图层打开远程 URL | | pea.exportImage(type) | 导出当前文档；返回 Blob（"png" 或 "jpg"） |

所有方法返回 Promise — 始终使用 await 或 .then()。

---

步骤 1 — 嵌入

容器 <div> 在调用 createEmbed 之前必须具有固定的宽度和高度。

<div id="editor" style="width:1000px; height:650px;"></div>
<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
<script>
  Photopea.createEmbed(document.getElementById("editor")).then(async (pea) => {
    // pea is ready
  });
</script>

React：

import { useEffect, useRef } from "react";
import Photopea from "photopea";

export default function Editor() {
  const containerRef = useRef(null);
  const peaRef       = useRef(null);

  useEffect(() => {
    if (!containerRef.current || peaRef.current) return;
    Photopea.createEmbed(containerRef.current).then((pea) => {
      peaRef.current = pea;
    });
  }, []);

  return <div ref={containerRef} style={{ width: "100%", height: "650px" }} />;
}

---

步骤 2 — 打开文件

// Remote URL → new document
await pea.openFromURL("https://example.com/design.psd", false);

// Remote URL → smart object layer inside current document
await pea.openFromURL("https://example.com/overlay.png", true);

// Local file (user input → ArrayBuffer → loadAsset)
document.getElementById("fileInput").addEventListener("change", async (e) => {
  const buf = await e.target.files[0].arrayBuffer();
  await pea.loadAsset(buf);
});

// Base64 data URI via runScript
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);

---

步骤 3 — 运行脚本

runScript 发送 JS 字符串，返回 app.echoToOE(...) 值的数组，最后一个为 "done"。

const result = await pea.runScript(`app.echoToOE("hello");`);
// result → ["hello", "done"]

// Return structured data
const out = await pea.runScript(`
  app.echoToOE(JSON.stringify({
    width:  app.activeDocument.width,
    height: app.activeDocument.height,
    layers: app.activeDocument.layers.length
  }));
`);
const info = JSON.parse(out[0]);

---

步骤 4 — 导出

// PNG Blob (via exportImage)
const blob = await pea.exportImage("png");
document.getElementById("preview").src = URL.createObjectURL(blob);

// JPEG Blob
const blob = await pea.exportImage("jpg");

// WebP / PSD / quality-controlled JPEG via saveToOE
const result = await pea.runScript(`app.activeDocument.saveToOE("webp:0.85");`);
const webpBlob = new Blob([result[0]], { type: "image/webp" });

const result = await pea.runScript(`app.activeDocument.saveToOE("psd:true");`);
const psdBlob  = new Blob([result[0]], { type: "application/octet-stream" });

// Trigger download
async function download(pea, filename = "export.png") {
  const blob = await pea.exportImage("png");
  const a    = Object.assign(document.cr