Class: PageList
PageList represents an ordered list of PageNodes, all of which are children of the root node of the document's "scenegraph" artwork tree (see ExpressRootNode). A page contains one or more artboards, representing "scenes" in a linear timeline sequence. Those artboards, in turn, contain all the visual content of the document.
PageList also provides APIs for adding/removing pages from the document. PageList is never empty: it is illegal to remove the last remaining page from the list.
Pages outside the current viewport are not guaranteed to be fully loaded, thus the PageNode classes returned from this list do not allow accessing the page's content directly. The ActivePageNode subclass represents a Page that is fully loaded and whose contents are accessible synchronously. The current Context is always an an ActivePageNode. To load any other pages for access, use the asynchronous visitPages API.
Extends
Indexable
[key: number]: object
Constructors
Constructor
new PageList(): PageList;
Returns
PageList
Inherited from
RestrictedItemList.constructor
Accessors
length
Get Signature
get length(): number;
Number of items in this list.
Returns
number
Inherited from
first
Get Signature
get first(): T | undefined;
First item in this list, or undefined if list is empty.
Returns
T | undefined
Inherited from
last
Get Signature
get last(): T | undefined;
Last item in this list, or undefined if list is empty.
Returns
T | undefined
Inherited from
Methods
visitPages()
visitPages(pages, callback): Promise<void>;
Experimental
data-slots=text
data-variant=warning
experimentalApis flag to true in the requirements section of the manifest.json.Visit the given pages asynchronously: loading each one in turn so its content is accessible, and then invoking your provided callback for the resulting fully-accessible ActivePageNode.
The callback receives an ActivePageNode, which provides full access to the page's content tree (artboards and all descendants). This access is only guaranteed inside the callback; do not hold onto the reference after the callback returns.
Visiting many pages can be slow – up to tens of seconds in larger documents. Any feature which visits all pages in the entire document should include a progress UI so users understand when the operation is still ongoing.
There is no guarantee more than one of the Pages will be loaded at the same time – there may only be one page accessible at a time, each visited with sight delays in between. If your callback returns long-running promises, iteration may pause until some of the promises resolve and free up capacity to load the next page(s) in the visit list.
Pages may be visited in a different order than provided for performance reasons, but each callback is still called exactly once per page.
Use an async callback (or return a promise) so visitPages waits for all await work on each page before moving on. Do not start async work without awaiting it as it may make the page inactive before your edits run.
Parameters
callbackpage) => void | Promise<void>await on host APIs (such as loadBitmapImage) or UI proxy methods. Use an async callback so visitPages waits until your per-page work finishes.Returns
Promise<void>
Examples
Call a UI iframe API to translate text on each page, then write the result back to the page (no keepContentActiveDuringAsync needed). panelUiProxy.translateText is a method on your add-on's UI iframe proxy:
await pages.visitPages([...pages], async (page) => {
// Assume the first child is a text node for now
const textNode = page.artboards.first.children.item(0) as TextNode;
const translated = await panelUiProxy.translateText(textNode.fullContent.text);
textNode.fullContent.text = translated;
});
Load an image from the host, then add it to the page:
await pages.visitPages([...pages], async (page) => {
const bitmap = await editor.loadBitmapImage(imageBlob);
const container = editor.createImageContainer(bitmap);
page.artboards.first.children.append(container);
});
addPage()
addPage(inputGeometry): ActivePageNode;
Create a new page containing a single empty artboard, and add it to the end of the list. The artboard is configured with the same defaults as in ArtboardList.addArtboard. The page's artboard becomes the default target for newly inserted content (Context.insertionParent) and the viewport switches to display this artboard.
The newly created page starts out already "active" initially, so you can immediately access its subtree to populate it with content. You should not hold onto this ActivePageNode reference across an async period of time however, since it might become inaccessible at any point after the initial synchronous block of execution where it was created. Use Editor.keepContentActiveDuringAsync if you need to work with this page's content asynchronously.
Parameters
inputGeometryReturns
the newly created page.
indexOf()
indexOf(item): number;
Get index of item in list.
Parameters
itemReturns
number
index number, or -1 if item isn't in this list.
Inherited from
item()
item(index): PageNode | undefined;
Returns item at the given index, or undefined if index is out of range.
Parameters
indexnumberReturns
PageNode | undefined
Inherited from
[iterator]()
iterator: Iterator<PageNode>;
Iterates over all the items in this list. Mutations that occur mid-iteration are not reflected by the iterator.
Returns
Iterator<PageNode>
Inherited from
toArray()
toArray(): readonly PageNode[];
All items in the list, as a static array. Mutations that occur later are not reflected in an array returned earlier.
Returns
readonly PageNode[]
Inherited from
remove()
remove(...items): void;
Remove the items from the list. The items need not be contiguous.
Parameters
itemsPageNode[]Returns
void
Throws
If any of the items are not in the list, or if it is illegal to remove any of the items from this parent.
Inherited from
moveBefore()
moveBefore(item, before): void;
Move item so it is immediately before before in this list: places item at the index that before used to occupy. Depending on the position in the list item originally occupied, some other items in the list may shift to higher or lower indices as a result. No-op if both arguments are the same item.
Parameters
Returns
void
Throws
An error if either argument is not contained in this list.
Inherited from
moveAfter()
moveAfter(item, after): void;
Move item so it is immediately after after in this list: places item at the index one higher than after. Depending on the position in the list item originally occupied, some other items in the list may shift to higher or lower indices as a result. No-op if both arguments are the same item.
Parameters
Returns
void
Throws
An error if either argument is not contained in this list.