modifyPageElements

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

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 existing elements (with uuid) obtained via getElements, etc.; uuid stays the same before and after modification. Two checks apply here as well: the uuid must still be present in the native cache (if not found, the item is silently skipped without a separate error), and the element must already exist on the page; a missing cache entry is caught at the earlier stage and never reaches the “does it already exist on the page” check. See Element Caching and Release for details. Parameters

Parameter	Type	Description
`elements`	`Element[]`	Elements to modify. They must already exist on the target page
`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<number[]>: result is the list of in-page element indices modified successfully, starting from 1

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: modify elements on a specified page in the current file.
 */
export async function exampleModifyPageElements(elements: Element[]) {
  const page = 0;
  const layer = 0;
  const res = await PluginCommAPI.modifyPageElements(elements, page, layer);
  if (!res.success) {
    console.log('modifyPageElements failed', res.error);
    throw new Error(res.error?.message ?? 'modifyPageElements call failed');
  }
  console.log('modifyPageElements result', res.result);
  return res.result;
}

​Example

Example