pixso

The JavaScript of the plug-in will run in a restricted sandbox, so there is no access to the browser API. But we provide a global variable pixso, through pixso can access most of the plug-in API, to achieve the operation function of the editor, node, style, etc.

General

`mixed`

Readonly: true
Type: string

pixso.mixed is a constant value that is returned when getting a property of a node if the property is a mixed value.

`fileKey`

Readonly: true
Type: string | undefined

The file key of the current file this plugin is running on.

`pluginId`

Readonly: true
Type: string

The value specified in the manifest.json id field. This only exists for Plugins.

`command`

Readonly: true
Type: string

The currently executing command from the manifest.json file. It is the command string in the ManifestMenuItem. If the plugin does not have any menu item, this property is undefined.

`startup`

Readonly: true
Type: Startup

/**
 * SHORTCUT Start by shortcut key
 * DEFAULT Default startup
 * RESTART Restart
 */
type Startup = "NORMAL" | "SHORTCUT" | "DEFAULT" | "RESTART";

Get the startup method of the plugin.

HWDC

`isLoadByShortcut`

Readonly: true
Type: Boolean

Indicates whether the current plugin is invoked by shortcut key.

`showUI`

showUI(html: string, options?: ShowUIOptions): void;
interface ShowUIOptions {
	visible?: boolean;
	title?: string;
	width?: number;
	height?: number;
	position?: { x: number; y: number };
	themeColors?: boolean;
	mode?: "NORMAL" | "SIMPLIFIED";
	enableMinimize?: boolean;
}

Enables you to render UI to interact with the user, or simply to access browser APIs. This function creates a modal dialog with an iframe containing the HTML markup in the html argument.

Parameter:

html: The HTML to insert into the iframe. You can pass in the HTML code as a string here, but this will often be the global value __html__. The value of html is the content of the file specified by the ui field in manifest.json.

options: An object that may contain the following optional parameters:

visible: Optional, controls whether the UI modal box is visible or not, type is boolean, default is true.
title: Optional, the title of the UI modal box.
width: Optional, the width of the UI modal box iframe, default is 300.
height: Optional, the height of the UI modal box iframe, default is 240.
position: Optional, the horizontal and vertical position of the UI modal box.
themeColors: Optional, the theme of the UI modal box, type is boolean, default is false.
mode: Optional, set the display mode of the UI modal box, the default is NORMAL, SIMPLIFIED mode will hide the plug-in icon and title. Reading and writing can be done by calling pixso.ui.mode.
enableMinimize: Optional, set whether the UI modal box displays the minimize button, the default is false. It can be read and written by calling pixso.ui.enableMinimize.

`ui`

Readonly: true
Type: UIAPI

These are methods and properties available on the pixso.ui global objects. A UI is created via pixso.showUI.

`host`

Readonly: true
Type: HostAPI

This object provides some methods of the host context in which the plugin runs.

`mouse`

Readonly: true
Type: MouseAPI

This property contains mouse-related properties.

`editor`

Readonly: true
Type: EditorAPI

This property contains editor related properties.

HWDC

`keyboard`

Readonly: true
type: KeyboardAPI

Editor keyboard related methods are provided under this property.

`viewport`

Readonly: true
Type: ViewportAPI

This property contains methods for reading and setting the viewport (the user-visible area of the current page).

`vectorEditor`

Readonly: true
Type: VectorEditorAPI

Provides APIs for editing vector layers.

`currentTheme`

Readonly: true
Type: ThemeType

This property returns the theme color in the current preferences of the pixso application.

`currentTool`

Type: ToolType

This property reads or sets the current brush tool type

`closePlugin`

Type: closePlugin(message?: string): void

Closes the plugin. You should always call pixso.closePlugin() once your plugin is done running. When called, any UI that's open will be closed and any setTimeout or setInterval timers will be cancelled.

Parameter:

message: Optional -- display a visual bell toast with the message after the plugin closes.

`notify`

