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。插件自己决定跳转前是否先保存发布稿:先持久化并等待成功,再调用导航。