Habilidade do Editor Incorporado Photopea
Usando photopea.js (yikuansun/PhotopeaAPI) em Sites e Aplicativos
Quando Usar Esta Habilidade
Use esta habilidade para todas as tarefas que envolvam:
- Incorporar o Photopea como um editor de imagens dentro de uma página web ou aplicativo web
- Controlar uma instância do Photopea incorporada a partir do seu código JavaScript
- Automatizar fluxos de trabalho de edição de imagens a partir de uma página hospedeira (abrir arquivos, executar scripts, exportar resultados)
- Construir um recurso de edição de imagens em seu produto usando o Photopea como motor
- Escrever scripts para manipular documentos, camadas, texto, seleções, filtros, cores e caminhos
NÃO use postMessage bruto — sempre use photopea.js como invólucro.
Biblioteca: photopea.js
photopea.js é um invólucro JavaScript baseado em Promises para a API de Mensagens ao Vivo do Photopea.
Repositório: https://github.com/yikuansun/PhotopeaAPI
Pacote npm: https://www.npmjs.com/package/photopea
Instalação
CDN (sem etapa de build)
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
Auto-hospedado
<script src="./photopea.min.js"></script>
npm (Webpack / Vite / Rollup)
npm install photopea
import Photopea from "photopea";
API Central: A Classe Photopea
| Método | Descrição |
|---|---|
Photopea.createEmbed(container) | Cria + injeta o iframe, resolve quando pronto |
new Photopea(window.parent) | Modo plugin: envolve a janela pai |
pea.runScript(script) | Executa string JS dentro do Photopea; retorna array de saída |
pea.loadAsset(arrayBuffer) | Carrega arquivo binário (imagem, fonte, pincel, etc.) |
pea.openFromURL(url, asSmart) | Abre URL remota como novo doc ou camada de objeto inteligente |
pea.exportImage(type) | Exporta o documento atual; retorna Blob ("png" ou "jpg") |
Todos os métodos retornam Promises — sempre use await ou .then().
Passo 1 — Incorporar
O <div> contêiner deve ter largura e altura fixas antes de chamar createEmbed.
<div id="editor" style="width:1000px; height:650px;"></div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
<script>
Photopea.createEmbed(document.getElementById("editor")).then(async (pea) => {
// pea está pronto
});
</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" }} />;
}
Passo 2 — Abrindo Arquivos
// URL remota → novo documento
await pea.openFromURL("https://exemplo.com/design.psd", false);
// URL remota → camada de objeto inteligente dentro do documento atual
await pea.openFromURL("https://exemplo.com/sobreposicao.png", true);
// Arquivo local (entrada do usuário → ArrayBuffer → loadAsset)
document.getElementById("inputArquivo").addEventListener("change", async (e) => {
const buf = await e.target.files[0].arrayBuffer();
await pea.loadAsset(buf);
});
// URI de dados Base64 via runScript
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);
Passo 3 — Executando Scripts
runScript envia uma string JS, retorna um array de valores app.echoToOE(...) + "done" por último.
const resultado = await pea.runScript(`app.echoToOE("olá");`);
// resultado → ["olá", "done"]
// Retornar dados estruturados
const saida = await pea.runScript(`
app.echoToOE(JSON.stringify({
largura: app.activeDocument.width,
altura: app.activeDocument.height,
camadas: app.activeDocument.layers.length
}));
`);
const info = JSON.parse(saida[0]);
Passo 4 — Exportando
// Blob PNG (via exportImage)
const blob = await pea.exportImage("png");
document.getElementById("preview").src = URL.createObjectURL(blob);
// Blob JPEG
const blob = await pea.exportImage("jpg");
// WebP / PSD / JPEG com controle de qualidade via saveToOE
const resultado = await pea.runScript(`app.activeDocument.saveToOE("webp:0.85");`);
const webpBlob = new Blob([resultado[0]], { type: "image/webp" });
const resultado = await pea.runScript(`app.activeDocument.saveToOE("psd:true");`);
const psdBlob = new Blob([resultado[0]], { type: "application/octet-stream" });
// Disparar download
async function download(pea, nomeArquivo = "exportacao.png") {
const blob = await pea.exportImage("png");
const a = Object.assign(document.createElement("a"), {
href: URL.createObjectURL(blob),
download: nomeArquivo
});
a.click();
}
Strings de formato de exportação para saveToOE:
| String | Formato |
|---|---|
"png" | PNG sem perdas |
"jpg" | JPEG padrão |
"jpg:0.8" | JPEG qualidade 0.0–1.0 |
"webp:0.7" | WebP qualidade 0.0–1.0 |
"psd" | PSD completo |
"psd:true" | PSD minimizado |
"svg:true" | SVG |
Passo 5 — Carregando Ativos
// Fonte
const buf = await (await fetch("https://exemplo.com/MinhaFonte.otf")).arrayBuffer();
await pea.loadAsset(buf);
// Agora utilizável em textItem.font
// Pincel
await pea.loadAsset(await (await fetch("Natureza.ABR")).arrayBuffer());
// Gradiente
await pea.loadAsset(await (await fetch("Gradientes.GRD")).arrayBuffer());
Passo 6 — Modo Plugin
// Sua página está dentro do iframe da barra lateral do Photopea
const pea = new Photopea(window.parent);
const saida = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
console.log("Largura:", saida[0]);
// Carregar um ativo do seu plugin
const buf = await (await fetch("https://meus-ativos.com/sticker.png")).arrayBuffer();
await pea.loadAsset(buf);
Configuração do plugin:
{
"environment": {
"plugins": [{
"name": "Meu Plugin",
"url": "https://meu-plugin.exemplo.com",
"icon": "===https://meu-plugin.exemplo.com/icone.png"
}]
}
}
Padrões Utilitários
addImageAndWait — inserção robusta de camada assíncrona
async function adicionarImagemEAguardar(pea, imgURI) {
let contagem = "done";
while (contagem === "done")
contagem = (await pea.runScript(`app.echoToOE(app.activeDocument.layers.length)`))[0];
contagem = parseInt(contagem);
const literalURIimagem = JSON.stringify(imgURI);
await pea.runScript(`app.open(${literalURIimagem}, null, true);`);
return new Promise((resolve) => {
const verificar = async () => {
const n = parseInt((await pea.runScript(
`app.echoToOE(app.activeDocument.layers.length)`
))[0]);
n === contagem + 1 ? resolve() : setTimeout(verificar, 50);
};
verificar();
});
}
getDocumentAsImage — retorna elemento <img>
async function obterDocumentoComoImagem(pea) {
const resultado = await pea.runScript(`app.activeDocument.saveToOE('png')`);
return new Promise((resolve) => {
const leitor = new FileReader();
leitor.addEventListener("load", (e) => {
const img = new Image(); img.src = e.target.result; resolve(img);
});
leitor.readAsDataURL(new Blob([resultado[0]], { type: "image/png" }));
});
}
Padrões do Mundo Real
Padrão A — UI Abrir + Exportar
<input type="file" id="inputArquivo" accept="image/*,.psd">
<button id="botaoExportar">Exportar PNG</button>
<div id="editor" style="width:100%;height:600px;"></div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
<script>
let pea;
Photopea.createEmbed(document.getElementById("editor")).then(p => pea = p);
document.getElementById("inputArquivo").addEventListener("change", async e => {
await pea.loadAsset(await e.target.files[0].arrayBuffer());
});
document.getElementById("botaoExportar").addEventListener("click", async () => {
const blob = await pea.exportImage("png");
const a = Object.assign(document.createElement("a"), {
href: URL.createObjectURL(blob), download: "exportacao.png"
});
a.click();
});
</script>
Padrão B — Modelo + Edição de Texto + Exportar
async function gerarCartao(pea, nome, slogan) {
await pea.openFromURL("https://exemplo.com/cartao.psd", false);
const literalNome = JSON.stringify(nome);
const literalSlogan = JSON.stringify(slogan);
await pea.runScript(`
app.activeDocument.layers.getByName("Nome").textItem.contents = ${literalNome};
app.activeDocument.layers.getByName("Slogan").textItem.contents = ${literalSlogan};
`);
return await pea.exportImage("png");
}
Padrão C — Marca d'Água em Lote
async function marcaDAguaEmLote(pea, urlsImagens, urlMarcaDAgua) {
const resultados = [];
for (const url of urlsImagens) {
await pea.openFromURL(url, false);
await pea.openFromURL(urlMarcaDAgua, true);
await pea.runScript(`
var doc = app.activeDocument, wm = doc.activeLayer;
wm.translate(doc.width - wm.bounds[2] - 20, doc.height - wm.bounds[3] - 20);
wm.opacity = 70;
`);
resultados.push(await pea.exportImage("png"));
await pea.runScript(`app.activeDocument.close(SaveOptions.DONOTSAVECHANGES);`);
}
return resultados;
}
REFERÊNCIA COMPLETA DA API DE SCRIPTS
Todo código nesta seção é executado dentro de strings
pea.runScript("..."). O Photopea implementa a interface de script JavaScript do Adobe Photoshop CC 2015. Qualquer script do Photoshop que tenha como alvo essa versão deve funcionar no Photopea.
app — Objeto Aplicativo
Propriedades
| Propriedade | Tipo | L/E | Descrição |
|---|---|---|---|
app.activeDocument | Document | L/E | O documento atualmente ativo |
app.documents | Documents | L | Coleção de todos os documentos abertos |
app.documents.length | number | L | Contagem de documentos abertos |
app.documents[i] | Document | L | Acesso por índice baseado em zero |
app.foregroundColor | SolidColor | L/E | Cor de primeiro plano atual |
app.backgroundColor | SolidColor | L/E | Cor de fundo atual |
app.preferences.rulerUnits | Units | L/E | Units.PIXELS, Units.CM, Units.INCHES, Units.MM, Units.PICAS, Units.POINTS, Units.PERCENT |
app.preferences.typeUnits | TypeUnits | L/E | TypeUnits.PIXELS, Units.MM, Units.POINTS |
app.displayDialogs | DialogModes | L/E | DialogModes.NO, DialogModes.ALL, DialogModes.ERROR |
Métodos
| Método | Descrição |
|---|---|
app.open(url) | Abrir URL como novo documento |
app.open(url, null, true) | Abrir URL como camada de objeto inteligente no documento ativo |
app.echoToOE(string) | Extensão Photopea — envia string para a página hospedeira (capturada por runScript) |
app.showWindow("magiccut") | Extensão Photopea — abrir painel Magic Cut |
app.showWindow("vbitmap") | Extensão Photopea — abrir painel Vetorizar Bitmap |
app.UI.zoomIn() | Ampliar zoom |
app.UI.zoomOut() | Reduzir zoom |
app.UI.fitTheArea() | Ajustar tela à janela de visualização |
app.UI.pixelToPixel() | Zoom 100% |
app.UI.switchFullscreen() | Alternar tela cheia |
app.UI.scroll(dx, dy) | Rolar por delta |
app.UI.scrollTo(x, y) | Rolar para posição absoluta |
Importante: Sempre defina as unidades de régua para pixels no início de qualquer script que use medidas em pixels:
var unidadesSalvas = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
// ... seu código ...
app.preferences.rulerUnits = unidadesSalvas;
Document — Objeto Documento
Acesse via app.activeDocument ou app.documents[i].
Propriedades
| Propriedade | Tipo | L/E | Descrição |
|---|---|---|---|
width | number | L | Largura do documento nas unidades de régua atuais |
height | number | L | Altura do documento nas unidades de régua atuais |
resolution | number | L | DPI (pixels por polegada) |
name | string | L/E | Extensão Photopea — rótulo de exibição (sem etapa de histórico) |
source | string | L/E | Extensão Photopea — URL de origem do arquivo ou "local,X,NOME" |
mode | DocumentMode | L | DocumentMode.RGB, GRAYSCALE, CMYK, LAB, BITMAP, INDEXEDCOLOR, MULTICHANNEL |
bitsPerChannel | BitsPerChannelType | L | BitsPerChannelType.EIGHT, SIXTEEN, THIRTYTWO |
colorProfileName | string | L | Nome do perfil de cores incorporado |
activeLayer | Layer/ArtLayer/LayerSet | L/E | Definir para ativar uma camada |
currentLayer | ArtLayer | L/E | Alias para activeLayer |
layers | Layers | L | Todas as camadas de nível superior (arte + grupo) |
artLayers | ArtLayers | L | Apenas camadas de arte de nível superior |
layerSets | LayerSets | L | Apenas camadas de grupo de nível superior |
selection | Selection | L | A seleção atual |
channels | Channels | L | Todos os canais |
historyStates | HistoryStates | L | Histórico de desfazer |
activeHistoryState | HistoryState | L/E | Posição atual no histórico |
layerComps | LayerComps | L | Coleção de composições de camada |
guides | Guides | L | Coleção de guias |
pathItems | PathItems | L | Caminhos vetoriais |
id | number | L | ID único do documento |
saved | boolean | L | Se o documento tem alterações não salvas |
quickMaskMode | boolean | L | Se está no modo Máscara Rápida |
backgroundLayer | ArtLayer | L | A camada de fundo |
pixelAspectRatio | number | L | Proporção de aspecto de pixel personalizada (0.1–10.0) |
histogram | array | L | Array de histograma de 256 elementos |
Métodos
| Método | Assinatura | Descrição |
|---|---|---|
resizeImage | (w, h, res, resampleMethod) | Redimensionar pixels da imagem. Método de reamostragem: BICUBIC, BILINEAR, NEARESTNEIGHBOR, NONE, BICUBICSHARPER, BICUBICSMOOTHER |
resizeCanvas | (w, h, anchor) | Redimensionar tela sem escalonar. Posição de ancoragem: TOPLEFT, TOPCENTER, TOPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER, BOTTOMRIGHT |
rotateCanvas | (degrees) | Girar tela inteira. Positivo = sentido horário |
flipCanvas | (direction) | Direction.HORIZONTAL ou Direction.VERTICAL |
crop | ([x1,y1,x2,y2], angle, w, h) | Cortar tela. Ângulo e dimensões são opcionais |
trim | (trimType, top, left, bottom, right) | Aparar ... |