notify(message: string, options?: NotificationOptions): NotificationHandler;
interface NotificationOptions {
	timeout?: number;
	error?: boolean;
	icon?: "SUCCESS" | "ERROR" | "WARN" | "INFO";
	position?: "TOP" | "BOTTOM" | "RIGHT_BOTTOM";
}
interface NotificationHandler {
	cancel: () => void
}

Display a notification message on the screen. pixso.notify() returns an object containing a cancel method. After cancellation, the notification message can be removed.

Parameter:

message: Optional, The message to show. options: Optional, you can configure the length and style of the message notification, the parameters are as follows:

timeout: How long the notification stays up in milliseconds before closing. Defaults to 4 seconds when not specified.
error: If true, display the notification as an error message, with a different color.
icon: Prompt the icon shown in front of the message content. Pixso provides four status icons: SUCCESS, ERROR, WARN, and INFO. If error is true, only the ERROR icon will be displayed.
position: The location of the notification message, the default is TOP。

`loading`

loading(message: string, options?: LoadingOptions): LoadingHandler;
interface LoadingOptions {
  position?: "TOP" | "BOTTOM" | "RIGHT_BOTTOM";
}
interface LoadingHandler {
  cancel: () => void
}

Display a loading status prompt on the screen, pixso.loading() returns an object containing a cancel method. The loading status prompt will not be closed regularly and needs to be closed manually.

Event

`on`

on(type: ArgFreeEventType, callback: () => void): void;

on(type: "run", callback: (event: RunEvent) => void): void;

on(type: "drop", callback: (event: DropEvent) => boolean): void;

on(type: "documentchange", callback: (event: DocumentChangeEvent) => void): void;

on(type: "themechange", callback: (theme: ThemeChangeEvent) => void): void;

on(type: "edittypechange", callback: (event: EditTypeChangeEvent) => void): void;

on(type: "detachinstance", callback: (event: DetachInstanceEvent) => void): void;

on(type: "detachstyle", callback: (event: DetachStyleEvent) => void): void;

on(type: "toptoolselect", callback: (event: ToptoolselectEvent) => void): void;

on(type: "bottomtoolselect", callback: (event: BottomToolSelectEvent) => void): void;

on(type: "contextmenuselect", callback: (event: ContextMenuSelectEvent) => void): void;

on(type: "shortcuthit", callback: (event: ShortcutHitEvent) => void): void;

on(type: "subscribelibrary", callback: (event: LibraryEvent) => void): void;

on(type: "unsubscribelibrary", callback: (event: LibraryEvent) => void): void;

Registers an callback that will be called when an event happens in the editor. Current supported events are:

selectionchange: Triggered when pixso.currentPage.selection changed.
currentpagechange: Triggered when pixso.currentPage changed.
librarychange：Triggered when the document pops up the update popup;
viewportchange: Triggered when the canvas viewport changes;
close: Triggered when the plugin is about to be closed, either from a call to pixso.closePlugin() or from the user closing the plugin.
run: Triggered when the plugin starts running.
drop: Triggered when an external object is placed on Pixso's canvas.
themechange：Triggered when the user switches the color theme (i.e. pixso.currentTheme changes);
edittypechange：Triggered when text is out of focus;
detachinstance：Triggered when the instance is detached from the component;
detachstyle：Triggered when the style is detached from the node object;
bottomtoolselect: Triggered when a bottom toolbar button customized via pixso.setBottomTools is clicked;
toptoolselect: Triggered when clicking the top toolbar button customized by pixso.setTopTools;
contextmenuselect: Triggered when clicking on pixso.setContextMenus customized right-click menu item;
shortcuthit: Triggered when a shortcuts plugin customized via pixso.setShortcuts is clicked;
subscribelibrary: Triggered when a resource library is subscribed;
unsubscribelibrary: Triggered when a subscription to a library is unsubscribed;

`once`

once(type: ArgFreeEventType, callback: () => void): void;

once(type: "run", callback: (event: RunEvent) => void): void;

once(type: "drop", callback: (event: DropEvent) => boolean): void;

once(type: "documentchange", callback: (event: DocumentChangeEvent) => void): void;

