`open-pencil eval` — API Plugin Figma-compatibile per scripting headless

Panoramica

bun open-pencil eval <file> --code '<js>' esegue JavaScript su un file .fig con un oggetto globale figma compatibile con Figma. Questo abilita scripting headless, operazioni batch, esecuzione di strumenti IA e test — tutto senza la GUI.

L'oggetto figma rispecchia la superficie dell'API Plugin di Figma il più fedelmente possibile, così le conoscenze esistenti sui plugin Figma e gli snippet di codice sono direttamente trasferibili.

# Creare un frame, impostare auto-layout, aggiungere figli
bun open-pencil eval design.fig --code '
  const frame = figma.createFrame()
  frame.name = "Card"
  frame.resize(300, 200)
  frame.layoutMode = "VERTICAL"
  frame.itemSpacing = 12
  frame.fills = [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }]
  return { id: frame.id, name: frame.name }
'

# Interrogare nodi
bun open-pencil eval design.fig --code '
  const buttons = figma.currentPage.findAll(n => n.name.includes("Button"))
  return buttons.map(b => ({ id: b.id, name: b.name }))
'

# Scrivere le modifiche
bun open-pencil eval design.fig --code '...' --write

Architettura

CLI: open-pencil eval <file> --code '...'
  → loadDocument(file) → SceneGraph
  → FigmaAPI(sceneGraph) → proxy `figma`
  → AsyncFunction('figma', code)(figmaProxy)
  → stampa risultato / salva file con --write

Classi principali

Classe	Posizione	Ruolo
`FigmaAPI`	`packages/core/src/figma-api.ts`	Oggetto proxy che implementa metodi `figma.*`
`FigmaNode`	`packages/core/src/figma-api.ts`	Proxy che avvolge `SceneNode` con accesso proprietà stile Figma
Comando `eval`	`packages/cli/src/commands/eval.ts`	Carica documento, crea API, esegue codice

Perché in `@open-pencil/core`?

La classe FigmaAPI è nel core perché: gli strumenti IA la riutilizzano, i test possono usarla e non ha dipendenze DOM.

Comando CLI

bun open-pencil eval <file> [opzioni]

Argomenti:
  file            File .fig su cui operare

Opzioni:
  --code, -c      Codice JavaScript da eseguire
  --stdin         Leggere codice da stdin
  --write, -w     Scrivere le modifiche nel file di input
  -o, --output    Scrivere in un file diverso
  --json          Output come JSON
  --quiet, -q     Sopprimere l'output

Implementazione a fasi

Fase 1: Core — creazione nodi, proprietà, operazioni albero, auto-layout, testo (~80% degli script reali)
Fase 2: Componenti & Istanze — createComponent, createInstance, detachInstance
Fase 3: Variabili — getLocalVariables, createVariable, setBoundVariable
Fase 4: Stili & Avanzato — stili paint/testo/effetti, operazioni booleane

Riferimento API completo in inglese

2.8 KiB Raw Blame History

open-pencil eval — API Plugin Figma-compatibile per scripting headless