> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supernote.com/llms.txt
> Use this file to discover all available pages before exploring further.

# modifyPageElements

> 修改当前文件指定页面中的已有元素。

```ts wrap theme={null}
static modifyPageElements(
  elements: Element[],
  page: number,
  layer?: number | null
): Promise<APIResponse<number[]>>;
```

<Note>
  当该接口操作的是当前页时，请先调用 [`getPageDisplaySize`](/zh/api-reference/supernote-plugin/plugin-comm-api/get-page-display-size) 获取当前页面显示尺寸，不要调用 [`PluginFileAPI.getPageSize`](/zh/api-reference/supernote-plugin/plugin-file-api/get-page-size) 获取文件页面尺寸，否则位置数据可能对不上。
</Note>

传入的 `elements` 通常来自 `getElements` 等接口读到的既有元素（带 `uuid`），修改前后 `uuid` 保持不变。这里同样存在两层校验：`uuid` 必须还在原生缓存中（找不到会被直接跳过，不会单独报错），并且元素必须已存在于该页面；缓存缺失会在更早阶段被跳过，不会再走到"是否已存在于页面"这一步，详见 [Element 缓存与释放](/zh/plugin-base/file-op/element-op#4-element-缓存与释放)。

**参数**

| 参数         | 类型                                                            | 说明                                                                                                                               |
| ---------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `elements` | [`Element[]`](/zh/api-reference/supernote-plugin/types/trail) | 要修改的元素数组，必须是指定页面中已存在的元素                                                                                                          |
| `page`     | `number`                                                      | 页面索引，从 `0` 开始                                                                                                                    |
| `layer`    | `number \| null`                                              | 可选图层参数。笔记文件（`.note`）不传时使用当前图层；如果是识别笔记，不管传不传都不会使用该参数，因为识别笔记只有一个图层；文档文件（`.pdf`、`.epub` 等）不管传不传都不会使用该参数，因为文档文件只有一个图层。传值时取值范围为 `0-3` |

**返回**

* [`APIResponse<number[]>`](/zh/api-reference/supernote-plugin/types/api-response)：`result` 为修改成功的元素页内序号列表，序号从 `1` 开始

**异常**

* 当 `elements` 不是合法的元素数组时，会抛出参数校验异常
* 当 `page` 不是大于等于 `0` 的整数时，会抛出参数校验异常
* 当 `layer` 传值且不是 `0-3` 的整数时，会抛出参数校验异常

## 示例

```ts wrap theme={null}
import { PluginCommAPI, type Element } from 'sn-plugin-lib';

/**
 * 修改当前文件指定页面元素的示例。
 */
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 调用失败');
  }
  console.log('modifyPageElements result', res.result);
  return res.result;
}
```