once(type: "themechange", callback: (theme: ThemeChangeEvent) => void): void;

once(type: "edittypechange", callback: (theme: EditTypeChangeEvent) => void): void;

once(type: "detachinstance", callback: (event: DetachInstanceEvent) => void): void;

once(type: "detachstyle", callback: (event: DetachStyleEvent) => void): void;

once(type: "bottomtoolselect", callback: (event: BottomToolSelectEvent) => void): void;

once(type: "toptoolselect", callback: (event: toptoolselectEvent) => void): void;

once(type: "contextmenuselect", callback: (event: ContextMenuSelectEvent) => void): void;

once(type: "shortcuthit", callback: (event: ShortcutHitEvent) => void): void;

The once method allows registering a handler for a specific event and executing the callback when the event occurs. The difference with the on method is that the event handler function registered with the once method will only be executed once.

`off`

off(type: ArgFreeEventType, callback: () => void): void;

off(type: "run", callback: (event: RunEvent) => void): void;

off(type: "drop", callback: (event: DropEvent) => boolean): void;

off(type: "documentchange", callback: (event: DocumentChangeEvent) => void): void;

off(type: "themechange", callback: (theme: ThemeChangeEvent) => void): void;

off(type: "edittypechange", callback: (theme: EditTypeChangeEvent) => void): void;

off(type: "detachinstance", callback: (event: DetachInstanceEvent) => void): void;

off(type: "detachstyle", callback: (event: DetachStyleEvent) => void): void;

off(type: "bottomtoolselect", callback: (event: BottomToolSelectEvent) => void): void;

off(type: "toptoolselect", callback: (event: toptoolselectEvent) => void): void;

off(type: "contextmenuselect", callback: (event: ContextMenuSelectEvent) => void): void;

off(type: "shortcuthit", callback: (event: ShortcutHitEvent) => void): void;

Removes event handlers bound via or pixso.once.Removes a callback added with pixso.on or pixso.once.

`root`

Readonly: true
Type: DocumentNode

The root of the entire Pixso document. This node is used to access other pages. Each child is a PageNode.

`currentPage`

Type: PageNode

The page that the user currently viewing. You can set this value to a PageNode to switch pages.

`getNodeById`

Type: getNodeById(id: string): BaseNode | null

Find the corresponding node based on the given id. If the corresponding node is not found, null is returned.

`createRectangle`

Type: createRectangle(): RectangleNode

Creates a new rectangle. The behavior is similar to using the R shortcut followed by a click.

`createLine`

Type: createLine(): LineNode

Creates a new line.

`createEllipse`

Type: createEllipse(): EllipseNode

Creates a new ellipse. The behavior is similar to using the O shortcut followed by a click. However, unlike layers created using the shortcut key, layers created using the interface will not be in the selected state.

`createPolygon`

Type: createPolygon(): PolygonNode

Create a new polygon.

`createStar`

Type: createStar(): StarNode

Create a new star.

`createVector`

Type: createVector(): VectorNode

Creates a new, empty vector network with no vertices.

`createText`

Type: createText(): TextNode

Creates a new, empty text node.

`createFrame`

Type: createFrame(): FrameNode

Creates a new frame.

`createComponent`

Type: createComponent(): ComponentNode

Creates a new, empty component.

`createPage`

Type: createPage(): PageNode

Creates a new page.

`createSlice`

Type: createSlice(): SliceNode

Creates a new slice.

`createSection`

Type: createSection(): SectionNode

Creates a new section.

`createNodeFromSvg`

Type: createNodeFromSvg(svg: string): FrameNode

Creates a new node from an SVG string. Equivalent to the SVG import function in the editor.

`createNodeFromSvgAsync`

Type: createNodeFromSvgAsync(svg: Uint8Array): Promise<FrameNode>

Create a layer from SVG's Uint8Array data.

`group`

Type: group(nodes: ReadonlyArray<BaseNode>,parent: BaseNode & ChildrenMixin,index?: number): GroupNode

Used to create a group based on the nodes specified in its parameters.

