
关于
使用 photopea.js 在 Web 应用中嵌入 Photopea。涵盖嵌入、文件 I/O、脚本、导出、图层、文本、滤镜和完整的 Photoshop 兼容 API。
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