insertElements - Supernote

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 — if an element’s uuid can no longer be found in the cache (e.g. already released via recycleElement/clearElementCache), that item is silently skipped instead of causing a separate error. See Element Caching and Release for details.

static insertElements(notePath: string, page: number, elements: Element[]): Promise<APIResponse<boolean>>;

Parameters

Parameter	Type	Description
`notePath`	`string`	NOTE file path
`page`	`number`	Page index (starts from `0`)
`elements`	`Element[]`	Element data array

Returns

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

Example

This example applies to sn-plugin-lib later than 0.1.65. It writes Android pixel coordinates, based on the actual page size returned by getPageSize. In 0.1.65 and earlier, what you write is EMR coordinates, so you need to convert them with PointUtils first.

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

/**
 * Example: create an element and insert it into a page.
 */
export async function exampleInsertElements() {
 const notePath = '/storage/emulated/0/Note/demo.note';
 const page = 0;

 const createRes = await PluginCommAPI.createElement(0);
 if (!createRes.success) {
 throw new Error(createRes.error?.message ?? 'createElement call failed');
 }

 const element = createRes.result as Element;
 const pressures = [800, 900, 1000];
 const pageSizeRes = await PluginFileAPI.getPageSize(notePath, page);
 if (!pageSizeRes.success) {
 throw new Error(pageSizeRes.error?.message ?? 'getPageSize call failed');
 }
 const { width, height } = pageSizeRes.result;
 // Android pixel coordinates, within the actual page size width × height
 const points = [
 { x: width * 0.2, y: height * 0.2 },
 { x: width * 0.4, y: height * 0.3 },
 { x: width * 0.6, y: height * 0.35 },
 ];
 element.thickness = 2;
 if (element.stroke) {
 element.stroke.penColor = 0;
 element.stroke.penType = 16;
 await element.stroke.points.setRange(0, points.length - 1, points);
 await element.stroke.pressures.setRange(0, pressures.length - 1, pressures);
 }
 const res = await PluginFileAPI.insertElements(notePath, page, [element]);
 if (!res.success) {
 throw new Error(res.error?.message ?? 'insertElements call failed');
 }
 return res.result;
}

​Example

Example