feat(figma-api): add detachInstance() to instances (#778 )

instance.detachInstance() turns an instance into a frame that keeps its content, as in Figma, from scripts run through eval. It reuses the graph's shared detach implementation, asserts editability like the proxy's other mutations, and joins the instance surface check against @figma/plugin-typings.

2026-09-30 05:19:11 +04:00

3.6 KiB

Raw Blame History

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(), 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.

3.6 KiB Raw Blame History