@express-document-sdk

Class: ExpressEditor

Entry point for Express specific APIs that read or modify the document's content.

Extends

• Editor

Constructors

Constructor

new ExpressEditor(): ExpressEditor;

Returns

ExpressEditor

Inherited from

Editor.constructor

Accessors

context

Get Signature

get context(): ExpressContext;

User's current selection context

Returns

ExpressContext

Overrides

Editor.context

documentRoot

Get Signature

get documentRoot(): ExpressRootNode;

Returns

ExpressRootNode

the root of the document.

Methods

queueAsyncEdit()

queueAsyncEdit(lambda): Promise<void>;

Legacy API for scheduling an edit after an asynchronous wait, for cases where the edit only targets whatever the current selection or Context.insertionParent happens to be at the end of the await.

New code should use keepContentActiveDuringAsync instead, which also keeps any pre-designated scenenodes accessible across the async gap and safely runs the follow-up edit.

Parameters

Returns

Promise<void>

a Promise that resolves when the lambda has finished running, or rejects if the lambda throws an error.

Example

Load an image from a Blob, then add it to the document using keepContentActiveDuringAsync:

async function addImage(blob) {
    const bitmapImage = await editor.loadBitmapImage(blob);

    await editor.keepContentActiveDuringAsync(
        editor.context.insertionParent,
        async () => {},
        () => {
            const rectangleGeometry = { width: 256, height: 256 };
            const mediaContainerNode = editor.createImageContainer(bitmapImage, {
                initialSize: rectangleGeometry
            });
            mediaContainerNode.translation = { x: 100, y: 120 };
            editor.context.insertionParent.children.append(mediaContainerNode);
        }
    );
}

Deprecated

This API will be removed after 2026-07-15. Use keepContentActiveDuringAsync instead.

Inherited from

Editor.queueAsyncEdit

keepContentActiveDuringAsync()

keepContentActiveDuringAsync<AsyncResultT>(
   target, 
   asyncLambda, 
afterAsyncCallback): Promise<void>;

Experimental

data-slots=text

data-variant=warning

Allow continued access to a subtree of content over an async span of time. Normally, access to any piece of visual content is only guaranteed during the synchronous execution span where you initially encountered it (e.g. by reading the current selection). After that, it may be unloaded from memory at any time. Use this API if you need to maintain access to specific content after awaiting an async operation (such as a server request).

Contrast to queueAsyncEdit, which you can use after an asynchronous interval to make edits only targeting whatever the current selection or Context.insertionParent is at the end of the interval – not any specific content that you predetermined earlier.

Example of typical usage:

// Assume translateText() is called from your UI code
async function translateText() {
    const textNode = editor.context.selection[0] as TextNode;  // for simplicity we blindly assume text is selected

    // Call this immediately after capturing textNode — do NOT await anything before
    // calling keepContentActiveDuringAsync, or textNode may become inaccessible.
    // Edits after awaiting the async lambda need to be queued to run at a safe time, and
    // with a guarantee that 'textNode' is still accessible
    await editor.keepContentActiveDuringAsync(
        textNode,
        async () => {
            // All async work belongs here. Use iframe runtime environment to make async network call.
            // textNode is guaranteed accessible throughout, but do NOT edit the
            // document inside this lambda — put edits in afterAsyncCallback below.
            return await uiApis.callTranslationService(textNode.fullContent.text);
        },
        (translatedText) => {
            // This callback runs after the async lambda has resolved.
            // All document edits belong here. textNode is still accessible.
            // Replace the text content of textNode with the translation service's results:
            textNode.fullContent.text = translatedText;
        }
    );
    // Code here runs only after afterAsyncCallback has completed.
}

Type Parameters

Parameters

Returns

Promise<void>

Inherited from

Editor.keepContentActiveDuringAsync

createText()

Call Signature

createText(): StandaloneTextNode;

Returns

StandaloneTextNode

a text node with default styles. The text content is initially empty, so the text node will be invisible until its fullContent property's text is set. Creates auto-width text, so the node's width will automatically adjust to accommodate whatever text is set.

Deprecated

• Initial text content is always expected so please use createText(textContent: string): StandaloneTextNode.

