Skip to content

AI-native design editor. Open-source Figma alternative.

feat(figma-api): add setCurrentPageAsync and PageNode.loadAsync (#1450)

IvyTechnx7bcdd2d24c71
diff --git a/changes/1450/added.md b/changes/1450/added.md
new file mode 100644
index 000000000..5be2de4b6
--- /dev/null
+++ b/changes/1450/added.md
@@ -0,0 +1 @@
+- Scripts written for Figma's dynamic-page mode can switch pages with `figma.setCurrentPageAsync()` and load a page with `page.loadAsync()`, as in Figma, instead of stopping at the first of these calls.
diff --git a/packages/core/src/figma-api/compatibility.ts b/packages/core/src/figma-api/compatibility.ts
index c12624487..4f4d6503b 100644
--- a/packages/core/src/figma-api/compatibility.ts
+++ b/packages/core/src/figma-api/compatibility.ts
@@ -27,6 +27,7 @@ export type SupportedPluginAPI = Pick<
| 'base64Encode'
| 'loadFontAsync'
| 'notify'
+ | 'setCurrentPageAsync'
| 'createComponent'
| 'createConnector'
| 'createEllipse'
diff --git a/packages/core/src/figma-api/index.ts b/packages/core/src/figma-api/index.ts
index 24cc55d52..2b86ff2e3 100644
--- a/packages/core/src/figma-api/index.ts
+++ b/packages/core/src/figma-api/index.ts
@@ -174,6 +174,22 @@ export class FigmaAPI implements NodeProxyHost {
return this.getNodeById(id)
}
+ /**
+ * The page switch Figma requires in dynamic-page mode, which sets `currentPage`. As in Figma, a
+ * missing node throws at once and a node that is no page rejects.
+ */
+ setCurrentPageAsync(page: FigmaNodeProxy): Promise<void>
+ setCurrentPageAsync(page: PageNode): Promise<void>
+ // Scripts are not type-checked, so the call checks for a missing node as Figma does.
+ setCurrentPageAsync(page: PageNode | FigmaNodeProxy | null | undefined): Promise<void> {
+ if (page == null) throw new Error(`in setCurrentPageAsync: Expected node, got ${String(page)}`)
+ if (this._rawNode(page).type !== 'CANVAS') {
+ return Promise.reject(new Error('figma.setCurrentPageAsync expects a PageNode'))
+ }
+ this._currentPageId = this._nodeId(page)
+ return Promise.resolve()
+ }
+
// --- Node Creation ---
/** New layers start as the editor's tools make them, which is how Figma's plugin API makes them. */
diff --git a/packages/core/src/figma-api/proxy.ts b/packages/core/src/figma-api/proxy.ts
index 2ab733dda..23e424538 100644
--- a/packages/core/src/figma-api/proxy.ts
+++ b/packages/core/src/figma-api/proxy.ts
@@ -183,6 +183,8 @@ export class FigmaNodeProxy {
declare authorVisible: boolean | undefined
declare isWideWidth: boolean | undefined
declare shapeType: ShapeWithTextType | undefined
+ /** On pages alone, as in Figma. */
+ declare loadAsync: () => Promise<void>
declare resetOverrides: () => void
declare strokeWeight: number
@@ -276,6 +278,10 @@ export class FigmaNodeProxy {
const internals = { id: INTERNAL_ID, graph: INTERNAL_GRAPH, api: INTERNAL_API }
if (type === 'VECTOR') installVectorNodeProxyAccessors(this, internals, MIXED)
if (type) installShapeNodeProxyAccessors(this, internals, type)
+ // Figma loads a page's layers on demand in dynamic-page mode and has `loadAsync` on pages
+ // alone; every page here is already loaded.
+ if (type === 'CANVAS')
+ Object.defineProperty(this, 'loadAsync', { value: () => Promise.resolve() })
}
private _update(changes: Partial<SceneNode>): void {
diff --git a/packages/core/tests/figma-api/pages.test.ts b/packages/core/tests/figma-api/pages.test.ts
index ed145cdf5..9e66be8de 100644
--- a/packages/core/tests/figma-api/pages.test.ts
+++ b/packages/core/tests/figma-api/pages.test.ts
@@ -43,3 +43,42 @@ describe('document & pages', () => {
expect(api.getNodeById('nonexistent')).toBeNull()
})
})
+
+// Scripts written for Figma's dynamic-page mode switch pages with `setCurrentPageAsync` and load
+// a page before reading its layers. Every page of a document here is already loaded. Errors and
+// members recorded in Figma 126.
+describe('dynamic-page loading in the plugin API', () => {
+ test('setCurrentPageAsync switches the page new layers go on', async () => {
+ const figma = createAPI()
+ const page = figma.createPage()
+ await figma.setCurrentPageAsync(page)
+ expect(figma.currentPage.id).toBe(page.id)
+ expect(figma.createRectangle().parent?.id).toBe(page.id)
+ })
+
+ test('setCurrentPageAsync switches only to a page', async () => {
+ const figma = createAPI()
+ const page = figma.currentPage
+ await expect(figma.setCurrentPageAsync(figma.createFrame())).rejects.toThrow(
+ 'figma.setCurrentPageAsync expects a PageNode'
+ )
+ expect(() => figma.setCurrentPageAsync(null as never)).toThrow(
+ 'in setCurrentPageAsync: Expected node, got null'
+ )
+ expect(figma.currentPage.id).toBe(page.id)
+ })
+
+ test('loading a page resolves and leaves its layers readable', async () => {
+ const figma = createAPI()
+ const rectangle = figma.createRectangle()
+ await figma.currentPage.loadAsync()
+ expect(figma.currentPage.children.map((child) => child.id)).toEqual([rectangle.id])
+ })
+
+ test('only a page has loadAsync', () => {
+ const figma = createAPI()
+ expect('loadAsync' in figma.currentPage).toBe(true)
+ expect('loadAsync' in figma.createFrame()).toBe(false)
+ expect('loadAsync' in figma.root).toBe(false)
+ })
+})
diff --git a/packages/docs/programmable/cli/scripting.md b/packages/docs/programmable/cli/scripting.md
index 47be30bd5..79142390a 100644
--- a/packages/docs/programmable/cli/scripting.md
+++ b/packages/docs/programmable/cli/scripting.md
@@ -247,6 +247,7 @@ Common node properties are readable/writable through the proxy, including:
- `figma.loadFontAsync(fontName)` no-ops because OpenPencil does not gate text edits on plugin font loading
- `figma.listAvailableFontsAsync()` returns host-provided fonts when available
- `figma.getNodeByIdAsync(id)` and `instance.getMainComponentAsync()` resolve to the same nodes as `figma.getNodeById(id)` and `instance.mainComponent`, for scripts written for Figma's dynamic-page mode
+- `figma.setCurrentPageAsync(page)` switches pages as setting `figma.currentPage` does, and `page.loadAsync()` resolves at once because every page is already loaded, for scripts written for Figma's dynamic-page mode
- `figma.notify(message)` logs a warning in headless mode
- `instance.swapComponent(component)` points an instance at another component
- A layer inside an instance refuses `x`, `y`, `rotation`, `relativeTransform`, `constraints`, `isMask`, and `maskType` with Figma's error, such as `in set_x: This property cannot be overridden in an instance: relative-transform`; those always follow the component. Slot content keeps them, and setting one on a slot's default content makes the instance own the slot