SDK 页面 API

2026-11-15

本篇是插件页面(浏览器端)的 API 参考:桥接、恢复状态、保存契约与文稿导航。

页面、状态与保存(浏览器端)

页面里 const sdk = await connect() 返回 BrowserAPI:

成员 签名 说明
context context(): Promise 取当前视图会话(含恢复状态、主题与明暗模式)
setState setState(state, dirty?) 写页面恢复状态,至多 64 KiB 的 JSON 检查点;只保留一个在途请求与最新快照,同批写入共享完成结果
onSave onSave(handler): () => void 注册保存处理器,返回退订函数
commands.invoke invoke(command, args?): Promise 调用本插件命令,返回宿主任务
tasks.list list(): Promise<摘要[]> 本插件任务摘要列表;不含 result,用 hasResult 表示有无结果,避免大结果挤满控制帧
tasks.get get(id): Promise 查询单个任务的完整状态与结果;只允许读取本插件任务
tasks.cancel cancel(id): Promise 请求取消任务,取消是协作式
appearance getColorScheme() / onDidChangeColorScheme(listener) 修订 2:同步读取宿主解析后的 light / dark 并订阅变化,宿主会在 HTML 首屏前设置 data-color-scheme
ready ready(): Promise 修订 2:首个可用画面(包括错误提示画面)渲染后调用,宿主结束加载提示;不要等 requestAnimationFrame

保存契约示例:

const view = await sdk.context()
let draft = view.state ?? { text: '' }

async function edited(text: string) {
  draft = { text }
  await sdk.setState(draft, true)
}

sdk.onSave(async () => {
  // 先把内容提交到自己的资源;失败要抛出错误,保持 dirty
  await persistDraft(draft)
  await sdk.setState(draft, false)
})
await sdk.ready()
  • 宿主保存 pluginId/viewId/instanceId/workspaceId/resource 关联,防止状态恢复到其他文件;
  • 主题由 view.theme 的 CSS 变量提供并动态更新;标题、返回与刷新控件由插件自行渲染(修订 3),宿主只提供容器与故障恢复;
  • 并发限制:浏览器至多 32 个在途 SDK 请求,宿主每页至多 16 个并发处理,超限返回 BACKPRESSURE;
  • 桥接超时或连接失效时向用户显示错误,不盲目重放副作用;
  • 关闭页面释放桥接与渲染进程,不停止后台任务;保存确认等待已提交状态,超时报 SAVE_TIMEOUT。

文稿导航(修订 3)

sdk.ui.openDocument({workspaceId, workspaceSession, documentId}) 在主窗口定位并打开指定文稿:原标签已关闭时重新打开;合集文稿定位到对应章节。导航固定绑定页面打开时的工作区会话,等待保存协调与主窗口确认;取消返回 NAVIGATION_CANCELLED,超时返回 NAVIGATION_TIMEOUT,工作区变化返回 WORKSPACE_CHANGED。插件自己决定跳转前是否先保存发布稿:先持久化并等待成功,再调用导航。