2c9bb8fcd7
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.
116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
---
|
|
title: Scripting
|
|
description: 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
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
openpencil eval design.fig -c "figma.currentPage.name = 'Updated'" -o updated.fig
|
|
```
|
|
|
|
## Leer el script de stdin
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|