> ## Documentation Index > Fetch the complete documentation index at: https://dev.marginnote.com.cn/llms.txt > Use this file to discover all available pages before exploring further. # 获取页面注释面 > 读该页上的视觉注释面：手写、插入的留白、按选择生成的留白，以及这些内容与 MarginNote 记录的对应关系。 响应里的 `parts` 是可以取图的项，`blanks` 是逻辑留白。一个按选择生成的留白可能包含多张图， 各张图须作为一组一同取用。`mapBacked` 的含义见字段说明。 `studySet` 的过滤规则见参数说明：只调整旧留白映射的解析优先级，不按学习集过滤。 ## OpenAPI ````yaml /openapi/plugin-api.yaml get /documents/{bookmd5}/pages/{index}/parts openapi: 3.1.0 info: title: 场景插件 API summary: 场景插件在网页面板里可以调用的接口。 description: > 场景插件的面板是一个网页。页面里向 `/bridge/v1` 发请求，就能读写 MarginNote 里的数据。 请求由 MarginNote 处理，与外部命令行工具共用同一套处理代码。外部工具要带令牌，面板不必带。 面板页面从 `mnpanel://panel/index.html` 加载，因此 `fetch('/bridge/v1' + path)` 属于同源请求。 面板调用受这些条件约束： - 请求不带令牌，本文件也不声明安全方案。 - 页面能调用哪些接口，取决于两份名单。模板里的 `plugins` 名单和沉浸态决定面板能不能建好， 网页面板白名单决定页面能调哪些接口。不在白名单里的请求返回 `403`， 错误码为 `IN_PROCESS_NOT_ALLOWED`。 - `GET /capabilities` 里的 `requiresMax` 只约束外部 Agent。面板的请求在 MarginNote 进程内处理， 不受令牌、订阅状态与跨设备批准的限制，能否调用只看该路径是否在白名单内。 - 写操作里的 `addon`，MarginNote 会改写为当前面板所属插件的 id；`confirm` 由 MarginNote 补上。 页面填的值不会生效。 用 `mn.api(path, opts)` 读取数据。该方法始终将 Response Body 按 JSON 解析，相当于 `fetch('/bridge/v1' + path, opts).then(r => r.json())`。 响应的内容不是 JSON 的接口，改用 `fetch`： - `GET /guide` 返回 Markdown 正文。 - `GET /notes/{noteid}/render` 返回卡片长图或 PDF。 - `GET /documents/{bookmd5}/pages/{index}/content/{contentId}` 返回图片。 - `GET /bundles/{bundleId}/files` 带 `?path=` 时返回该文件的原始字节。 调用失败时 Promise 不会进入 reject。MarginNote 把错误对象 `{"error":{"code":"…","message":"…"}}` 当作 Response Body 返回，因此结果落在 resolve 里。 判断调用结果看响应里是否带 `error`，写操作另看响应里的 `persisted`。 接口清单、各项上限与 Request Body 结构随 MarginNote 的版本变化，运行时以 `GET /capabilities` 与 `GET /guide` 返回的内容为准。 version: '0.91' servers: [] security: [] tags: - name: 能力与状态 description: 读取 MarginNote 的能力、版本与当前上下文。调用其他接口之前先读这组。 - name: 卡片与摘录 description: 卡片的读取与写入、摘录的创建、批注、标签、元数据与留白。 - name: 手写会话 description: 手写层、作答纸、练习准备清单与会话记录的读取与提交。 - name: 学习集与卡组 description: 学习集结构、脑图树、子脑图、色板、快照与复习卡组。 - name: 文档与页面 description: 文档目录、页文本、页内注释面、摘录清单与同步诊断。 - name: 导出与 Anki description: 文档导出计划、导出文件、Anki 导出能力、作业与产物。 - name: 查找 description: 跨库搜索、文件夹列表与学习集列表。 - name: 界面与模板 description: 读取当前界面状态与沉浸模板。 - name: 插件辅助 description: 面板辅助脚本、已配对设备与本机 helper 信息。 - name: 任务包与同步诊断 description: 拆书任务包与旧 CloudKit 同步诊断。 paths: /documents/{bookmd5}/pages/{index}/parts: get: tags: - 文档与页面 summary: 获取页面注释面 description: | 读该页上的视觉注释面：手写、插入的留白、按选择生成的留白，以及这些内容与 MarginNote 记录的对应关系。 响应里的 `parts` 是可以取图的项，`blanks` 是逻辑留白。一个按选择生成的留白可能包含多张图， 各张图须作为一组一同取用。`mapBacked` 的含义见字段说明。 `studySet` 的过滤规则见参数说明：只调整旧留白映射的解析优先级，不按学习集过滤。 operationId: getDocumentsBookmd5PagesIndexParts parameters: - $ref: '#/components/parameters/Bookmd5' - $ref: '#/components/parameters/PageIndex' - $ref: '#/components/parameters/StudySetQuery' responses: '200': description: 该页的注释面。可能还有未列出的字段。 content: application/json: schema: $ref: '#/components/schemas/DocumentPartsResponse' examples: assembled: summary: 构造示例，未实测 value: parts: - contentId: 4A3B2C1D-5E6F-4708-9A1B-2C3D4E5F6071 contentPath: pages/12/handwriting.png topicid: 77012CA0-48E8-4D29-B5F5-1EEA927AE086 kind: handwriting blanks: - contentIds: - 4A3B2C1D-5E6F-4708-9A1B-2C3D4E5F6071 segments: - 1 mapBacked: true topicFilteringApplied: false measured: summary: 实测于 2026-10-07，App 0.91 value: topicFilteringApplied: false documentHandwritingContentIds: [] blanks: - height: 320 physicalNoteResolved: true blankId: blank-981b1f9e61b4 sourcePage: 1 segments: - bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 blankPage: 65795 notes: - topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 hostNoteid: 48FECCDA-BA29-477F-9B9D-B5B44D5FB051 physicalNoteid: 509CC486-1B22-4BD5-8CFF-FC0CC22FF72E role: physical noteid: 509CC486-1B22-4BD5-8CFF-FC0CC22FF72E - topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D hostNoteid: D3085422-2CB9-4B68-A78D-DEE351CF9C38 physicalNoteid: 509CC486-1B22-4BD5-8CFF-FC0CC22FF72E role: reference noteid: B2C6E32F-323D-458B-994A-20206B73B730 contentIds: - blank-0-image-0 position: x: 82.5 'y': 143.2 mapBacked: false kind: inserted closed: false - height: 320 physicalNoteResolved: true blankId: blank-020048f2077e sourcePage: 1 segments: - bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 documentPage: 65795 blankPage: 65796 notes: - topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 hostNoteid: 48FECCDA-BA29-477F-9B9D-B5B44D5FB051 physicalNoteid: BD3D9809-0917-4D2C-B999-08E504F2097E role: physical noteid: BD3D9809-0917-4D2C-B999-08E504F2097E - topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D hostNoteid: 8C8BDA1E-DD08-4453-98CA-53AF8C8A7E9D physicalNoteid: BD3D9809-0917-4D2C-B999-08E504F2097E role: reference noteid: DC67EE32-B228-4DB7-AB90-4F651AAC1B28 contentIds: - blank-1-image-0 position: x: 82.5 'y': 143.2 mapBacked: false kind: inserted closed: false - height: 320 physicalNoteResolved: true blankId: blank-bcd58ff91463 sourcePage: 1 segments: - bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 documentPage: 65795 blankPage: 65797 notes: - topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 hostNoteid: 1049A587-60FB-47B6-90D1-A9F16141CFA0 physicalNoteid: F3DAC119-E77D-45E3-B710-EA2EC973F422 role: physical noteid: F3DAC119-E77D-45E3-B710-EA2EC973F422 contentIds: - blank-2-image-0 position: x: 82.5 'y': 143.2 mapBacked: false kind: inserted closed: false bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 parts: - blankId: blank-981b1f9e61b4 index: 0 noteid: 509CC486-1B22-4BD5-8CFF-FC0CC22FF72E excerpt: false mimeType: image/png width: 1120 contentPath: >- /documents/ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07/pages/1/content/blank-0-image-0 topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 source: blank contentId: blank-0-image-0 height: 292 kind: blank_image composite: true renderable: true - blankId: blank-020048f2077e index: 1 noteid: BD3D9809-0917-4D2C-B999-08E504F2097E excerpt: false mimeType: image/png width: 1120 contentPath: >- /documents/ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07/pages/1/content/blank-1-image-0 topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 source: blank contentId: blank-1-image-0 height: 467 kind: blank_image composite: true renderable: true - blankId: blank-bcd58ff91463 index: 2 noteid: F3DAC119-E77D-45E3-B710-EA2EC973F422 excerpt: false mimeType: image/png width: 1120 contentPath: >- /documents/ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07/pages/1/content/blank-2-image-0 topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 source: blank contentId: blank-2-image-0 height: 467 kind: blank_image composite: true renderable: true mapSources: - book_config page: 1 bridgeApiVersion: '0.91' x-codeSamples: - lang: javascript label: 获取页面注释面 source: > const r = await mn.api('/documents/' + bookmd5 + '/pages/' + page + '/parts'); const first = r.parts[0]; // 取图用下一条接口，把 contentId 带过去 mn.log(first.contentId, r.mapBacked); components: parameters: Bookmd5: name: bookmd5 in: path required: true description: >- 文档的内容标识。取自 `GET /study-sets/{topicid}/documents` 响应里各项的 `bookmd5`、`GET /ui-state` 的 `state.bookmd5`，或 `GET /search?scope=documents`。 schema: type: string PageIndex: name: index in: path required: true description: PDF 页序，文档第一页为 1。 schema: type: integer minimum: 1 StudySetQuery: name: studySet in: query required: false description: >- 限定某个学习集。在 `GET /documents/{bookmd5}/pages/{index}/parts` 上只调整旧留白映射的解析优先级，不按学习集过滤。 schema: type: string schemas: DocumentPartsResponse: type: object properties: parts: type: array description: 该页上可以取图的项。 items: type: object properties: contentId: type: string contentPath: type: string topicid: type: string kind: type: string blanks: type: array description: 逻辑留白。一个选择留白可能包含多张图，取用时保持成一组。 items: type: object properties: contentIds: type: array items: type: string segments: type: array description: 该组图在留白里的段号。 items: type: number mapBacked: type: - boolean - integer description: >- 为 `false` 表示留白映射丢失，该清单是从物理留白恢复出来的。较早的 MarginNote 在该项上给 `1` 与 `0`，按真值判断。 topicFilteringApplied: type: boolean description: 固定为 `false`。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.