openpencil/packages/docs/es/programmable/cli/scripting.md

title	description
Scripting	Ejecutar JavaScript con una API compatible con plugins de Figma para consultar, modificar y generar diseños.

Scripting

openpencil eval ejecuta JavaScript sobre un documento y proporciona un objeto global figma. Resulta útil para cambios por lotes, inspección, datos de prueba y automatización sin abrir la interfaz del editor.

Uso básico

openpencil eval design.fig -c "return figma.currentPage.children.length"

-c acepta JavaScript. Si el código no empieza por return, OpenPencil lo ejecuta dentro de una función asíncrona y devuelve el resultado cuando existe.

openpencil eval design.fig -c "
  const frame = figma.createFrame()
  frame.name = 'Card'
  frame.resize(300, 200)
  frame.layoutMode = 'VERTICAL'
  frame.itemSpacing = 12
  return { id: frame.id, name: frame.name }
"

Consultar objetos

openpencil eval design.fig -c "
  return figma.currentPage
    .findAll((node) => node.type === 'FRAME' && node.name.includes('Button'))
    .map((button) => ({ id: button.id, name: button.name }))
"

Modificar y guardar

--write o -w sobrescribe el archivo de entrada. --output o -o crea otro.

openpencil eval design.fig -c "figma.currentPage.name = 'Updated'" -o updated.fig

Leer el script de stdin

cat transform.js | openpencil eval design.fig --stdin --write

Documento abierto

Omite la ruta para ejecutar el script sobre el documento activo en la aplicación de escritorio:

openpencil eval -c "return figma.currentPage.name"

Salida

En entornos no interactivos, eval usa JSON de forma predeterminada. --json lo solicita explícitamente y --quiet o -q oculta la salida cuando solo se escribe un archivo.

API compatible

La API sigue el modelo de Figma Plugin API, pero actúa sobre SceneGraph y los formatos de OpenPencil.

Documento y páginas

• figma.root
• figma.currentPage
• figma.currentPage.selection
• figma.getNodeById(id)
• figma.createPage()

Crear objetos

• figma.createFrame()
• figma.createRectangle()
• figma.createEllipse()
• figma.createText()
• figma.createLine()
• figma.createPolygon()
• figma.createStar()
• figma.createVector()
• figma.createComponent()
• figma.createSection()

Operaciones de árbol

children, parent, appendChild, insertChild, clone, remove, findAll, findOne, findChild, findChildren, figma.group y figma.ungroup funcionan como sus equivalentes de Figma.

Componentes y variables

Se admiten creación de componentes e instancias, consulta del componente principal, colecciones, modos, creación y eliminación de variables y enlaces mediante bindVariable y unbindVariable.

Propiedades

Las propiedades habituales se leen y modifican mediante el objeto correspondiente: geometría, apariencia, radios, texto, disposición automática y contornos. Se conservan nombres exactos como fills, fontSize, layoutMode y strokeWeight.

Utilidades

• figma.mixed
• figma.createImage(data)
• figma.loadFontAsync(fontName) — no bloquea la edición de texto;
• figma.listAvailableFontsAsync() — devuelve las fuentes del sistema;
• figma.notify(message) — escribe un aviso cuando no hay interfaz;
• figma.viewport.

Limitaciones

Aún no hay equivalentes completos para node.exportAsync(), node.setBoundVariable(), node.detachInstance(), figma.combineAsVariants(), estilos de pintura/texto y todas las operaciones booleanas vectoriales.

Según la tarea, pueden usarse el comando de exportación, las herramientas del núcleo o las operaciones directas de SceneGraph.