`union`

Type: union(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

Creates a new BooleanOperationNode using the contents of the node using the UNION operation. The parameters of the union are the same as in pixso.group.

`subtract`

Type: subtract(nodes: ReadonlyArray<BaseNode>,parent: BaseNode & ChildrenMixin,index?: number): BooleanOperationNode

Used to create a new boolean group (minus the top layer) layer based on the nodes specified by its parameters.

`intersect`

Type: intersect(nodes: ReadonlyArray<BaseNode>,parent: BaseNode & ChildrenMixin,index?: number): BooleanOperationNode;

Used to create a new boolean group (intersection) layer based on the nodes specified by its parameters.

`exclude`

Type: exclude(nodes: ReadonlyArray<BaseNode>,parent: BaseNode & ChildrenMixin,index?: number): BooleanOperationNode;

Used to create a new boolean group (difference set) layer based on the nodes specified by its parameters.

`flatten`

Type: flatten(nodes: ReadonlyArray<BaseNode>,parent?: BaseNode & ChildrenMixin,index?: number): VectorNode

Flattens every node in nodes into a new vector network.

`ungroup`

Type: ungroup(node: SceneNode & ChildrenMixin): Array<SceneNode>

Ungroups the given node, moving all of node's children into node's parent and removing node. Returns an array of nodes that were children of node.

`getStyleById`

Type: getStyleById(id: string): BaseStyle | null

Find the corresponding style based on the given id. If the corresponding node is not found, null is returned.

`createPaintStyle`

Type: createPaintStyle(): PaintStyle

Create a new color style that can be used for fill or stroke.

`createTextStyle`

Type: createTextStyle(): TextStyle

Create a new text style.

`createEffectStyle`

Type: createEffectStyle(): EffectStyle

Create a new effect style.

`createGridStyle`

Type: createGridStyle(): GridStyle

Create a new grid style.

`getLocalPaintStyles`

Type: getLocalPaintStyles(): PaintStyle[]

Get the local color style.

`getLocalTextStyles`

Type: getLocalTextStyles(): TextStyle[]

Get the local text style.

`getLocalEffectStyles`

Type: getLocalEffectStyles(): EffectStyle[]

Get the local effect style.

`getLocalGridStyles`

Type: getLocalGridStyles(): GridStyle[]

Get the local grid style.

library

`getLibraryListAsync`

Type: getLibraryListAsync(): Promise<LibraryItem>
Type Declaration: LibraryItem

Get the library list.

`getLibraryByKeyAsync`

Type: getLibraryByKeyAsync(key: string): Promise<Library>
Type Declaration: Library

Get library information based on key value.

`subscribeLibraryAsync`

Type: subscribeLibraryAsync(key: string): Promise<void>

Subscribe to the library. Before you want to import resources from a certain library file, it is recommended to subscribe to the resource library first, which can increase the request speed for imported resources.

`unsubscribeLibraryAsync`

Type: unsubscribeLibraryAsync(key: string): Promise<void>

Unsubscribe from the library.

`importStyleByKeyAsync`

Type: importStyleByKeyAsync(key: string): Promise<BaseStyle>

Load the style from the library.

`importComponentByKeyAsync`

Type: importComponentByKeyAsync(key: string): Promise<ComponentNode>

Load the component from the library.

`importComponentSetByKeyAsync`

Type: importComponentSetByKeyAsync(key: string): Promise<ComponentSetNode>

Load the componentSet from the library.

`publishLocalComponentAsync`

Type: publishLocalComponentAsync(libraryType?: 'ENT'|'TEAM'): Promise<void>

Publish the resource library. The same publishing function as the resource library pop-up window, but only publishes components. The value of libraryType defaults to TEAM

`publishLocalStyleAsync`

Type: publishLocalStyleAsync(libraryType?: 'ENT'|'TEAM'): Promise<void>

Publish the resource library. The same publishing function as the resource library pop-up window, but only publishes styles. The value of libraryType defaults to TEAM

`getLibraryChange`

Type: getLibraryChange(): Library[]
Type Declaration: Library

Get the library information that needs to be updated in the current document.

`updateLibraryComponentAsync`

Type: updateLibraryComponentAsync(): Promise<void>

Updating the current document requires updating component resources.

`updateLibraryStyleAsync`

Type: updateLibraryStyleAsync(): Promise<void>

Update the style resources that need to be updated in the current document.

`getLibraryComponentsInUse`

Type: getLibraryComponentsInUse(): (LibraryComponent | LibraryComponentSet)[]
Type Declaration: LibraryComponent, LibraryComponentSet

Get the cloud component resources that the current document is using.

`getLibraryStylesInUse`

Type: getLibraryStylesInUse(): LibraryStyle[]
Type Declaration: LibraryStyle

Get the cloud style resource that the current document is using.

`getLocalComponents`

Type: getLocalComponents(): (LocalComponent | LocalComponentSet)[]
Type Declaration: LocalComponent, LocalComponentSet

Get local component resources.

Storage

`clientStorage`

Readonly: true
Type: ClientStorageAPI

interface ClientStorageAPI {
  getAsync(key: string): Promise<any | undefined>;
  setAsync(key: string, value: any): Promise<void>;
  deleteAsync(key: string): Promise<void>;
  keysAsync(): Promise<string[]>;
}

Allows you to store data on the user's local machine.

`serverStorage`

Readonly: true
Type: ServerStorageAPI

interface ServerStorageAPI {
  getAsync(key?: string): Promise<any | undefined>;
  setAsync(key: string, value: any): Promise<void>;
  deleteAsync(key?: string): Promise<void>;
}

Allows you to store data on the server side.

Font

`listAvailableFontsAsync`

Type: listAvailableFontsAsync(): Promise<Font[]>

Returns a list of currently available fonts.

`loadFontAsync`

Type: loadFontAsync (fontName: FontName ): Promise<void>

Load a font to ensure that it is valid when used on a text layer.

Tool

`setTopTools`

Type：setTopTools(tools: ToolItem[]): void
Type Declaration: ToolItem

Supports defining more top menus next to the top AI magic box button. You can use pixso.on to listen to the toptoolselect event to realize the interaction between the plugin and the top menus.

`setBottomTools`

Type：setBottomTools(tools: ToolItem[]): void
Type Declaration: ToolItem

Customize bottom toolbar buttons. You can use pixso.on to listen to the bottomtoolselect event to realize the interaction between the plugin and the bottom toolbar.

`setContextMenus`

Type：setContextMenus(menus: ContextMenuItem[]): void
Type Declaration: ContextMenuItem

Customize the right-click menu. In edit mode, select the artboard and layer and right-click to display them. You can use pixso.on to listen to the contextmenuselect event to realize the interaction between the plugin and the right-click menu.

`setShortcuts`

Type：setShortcuts(shortcuts: ShortcutItem[]): void
Type Declaration: ShortcutItem

This property provides the ability to set secondary functionality for plug-ins on the plug-in dock. You can use pixso.on to listen to the shortcuthit event to realize the interaction between the plugin and the shortcuts plugins.

Undo

`commitUndo`

Type: () => void

By default, plugin operations are not committed to the undo history. The current plugin operation can be manually committed to the undo history through the pixso.commitUndo() function.

For example, let's say our plugin performs two operations, creating two rectangles:

pixso.createRectangle(); // Create the first rectangle
pixso.createRectangle(); // Create a second rectangle
pixso.triggerUndo();

At this point, when we perform the undo action, both rectangles will be undone. If we call the pixso.commitUndo() function between two rectangle creation actions:

pixso.createRectangle(); // Create the first rectangle
pixso.commitUndo(); // Add undo history
pixso.createRectangle(); // Create a second rectangle
pixso.triggerUndo();

At this time, if we perform the undo action, only the creation of the second rectangle will be undone.

`triggerUndo`

Type: () => void

Triggering the undo action will restore the state of the last commitUndo().

Image

`createImage`

Type: createImage(data: Uint8Array): Image

Create an image object with the parameter data. The created image object is not a layer node, but a handle to an image stored in Pixso.

`getImageByHash`

Type: getImageByHash(hash: string): Image | null

Get the corresponding image object by the given image hash value, otherwise return null.

Export & Import

`exportFileAsync`

Type：exportFileAsync(): Promise<Uint8Array>

Export the current Pixso file, the API returns the Promise<Uint8Array> value, which can be downloaded as a Pixso file to the local.

As a result, compared with the Export-Pixso Design File operation in the main menu of the Pixso editing interface, the exported content has fewer image resources. Therefore, when re-importing the file, it needs to be in the same environment as when the file was exported, otherwise the design draft will The image resource for will be lost.

The following is an example of downloading the Pixso file to the local through the exportFileAsync API:

/** Main thread */
const fileUint8Array = await pixso.exportFileAsync();

/** User interface */
const blob = new Blob([fileUint8Array], { type: "application/zip" });
const href = window.URL.createObjectURL(blob);
const downloadEle = document.createElement("a");
downloadEle.href = href;
// The Pixso file is actually a zip file, but the suffix needs to be changed to pix.
downloadEle.download = "design.pix";
document.body.appendChild(downloadEle);
downloadEle.click();
document.body.removeChild(downloadEle);
window.URL.revokeObjectURL(href);

`exportSceneNodeListStream`

Type：exportSceneNodeListStream(nodes: SceneNode[]): string

Export data streams of multiple layer nodes (except page and document nodes), and the returned result has been encapsulated in text/html format. You can manually write to the clipboard, and then paste it in the editor to realize the operation of copying layers.

The following is an example of copying the Pixso layer node data stream to the clipboard through the exportSceneNodeListStream API:

/** Main thread */
const stream = pixso.exportSceneNodeListStream(nodeList);

/** User interface */
document.body.addEventListener("copy", (e: ClipboardEvent) => {
  e.preventDefault();
  e.clipboardData.setData("text/html", stream);
});

document.execCommand("copy");

`importSceneNodeListStream`

Type：importSceneNodeListStream(stream: string): void

importSceneNodeListStream can import the data stream exported through the exportSceneNodeListStream, simulating the operation of pasting layers.

`convertSketchJsonAndPaste`

Type：convertSketchJsonAndPaste(sketchJSON: string): BaseNode | null

Creating new nodes from the JSON data of the sketch layer is equivalent to copying the layer JSON in sketch and pasting it into the editor.

File-Thumbnail

`getFileThumbnailNode`

Type: getFileThumbnailNode(): FrameNode | ComponentNode | ComponentSetNode | null

Gets the layer node used for the current file thumbnail, or null if the file uses the default thumbnail.

`setFileThumbnailNodeAsync`

Type: setFileThumbnailNodeAsync(node: FrameNode | ComponentNode | ComponentSetNode | null): Promise<void>

Set the layer node to be the thumbnail of the file, or use the default thumbnail if the layer node is null.

Base64

`base64Encode`

Type: base64Encode(data: Uint8Array): string

Returns a base64-encoded string from the Uint8Array data.

`base64Decode`

Type: base64Decode(data: string): Uint8Array

Decodes and returns a Uint8Array from the base64-encoded string data.

User

`currentUser`

Readonly: true
Type: CurrentUser

This property contains information about the current user.

interface CurrentUser {
  readonly id: string | null;
  readonly name: string;
  readonly photoUrl: string | null;
  readonly color: string;
  readonly sessionId: number;
  readonly uniqueId: string;
}

`activeUsers`

Readonly: true
Type: ActiveUser[]

This property contains information about the active users in the file.

interface ActiveUser {
  readonly id: string | null;
  readonly name: string;
  readonly photoUrl: string | null;
  readonly color: string;
  readonly sessionId: number;
}

Others

`saveVersionHistoryAsync`

Type: saveVersionHistoryAsync(title: string, description?: string): Promise<VersionHistoryResult>

Saves a new version of the file and adds it to the version history of the file. Returns the new version id.