`open-pencil eval` — API Pluginów kompatybilne z Figmą do skryptowania headless

Przegląd

bun open-pencil eval <file> --code '<js>' wykonuje JavaScript na pliku .fig z globalnym obiektem figma kompatybilnym z Figmą. Umożliwia to skryptowanie headless, operacje wsadowe, wykonywanie narzędzi AI i testy — wszystko bez GUI.

Obiekt figma odzwierciedla powierzchnię API Pluginów Figmy jak najdokładniej, więc istniejąca wiedza o pluginach Figmy i fragmenty kodu są bezpośrednio przenośne.

# Utworzenie ramki, ustawienie auto-layout, dodanie dzieci
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 }
'

# Zapytanie o węzły
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 }))
'

# Zapis zmian
bun open-pencil eval design.fig --code '...' --write

Architektura

CLI: open-pencil eval <file> --code '...'
  → loadDocument(file) → SceneGraph
  → FigmaAPI(sceneGraph) → proxy `figma`
  → AsyncFunction('figma', code)(figmaProxy)
  → wydruk wyniku / zapis pliku z --write

Główne klasy

Klasa	Lokalizacja	Rola
`FigmaAPI`	`packages/core/src/figma-api.ts`	Obiekt proxy implementujący metody `figma.*`
`FigmaNode`	`packages/core/src/figma-api.ts`	Proxy opakowujący `SceneNode` z dostępem do właściwości w stylu Figmy
Polecenie `eval`	`packages/cli/src/commands/eval.ts`	Ładuje dokument, tworzy API, wykonuje kod

Dlaczego w `@open-pencil/core`?

Klasa FigmaAPI żyje w core, ponieważ: narzędzia AI ją reużywają, testy mogą jej używać i nie ma zależności DOM.

Polecenie CLI

bun open-pencil eval <file> [opcje]

Argumenty:
  file            Plik .fig do przetworzenia

Opcje:
  --code, -c      Kod JavaScript do wykonania
  --stdin         Odczyt kodu ze stdin
  --write, -w     Zapis zmian do pliku wejściowego
  -o, --output    Zapis do innego pliku
  --json          Wynik jako JSON
  --quiet, -q     Pomiń wydruk

Implementacja fazowa

Faza 1: Core — tworzenie węzłów, właściwości, operacje na drzewie, auto-layout, tekst (~80% realnych skryptów)
Faza 2: Komponenty i Instancje — createComponent, createInstance, detachInstance
Faza 3: Zmienne — getLocalVariables, createVariable, setBoundVariable
Faza 4: Style i Zaawansowane — style paint/tekst/efekty, operacje boolowskie

Pełna referencja API po angielsku

2.7 KiB Raw Blame History

open-pencil eval — API Pluginów kompatybilne z Figmą do skryptowania headless