insertPageElements

static insertPageElements(
  elements: Element[],
  page: number,
  layer?: number | null
): Promise<APIResponse<boolean>>;

In sn-plugin-lib later than 0.1.65, the size of the current page is also obtained through PluginFileAPI.getPageSize (first use getCurrentFilePath and getCurrentPageNum to get the file path and page number). In 0.1.65 and earlier, call getPageDisplaySize to get the current page display size and do not call getPageSize, otherwise the position data may not match.

The elements you pass in typically come from createElement or existing elements read from elsewhere; uuid stays the same before and after insertion. This API requires those elements to still be present in the native cache — elements that can’t be found in the cache are silently skipped instead of causing a separate error. See Element Caching and Release for details. Parameters

Parameter	Type	Description
`elements`	`Element[]`	Elements to insert
`page`	`number`	Page index, starting from `0`
`layer`	`number \| null`	Optional layer parameter. For note files (`.note`), when omitted, the current layer is used. For recognized notes, the parameter is ignored whether you pass it or not because recognized notes have only one layer. For document files (`.pdf`, `.epub`, etc.), the parameter is ignored whether you pass it or not because document files have only one layer. When provided, valid values are `0-3`

Returns

APIResponse<boolean>: result === true indicates the insertion succeeded

Throws

Throws a parameter validation error when elements is not a valid element array
Throws a parameter validation error when page is not an integer greater than or equal to 0
Throws a parameter validation error when layer is provided but is not an integer in the range 0-3

Example

import { PluginCommAPI, type Element } from 'sn-plugin-lib';

/**
 * Example: insert elements into a specified page in the current file.
 */
export async function exampleInsertPageElements(elements: Element[]) {
  const page = 0;
  const layer = 0;
  const res = await PluginCommAPI.insertPageElements(elements, page, layer);
  if (!res.success) {
    console.log('insertPageElements failed', res.error);
    throw new Error(res.error?.message ?? 'insertPageElements call failed');
  }
  console.log('insertPageElements result', res.result);
  return res.result;
}

​Example

Example