Inherited from

Editor.createText

Call Signature

createText(textContent): StandaloneTextNode;

Parameters

Returns

StandaloneTextNode

a text node with default styles. Creates auto-width text, so the node's width will automatically adjust to accommodate the given text content.

Note: the registration point of this text node is not guaranteed to be at the top-left of the bounding box of its insertion parent. Recommend using setPositionInParent over translation to set the position.

Inherited from

Editor.createText

createEllipse()

createEllipse(): EllipseNode;

Returns

EllipseNode

an ellipse node with default x/y radii, a black fill, and no initial stroke. Transform values default to 0.

Inherited from

Editor.createEllipse

createRectangle()

createRectangle(): RectangleNode;

Returns

RectangleNode

a rectangle node with default width and height, a black fill, and no initial stroke. Transform values default to 0.

Inherited from

Editor.createRectangle

createLine()

createLine(): LineNode;

Returns

LineNode

a line node with default start point and end point and a default stroke. Transform values default to 0.

Inherited from

Editor.createLine

createGroup()

createGroup(): GroupNode;

Returns

GroupNode

a group node.

Inherited from

Editor.createGroup

makeColorFill()

makeColorFill(color): ColorFill;

Convenience helper to create a complete ColorFill value given just its color.

Parameters

Returns

ColorFill

Inherited from

Editor.makeColorFill

createImageContainer()

createImageContainer(bitmapData, options): MediaContainerNode;

Creates a bitmap image, represented as a multi-node MediaContainerNode structure. Always creates a "full-frame," uncropped image initially, but cropping can be changed after it is created by modifying the properties of the container's mediaRectangle and maskShape children.

Image creation involves some asynchronous steps. The image will be visible in this client almost instantly, but will render as a gray placeholder on other clients until it has been uploaded to DCX and then downloaded by those clients. This local client will act as having unsaved changes until the upload has finished.

Parameters

Returns

MediaContainerNode

MediaContainerNode representing the top container node of the multi-node structure.

Inherited from

Editor.createImageContainer

loadBitmapImage()

loadBitmapImage(bitmapData): Promise<BitmapImage>;

Creates a bitmap image resource in the document, which can be displayed in the scenegraph by passing it to createImageContainer to create a MediaContainerNode. The same BitmapImage can be used to create multiple MediaContainerNodes.

Because the resulting BitmapImage is returned asynchronously, to use it you must schedule an edit lambda to run at a safe later time in order to call createImageContainer. Use Editor.keepContentActiveDuringAsync if you need to work with this page's content asynchronously.

Further async steps to upload image resource data may continue in the background after this call's Promise resolves, but the resulting BitmapImage can be used right away (via the queue API noted above). The local client will act as having unsaved changes until all the upload steps have finished.

Parameters

Returns

Promise<BitmapImage>

Inherited from

Editor.loadBitmapImage

makeStroke()

makeStroke(options?): SolidColorStroke;

Convenience helper to create a complete SolidColorStroke value given just a subset of its fields. All other fields are populated with default values.

See SolidColorStroke for more details on the options fields. Defaults:

• color has default value DEFAULT_STROKE_COLOR if none is provided.
• width has default value DEFAULT_STROKE_WIDTH if none is provided.
• position has default value center if none is provided.
• dashPattern has default value [] if none is provided.
• dashOffset has default value 0 if none is provided. This field is ignored if no dashPattern was provided.
• type has default value SolidColorStroke.type if none is provided. This field shouldn't be set to any other value.

Parameters

Returns

SolidColorStroke

a stroke configured with the given options.

Inherited from

Editor.makeStroke

createThreadedText()

createThreadedText(
   parentNode, 
   textContent, 
   geometry?): ThreadedTextNode;

Experimental

data-slots=text

data-variant=warning

Parameters

Returns

ThreadedTextNode

A new ThreadedTextNode that is part of a threaded text flow.

Throws

if parentNode is not provided or is not a valid container node.

Throws

if textContent is empty or invalid.

Inherited from

Editor.createThreadedText

createPath()

createPath(path): PathNode;

Parameters

Returns

PathNode

a path node with a default stroke and no initial fill.

Inherited from

Editor.createPath