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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 | undefineddeclare isWideWidth: boolean | undefineddeclare shapeType: ShapeWithTextType | undefined+ /** On pages alone, as in Figma. */+ declare loadAsync: () => Promise<void>declare resetOverrides: () => voiddeclare 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.tsindex 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.mdindex 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