Skill de Editor Incrustado de Photopea
Usando photopea.js (yikuansun/PhotopeaAPI) en Sitios Web y Aplicaciones
Cuándo Usar Este Skill
Usa este skill para cada tarea que implique:
- Incrustar Photopea como editor de imágenes dentro de una página web o aplicación web
- Controlar una instancia incrustada de Photopea desde tu código JavaScript
- Automatizar flujos de trabajo de edición de imágenes desde una página anfitriona (abrir archivos, ejecutar scripts, exportar resultados)
- Construir una funcionalidad de edición de imágenes en tu producto usando Photopea como motor
- Escribir scripts para manipular documentos, capas, texto, selecciones, filtros, colores y trazados
NO uses postMessage directamente — usa siempre photopea.js como envoltorio.
Biblioteca: photopea.js
photopea.js es un envoltorio JavaScript basado en Promesas alrededor de la API Live Messaging de Photopea.
Repositorio: https://github.com/yikuansun/PhotopeaAPI
Paquete npm: https://www.npmjs.com/package/photopea
Instalación
CDN (sin paso de compilación)
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
Autoalojado
<script src="./photopea.min.js"></script>
npm (Webpack / Vite / Rollup)
npm install photopea
import Photopea from "photopea";
API Principal: La Clase Photopea
| Método | Descripción |
|---|---|
Photopea.createEmbed(container) | Crea e inyecta el iframe, se resuelve cuando está listo |
new Photopea(window.parent) | Modo plugin: envuelve la ventana padre |
pea.runScript(script) | Ejecuta una cadena JS dentro de Photopea; devuelve un array de salida |
pea.loadAsset(arrayBuffer) | Carga un archivo binario (imagen, fuente, pincel, etc.) |
pea.openFromURL(url, asSmart) | Abre una URL remota como nuevo documento o capa de objeto inteligente |
pea.exportImage(type) | Exporta el documento actual; devuelve un Blob ("png" o "jpg") |
Todos los métodos devuelven Promesas — usa siempre await o .then().
Paso 1 — Incrustar
El <div> contenedor debe tener un ancho y alto fijos antes de llamar a 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á listo
});
</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" }} />;
}
Paso 2 — Abrir Archivos
// URL remota → nuevo documento
await pea.openFromURL("https://example.com/design.psd", false);
// URL remota → capa de objeto inteligente dentro del documento actual
await pea.openFromURL("https://example.com/overlay.png", true);
// Archivo local (entrada de usuario → ArrayBuffer → loadAsset)
document.getElementById("fileInput").addEventListener("change", async (e) => {
const buf = await e.target.files[0].arrayBuffer();
await pea.loadAsset(buf);
});
// URI de datos Base64 mediante runScript
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);
Paso 3 — Ejecutar Scripts
runScript envía una cadena JS, devuelve un array de valores app.echoToOE(...) + "done" al final.
const result = await pea.runScript(`app.echoToOE("hola");`);
// result → ["hola", "done"]
// Devolver datos estructurados
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]);
Paso 4 — Exportar
// Blob PNG (mediante 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 con calidad controlada mediante 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" });
// Iniciar descarga
async function download(pea, filename = "export.png") {
const blob = await pea.exportImage("png");
const a = Object.assign(document.createElement("a"), {
href: URL.createObjectURL(blob),
download: filename
});
a.click();
}
Cadenas de formato de exportación para saveToOE:
| Cadena | Formato |
|---|---|
"png" | PNG sin pérdida |
"jpg" | JPEG por defecto |
"jpg:0.8" | JPEG calidad 0.0–1.0 |
"webp:0.7" | WebP calidad 0.0–1.0 |
"psd" | PSD completo |
"psd:true" | PSD minimizado |
"svg:true" | SVG |
Paso 5 — Cargar Recursos
// Fuente
const buf = await (await fetch("https://example.com/MyFont.otf")).arrayBuffer();
await pea.loadAsset(buf);
// Ahora usable en textItem.font
// Pincel
await pea.loadAsset(await (await fetch("Nature.ABR")).arrayBuffer());
// Degradado
await pea.loadAsset(await (await fetch("Gradients.GRD")).arrayBuffer());
Paso 6 — Modo Plugin
// Tu página está dentro del iframe de la barra lateral de Photopea
const pea = new Photopea(window.parent);
const out = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
console.log("Ancho:", out[0]);
// Cargar un recurso desde tu plugin
const buf = await (await fetch("https://my-assets.com/sticker.png")).arrayBuffer();
await pea.loadAsset(buf);
Configuración del plugin:
{
"environment": {
"plugins": [{
"name": "Mi Plugin",
"url": "https://my-plugin.example.com",
"icon": "===https://my-plugin.example.com/icon.png"
}]
}
}
Patrones de Utilidad
addImageAndWait — inserción robusta de capas asíncronas
async function addImageAndWait(pea, imgURI) {
let count = "done";
while (count === "done")
count = (await pea.runScript(`app.echoToOE(app.activeDocument.layers.length)`))[0];
count = parseInt(count);
const imageUrlLiteral = JSON.stringify(imgURI);
await pea.runScript(`app.open(${imageUrlLiteral}, null, true);`);
return new Promise((resolve) => {
const check = async () => {
const n = parseInt((await pea.runScript(
`app.echoToOE(app.activeDocument.layers.length)`
))[0]);
n === count + 1 ? resolve() : setTimeout(check, 50);
};
check();
});
}
getDocumentAsImage — devuelve elemento <img>
async function getDocumentAsImage(pea) {
const result = await pea.runScript(`app.activeDocument.saveToOE('png')`);
return new Promise((resolve) => {
const fr = new FileReader();
fr.addEventListener("load", (e) => {
const img = new Image(); img.src = e.target.result; resolve(img);
});
fr.readAsDataURL(new Blob([result[0]], { type: "image/png" }));
});
}
Patrones del Mundo Real
Patrón A — Interfaz de Abrir + Exportar
<input type="file" id="fileInput" accept="image/*,.psd">
<button id="exportBtn">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("fileInput").addEventListener("change", async e => {
await pea.loadAsset(await e.target.files[0].arrayBuffer());
});
document.getElementById("exportBtn").addEventListener("click", async () => {
const blob = await pea.exportImage("png");
const a = Object.assign(document.createElement("a"), {
href: URL.createObjectURL(blob), download: "export.png"
});
a.click();
});
</script>
Patrón B — Plantilla + Edición de Texto + Exportar
async function generateCard(pea, name, tagline) {
await pea.openFromURL("https://example.com/card.psd", false);
const nameLiteral = JSON.stringify(name);
const taglineLiteral = JSON.stringify(tagline);
await pea.runScript(`
app.activeDocument.layers.getByName("Nombre").textItem.contents = ${nameLiteral};
app.activeDocument.layers.getByName("Eslogan").textItem.contents = ${taglineLiteral};
`);
return await pea.exportImage("png");
}
Patrón C — Marca de Agua por Lotes
async function batchWatermark(pea, imageURLs, watermarkURL) {
const results = [];
for (const url of imageURLs) {
await pea.openFromURL(url, false);
await pea.openFromURL(watermarkURL, 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;
`);
results.push(await pea.exportImage("png"));
await pea.runScript(`app.activeDocument.close(SaveOptions.DONOTSAVECHANGES);`);
}
return results;
}
REFERENCIA COMPLETA DE LA API DE SCRIPTING
Todo el código en esta sección se ejecuta dentro de cadenas
pea.runScript("..."). Photopea implementa la interfaz de scripting de Adobe Photoshop CC 2015. Cualquier script de Photoshop dirigido a esa versión debería funcionar en Photopea.
app — Objeto de Aplicación
Propiedades
| Propiedad | Tipo | L/E | Descripción |
|---|---|---|---|
app.activeDocument | Documento | L/E | El documento actualmente activo |
app.documents | Documentos | L | Colección de todos los documentos abiertos |
app.documents.length | número | L | Conteo de documentos abiertos |
app.documents[i] | Documento | L | Acceso por índice basado en cero |
app.foregroundColor | ColorSólido | L/E | Color frontal actual |
app.backgroundColor | ColorSólido | L/E | Color de fondo actual |
app.preferences.rulerUnits | Unidades | L/E | Units.PIXELS, Units.CM, Units.INCHES, Units.MM, Units.PICAS, Units.POINTS, Units.PERCENT |
app.preferences.typeUnits | UnidadesTipo | L/E | TypeUnits.PIXELS, TypeUnits.MM, TypeUnits.POINTS |
app.displayDialogs | ModosDiálogo | L/E | DialogModes.NO, DialogModes.ALL, DialogModes.ERROR |
Métodos
| Método | Descripción |
|---|---|
app.open(url) | Abre una URL como nuevo documento |
app.open(url, null, true) | Abre una URL como capa de objeto inteligente en el documento activo |
app.echoToOE(cadena) | Extensión de Photopea — envía una cadena a la página anfitriona (capturada por runScript) |
app.showWindow("magiccut") | Extensión de Photopea — abre el panel de Corte Mágico |
app.showWindow("vbitmap") | Extensión de Photopea — abre el panel de Vectorizar Mapa de Bits |
app.UI.zoomIn() | Acercar |
app.UI.zoomOut() | Alejar |
app.UI.fitTheArea() | Ajustar lienzo al viewport |
app.UI.pixelToPixel() | Zoom al 100% |
app.UI.switchFullscreen() | Alternar pantalla completa |
app.UI.scroll(dx, dy) | Desplazar por delta |
app.UI.scrollTo(x, y) | Desplazar a posición absoluta |
Importante: Siempre establece las unidades de regla a píxeles al inicio de cualquier script que use medidas en píxeles:
var savedUnits = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
// ... tu código ...
app.preferences.rulerUnits = savedUnits;
Document — Objeto de Documento
Acceso mediante app.activeDocument o app.documents[i].
Propiedades
| Propiedad | Tipo | L/E | Descripción |
|---|---|---|---|
width | número | L | Ancho del documento en las unidades de regla actuales |
height | número | L | Alto del documento en las unidades de regla actuales |
resolution | número | L | DPI (píxeles por pulgada) |
name | cadena | L/E | Extensión de Photopea — etiqueta de visualización (sin paso de historial) |
source | cadena | L/E | Extensión de Photopea — URL de origen del archivo o "local,X,NOMBRE" |
mode | ModoDocumento | L | DocumentMode.RGB, GRAYSCALE, CMYK, LAB, BITMAP, INDEXEDCOLOR, MULTICHANNEL |
bitsPerChannel | TipoBitsPorCanal | L | BitsPerChannelType.EIGHT, SIXTEEN, THIRTYTWO |
colorProfileName | cadena | L | Nombre del perfil de color incrustado |
activeLayer | Capa/CapaArte/ConjuntoCapas | L/E | Establecer para activar una capa |
currentLayer | CapaArte | L/E | Alias de activeLayer |
layers | Capas | L | Todas las capas de nivel superior (tanto de arte como de grupo) |
artLayers | CapasArte | L | Solo capas de arte de nivel superior |
layerSets | ConjuntosCapas | L | Solo capas de grupo de nivel superior |
selection | Selección | L | La selección actual |
channels | Canales | L | Todos los canales |
historyStates | EstadosHistorial | L | Historial de deshacer |
activeHistoryState | EstadoHistorial | L/E | Posición actual del historial |
layerComps | ComposicionesCapa | L | Colección de composiciones de capa |
guides | Guías | L | Colección de guías |
pathItems | ElementosTrazado | L | Trazados vectoriales |
id | número | L | ID único del documento |
saved | booleano | L | Indica si el documento tiene cambios sin guardar |
quickMaskMode | booleano | L | Indica si está en modo máscara rápida |
backgroundLayer | CapaArte | L | La capa de fondo |
pixelAspectRatio | número | L | Relación de aspecto de píxel personalizada (0.1–10.0) |
histogram | array | L | Array de histograma de 256 elementos |
Métodos
| Método | Firma | Descripción |
|---|---|---|
resizeImage | (w, h, res, métodoRemuestreo) | Redimensiona los píxeles de la imagen. MétodoRemuestreo: BICUBIC, BILINEAR, NEARESTNEIGHBOR, NONE, BICUBICSHARPER, BICUBICSMOOTHER |
resizeCanvas | (w, h, ancla) | Redimensiona el lienzo sin escalar. PosiciónAncla: TOPLEFT, TOPCENTER, TOPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER, BOTTOMRIGHT |
rotateCanvas | (grados) | Rota todo el lienzo. Positivo = en sentido horario |
flipCanvas | (dirección) | Direction.HORIZONTAL o Direction.VERTICAL |
crop | ([x1,y1,x2,y2], ángulo, w, h) | Recorta el lienzo. El ángulo y las dimensiones son opcionales |
trim | (tipoRecorte, superior, izquierda, inferior, derecha) | Recorta ... (truncado para traducción) |