文档、媒体与导出

示例中的SkyNoteEditor和parseCanvasDocument从@skynote/editor导入；以已经创建的Editor实例作为参数。纯JSON手动保存的完整流程见保存与恢复教程。

文档读取

documentName是低成本名称查询。exportDocument(): CanvasDocument返回当前文档的完整副本，可用于JSON序列化；它不包含媒体二进制、视口或完整历史。只想刷新名称时，不要导出整份文档。

校验与导入

方法	输入 / 返回	行为
`prepareDocumentImport(value)`	`unknown → ParseResult<DocumentAssetInspection>`	解析结构并检查资产引用，不替换当前文档
`importDocument(value, options?)`	`unknown → ParseResult<void>`	一步可撤销地替换内容，默认记录名“导入文档”
`restoreDocument(doc, options?)`	`CanvasDocument → ParseResult<void>`	已校验的本地恢复，清空原历史
`restoreRecovery(document, history, options?)`	两个`unknown → ParseResult<void>`	显式恢复完整检查点

ParseResult按ok区分成功和失败；失败时读取error，不要读取不存在的成功值。JSON语法错误需要在调用前捕获：

export function importJson(editor: SkyNoteEditor<HTMLElement>, text: string): { ok: boolean; message?: string } {
  let value: unknown;
  try {
    value = JSON.parse(text);
  } catch {
    return { ok: false, message: '不是有效JSON' };
  }
  const result = editor.importDocument(value);
  return result.ok ? { ok: true } : { ok: false, message: result.error };
}

importDocument的options.label指定历史记录名。默认拒绝检查到的媒体问题；宿主向用户说明具体问题并得到明确选择后，才使用allowAssetIssues:true接受残缺媒体。它不会绕过结构解析或事务校验。

本地恢复

export function restoreValidated(
  editor: SkyNoteEditor<HTMLElement>,
  value: unknown
): { ok: boolean; message?: string } {
  const parsed = parseCanvasDocument(value);
  if (!parsed.ok) return { ok: false, message: parsed.error };
  const restored = editor.restoreDocument(parsed.value, { initialView: 'fit-content' });
  return restored.ok ? { ok: true } : { ok: false, message: restored.error };
}

restoreDocument假定输入已经过parseCanvasDocument校验。成功后不保留之前的撤销历史，不能用它替代用户期望可撤销的“导入文件”。options.initialView可为本次恢复选择打开策略；未挂载时会等容器就绪后再应用。

普通恢复不代表跨文档的完整灾备。restoreRecovery需要成对的文档与历史证据，不能把任意旧历史拼到新的文档上。

图片任务

export async function addImage(editor: SkyNoteEditor<HTMLElement>, file: File): Promise<string | undefined> {
  const result = await editor.insertImage(file, editor.viewportCenter);
  if (result.status === 'succeeded') return result.value;
  if (result.status === 'failed') console.error('图片任务失败', result.failure);
  return undefined;
}

插入和替换需要宿主配置AssetAdapter。任务返回值按状态判断：

状态	载荷 / 处理
`succeeded`	`value`：插入返回节点ID，替换返回目标ID集合
`cancelled`	`reason`：过期、取消等原因，不应显示为上传成功
`failed`	`failure`：具体失败事实，由宿主展示或记录

replaceImage(ids, file)保留节点几何、位置与样式。getImageLoadState(id)查询渲染加载状态；retryImages(ids)返回实际接受重试的节点ID。任务成功与渲染器最终解码成功是两个不同阶段。

适配器的上传/解析应响应AbortSignal；临时对象URL由适配器释放。节点通过assetId引用文档资产表，不把Base64或Blob写入节点字段。

图片导出

先检查canExportPng以及getPngExportInfo(options?)，再调用exportPng(options?)。scope缺省为全部内容，可选择当前选区；scale影响输出尺寸。实际参数与返回签名见完整索引。

getPngExportInfo会在空范围或尺寸不合法时抛错。当前倍率范围为0.25～4，单边最多8192像素、总量最多16,777,216像素；结果包含bounds、width和height。

exportPng成功返回{data: Uint8Array, mimeType, width, height}，失败通过Promise拒绝反馈，调用方使用try/catch。background可选transparent/canvas，signal支持取消；未挂载、能力不支持或已有导出任务时会拒绝。不修改视口、选区或历史。跨域图片是否可导出还取决于宿主资源服务。

文档、媒体与导出 ​

文档读取 ​

校验与导入 ​

本地恢复 ​

图片任务 ​