外观
类型与枚举
本页汇总浏览器端 SDK（@atkonoffice/sdk）的接口签名、事件负载、比对 diff 结构，以及服务端打开模式等枚举。用法示例见通用控制与 Word。
浏览器端 SDK 是单一命名空间对象 atkonoffice，分两个使用面：
| 命名空间 | 运行位置 | 接口 |
|---|---|---|
atkonoffice.* | 业务网页（外层浏览器页） | config / open / on |
atkonoffice.session.* | 承载编辑器的页面（客户端内编辑页） | on / save / setSavePath / 工具条 / 拦截 / word |
绝大多数集成只用到
atkonoffice.*。session.*仅在用自带登录校验的业务页直接承载编辑器、需在编辑页内定制时才用到；客户端外普通浏览器里所有session动作都是无害 no-op。
atkonoffice.config(opts)
配置后台长跑所需的参数。返回 atkonoffice 自身，可链式。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
backendBase | string | 是 | 业务后端的源，拉起链端点所在处。open() 前必须配置。 |
launchPath | string | 否 | 拉起端点路径，默认 /atkonoffice/rpc/launch。 |
wsTicketPath | string | 否 | 事件通道重连 / 续订票据端点路径，默认 /atkonoffice/rpc/ws-ticket。 |
fetchImpl | typeof fetch | 否 | 自定义 fetch 实现（测试用）。 |
trustedFrameOrigins | string[] | 否 | 跨域 iframe 集成时的子帧源白名单；不设为宽松（向后兼容）。 |
atkonoffice.open(req)
拉起编辑窗口。返回 Promise<AtkonofficeOpenResult>。装机检测与引导由 open() 内部自管。
AtkonofficeOpenRequest
| 字段 | 类型 | 说明 |
|---|---|---|
pageApi | string | host-page 路由路径（相对路径，拼到后端源）。指向业务后端用 AtkonofficeCtrl 挂的路由；不填则客户端加载内建默认宿主页。 |
pageUrl | string | 业务页 URL（绝对）。让客户端导航到集成方自建的编辑承载页；省略则走内建默认宿主页。 |
params | Record<string, string> | 业务参数袋（值均字符串）。模型键：docId（打开 / 保存所指文档，默认宿主页模式下必填）、compareDocId（Word 比对目标，非空则进比对模式）、user（终端用户显示名）；其余为自定义业务键（如 bizType），全量透传进 pageApi 端点 query 用于分流。 |
headers | Record<string,string> | Array | 应用到数据面请求的额外 HTTP 头。 |
cookie | Record<string,string> | string | 序列化进 Cookie 头。 |
storage | Record<string,string> | 两用途：序列化进数据面请求头做后端鉴权；并注入编辑页 localStorage，让已有登录守卫在客户端内通过。 |
options | AtkonofficeWindowOptions | 弹窗几何。 |
AtkonofficeWindowOptions：width（默认 1280，200–9999）/ height（默认 960）/ modal（默认 false）。
打开模式不在这里传——由后端在
pageApi路由里用AtkonofficeOpenMode裁决；浏览器只透传params。
AtkonofficeOpenResult
| 字段 | 类型 | 说明 |
|---|---|---|
launchUrl | string | 已签发的拉起链。 |
downloadUrl | string | 文档取用 URL。 |
pairId | string | 本次拉起打开的订阅会合 id（不可得时为空串）。 |
wsUrl | string | 事件通道连接到的 WS 端点（不可得时为空串）。 |
atkonoffice.on(event, handler)
订阅文档生命周期与连接状态事件。链式返回 atkonoffice。
| 事件 | 负载 | 时机 |
|---|---|---|
documentOpened | AtkonofficeDocOpened | 文档打开完成（编辑会话已就绪）。 |
documentBeforeSave | AtkonofficeDocBeforeSave | 即将保存（通知式，不能取消保存）。 |
documentSaved | AtkonofficeDocSaved | 保存完成（业务闭环信号）。 |
shellClosed | AtkonofficeShellClosed | 编辑器窗口已不在（正常关闭 / 异常消失），本次编辑会话确定结束。 |
channelLost | AtkonofficeChannelLost | 本页与服务器的事件通道断开（每次失联只派发一次）。 |
channelRestored | AtkonofficeChannelRestored | 事件通道恢复、订阅已重建，回推继续送达。 |
error | AtkonofficeError | 发起打开之后的运行期异常（事件通道失败、打开命令未送达等），带稳定错误码——见错误对象。 |
事件负载
负载字段均可选，页面应对缺省容错（向前兼容）。
AtkonofficeDocSaved
| 字段 | 类型 | 说明 |
|---|---|---|
doc_id | string | 保存的文档 id（回显拉起时的 docId）。 |
ok | boolean | 是否成功；false 时带 message。 |
saved_at | number | 保存完成的 Unix 秒。 |
bytes_saved | number | 写入字节数（有上报时）。 |
version_no | number | 保存后的单调文档版本号（有上报时）。 |
message | string | ok=false 时的失败详情。 |
pair_id | string | 本次保存所属的会合 id。 |
saveTypes | string[] | 本次保存产出的产物 role 列表（恒为列表形态）：缺省单件保存回 ["source"]，声明了派生产物的保存回如 ["source","pdf"] 或纯 ["pdf"]。取代旧单值 saveType 字段。 |
AtkonofficeDocOpened：doc_id / opened_at（Unix 秒）/ pair_id。 AtkonofficeDocBeforeSave：doc_id / pair_id。
AtkonofficeShellClosed（shellClosed——编辑器窗口已不在，页面可据此复位「编辑中」状态）
| 字段 | 类型 | 说明 |
|---|---|---|
reason | string | "user_close" = 终端用户正常关闭编辑器窗口（即时送达）；"shell_gone" = 编辑器异常消失（进程崩溃 / 被强杀，或仅编辑器那条连接被单独掐断超过宽限期），由服务端在宽限期后代为通知。前向兼容字符串——后续可能追加取值，不要穷举 switch。 |
"shell_gone"有延迟：宽限期（默认约两分钟，由服务端shell-gone-grace-sec配置）+ 至多一个心跳周期；连接被静默掐断时还要再加一个空闲判死周期。宽限期届满前刷新页面会丢掉这条通知（刷新本来就意味着从头开始）。- 两格刻意不覆盖，设计页面时留意：① 编辑器连接短暂抖动——宽限期内自己接回来，什么都不发；反之掐断超过宽限期时编辑器可能其实还活着（服务端分不出两者，复位页面是刻意取舍）。② 终端用户整机断电 / 断网 / 休眠——编辑器与业务页在同一台机器上，那时本页连接一起断，走
channelLost/channelRestored那对事件，恢复后编辑会话一般还活着。不要拿这条通知去释放服务端侧的「正在编辑」锁——那一格等不到它。 - 与
channelLost的分工：shellClosed说「对面没了」（本页通道健康），channelLost说「本页通道断了」（编辑器可能好好的）。
AtkonofficeChannelLost（channelLost——本页事件通道断开；每次失联只派发一次，不随重试重复派发）
| 字段 | 类型 | 说明 |
|---|---|---|
reason | string | "unreachable" = 后端暂时不可达（重部署 / 断网），SDK 已转低频探测、恢复后有配对的 channelRestored；"rejected" = 服务端明说重连无济于事，不会有 channelRestored，只有重新打开文档能恢复。前向兼容字符串。 |
- 与
on('error')分层并存、不替代：同一时刻错误面也会派发对应错误（ws_backoff_exhausted/ws_gave_up），两层挑一层处理即可，别两层都接。这对事件是新集成的推荐层——它有配对的恢复信号，错误面没有（「恢复了」不是错误）。 - ⚠️ 一条例外，只订这对状态事件的页面必须额外盯一个错误码：「自动恢复期间放弃」（某轮探测连上了、随即被服务端永久拒绝）不会有第二条
channelLost、也不会有channelRestored——唯一的信号是错误面的ws_gave_up（terminal: true）。漏接它，页面会永久停在「正在自动恢复」。
AtkonofficeChannelRestored（channelRestored——通道恢复、订阅已重建）：当前无字段（状态信号，为可扩展声明为对象）。它只说明本页重新连上了服务器，不保证编辑会话还活着——编辑器可能已在中断期间被关闭。
错误对象 AtkonofficeError
浏览器端 SDK 自身产生的每一个错误——open() reject 出的、以及 on('error') 派发的——都带稳定的 code 与 category 字段。按 code / category 分流，不要匹配 message 文案：message 是给开发者读日志用的英文串，会随版本调整措辞；稳定的是 code。
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 逐失败出口可区分的稳定短标识（见下表），唯一适合编程分流的字段。 |
category | 'config' | 'launch' | 'channel' | 粗分三档兜底：config = 接入 / 宿主环境问题（重试无用）；launch = 拉起腿失败；channel = 运行期事件通道异常（多为瞬态）。 |
terminal | boolean（仅两条通道出口带） | ws_gave_up 上为 true（通道永久丢失，只有重新打开文档能恢复）；ws_backoff_exhausted 上为 false（已转低频探测，后端恢复后自愈）。其余错误没有此字段。 |
两个投递面互斥：发起阶段的失败由 open() reject（下表标 △ 的 7 条），其余经 on('error') 异步派发。其中 launch_open_frame_send_failed 是唯一一条在 open() 已成功返回之后才到达的 launch 类错误——看起来打开成功了，实际打开命令没送到客户端。
词表（按 category 分组；△ = open() reject）：
| code | 含义 |
|---|---|
| config —— 接入 / 宿主环境问题，重试无用 | |
backend_base_missing △ | open() 前没调 config({ backendBase })。 |
doc_id_missing △ | 不传 pageUrl 的打开方式下 params.docId 也没给——下载 / 保存都无锚。 |
fetch_unavailable △ | 宿主既无全局 fetch、config 也没注入 fetchImpl。 |
ws_unsupported | 宿主没有 WebSocket，事件通道开不起来（文档仍可正常编辑与保存，但收不到回推）。 |
ws_ticket_backend_missing | 通道续订时后端基址仍未配置。 |
ws_ticket_node_mismatch | 多实例部署下，本会话的续订请求被另一个实例受理——部署侧路由规则问题，见部署要求 · 多实例部署。 |
| launch —— 拉起腿 | |
launch_request_failed △ | 拉起请求根本没发出去：后端没起 / 断网 / 跨域被拦，或传入参数无法序列化。联调期最高频。 |
launch_http_error △ | 拉起端点返回非 2xx。 |
launch_response_not_json △ | 拉起端点 2xx 但响应不是 JSON——典型是网关 / 反代返了自己的 HTML 错误页。联调期高频。 |
launch_response_invalid △ | 响应是 JSON 但缺关键字段。 |
launch_open_frame_send_failed | 打开命令未能送达客户端（在 open() 成功返回之后异步到达）。 |
| channel —— 运行期事件通道 | |
ws_url_missing | 手里没有通道端点地址，无从连起。 |
ws_ticket_missing | 手里没有一次性接入凭据，无法订阅。 |
ws_connect_failed | WebSocket 构造即失败（地址非法 / 宿主拒绝）。 |
ws_error | 已建立的通道上报错（随后自动重连）。 |
headers_frame_send_failed | 会话级请求头未能送达（客户端将以无额外头打开）。 |
ws_no_pair_to_resume | 通道断了且已无可恢复的会话。 |
ws_backoff_exhausted | 快速重连耗尽、已转低频探测（非终态，terminal: false）：后端恢复后自动接上。宜提示「正在后台重试」，不要引导用户重开文档。 |
ws_gave_up | 服务端明确告知重连无济于事（终态，terminal: true）：只有重新打开文档能恢复。 |
ws_ticket_http_error | 通道续订端点返回非 2xx。 |
ws_ticket_response_invalid | 续订响应缺关键字段。 |
ws_ticket_refresh_failed | 续订请求本身失败（网络异常 / 响应非 JSON）。 |
三条使用纪律：
- 词表是开放的——后续版本会追加出口，
switch (err.code)必须保留default分支；宿主环境自身抛出的异常（如集成方替换过的 fetch 实现）仍可能是不带 code 的原生错误。 - 该词表与客户端失败提示上显示给终端用户的错误码是两套语义域，互不对齐、不可互相映射——前者面向业务页代码分流，后者面向用户报给管理员。
- 编辑页侧（
session.on('error')）当前没有任何会派发带 code 对象的错误出口，本表只覆盖业务页（atkonoffice.*）一侧。
分流示例见通用控制 · 生命周期事件回流。
atkonoffice.session.*
编辑承载页子命名空间。客户端外普通浏览器里所有动作均无害 no-op。
session.on(event, handler)
| 事件 | 负载 | 说明 |
|---|---|---|
documentSaved / documentOpened / documentBeforeSave | AtkonofficeSessionEvent | 文档生命周期事件。 |
controlReady | AtkonofficeSessionEvent | 控件就绪、session 动作可调（非「文档内容就绪」）。负载尽力而为，可能为空。 |
compareDiff | AtkonofficeCompareDiff | Word 比对的结构化 diff（仅编辑页内可拿，含原文，不出域）。 |
error | Error | 通道异常。编辑页侧当前没有带错误码的错误出口，负载按普通 Error 处理（错误码词表只覆盖业务页一侧）。 |
方法
| 方法 | 说明 |
|---|---|
save(opts?) | 触发保存，多产物保存的唯一入口。opts.savePath（相对路径，/ 起始，禁 ://）指定本次上传目标，客户端把它接在本次打开所用的后端地址（完整值，含反向代理 / 多实例部署带的路径前缀）之后；opts.formats（如 ['source','pdf']）声明本次产出哪些产物，客户端逐 role 生产后恰发一次原子 multipart POST（缺省 = 只存原格式 source，纯 ['pdf'] 合法；未知 role / 空数组整次保存失败）；其余字段随保存作表单字段 POST。formats 与 savePath 正交。不传 opts = 普通单件保存。 |
setSavePath(path) | 改后续所有保存（含 Office 原生保存按钮）的默认上传目标（有状态便利口）。跨信道无顺序保证时优先 save({ savePath })。 |
onBeforeSave(fn) | 注册「保存前」可阻断回调（返回 false / reject → 取消；true / undefined / 抛错 / 超时 → 放行）。链式。 |
onBeforeClose(fn) | 注册「关闭前」可阻断回调，语义同上。链式。 |
addCustomToolButton(caption, iconIndex, onClick) | 追加按钮。iconIndex：1..N 内置图标，0 / 省略 / 越界 = 纯文字。返回句柄（含 remove()）；客户端外返回 null。 |
setCustomToolbarVisible(visible) | 整体显隐自定义工具条。visible 非布尔抛 TypeError。链式。 |
showMessageBox(opts?) | 弹出原生提示 / 确认框（显示在文档之上、不被遮挡）。opts.type：info（默认）/ confirm / warning / error；opts.buttons：ok（默认）/ okCancel / yesNo / yesNoCancel；另有 title / text。返 Promise，永不 reject——resolve 出 { ok, button }，ok:true 时 button 为 ok / cancel / yes / no；客户端外 / 非法参数 / 保存进行中 → { ok:false }。用法见 通用控制 · 弹出提示与确认框。 |
onBeforeSave / onBeforeClose 的 fn 非函数时抛 TypeError。
session.word.*
Word 数据区域（命名的锁定填充位）子命名空间（异步返 Promise，仅 Word；客户端外 / 只读 / 失败 / 超时 → 无害降级）。数据区域内容终端用户不能手动改动或删除，只能经这些方法维护。用法见 Word · 数据区域。
| 方法 | 说明 |
|---|---|
fillDataRegion(name, value) | 编辑中即时把数据区域 name 的值改为 value。命中并改值成功 → true；文档无此名字 / 只读态 / 客户端外 / 失败 → false。 |
addDataRegion(name, caption?) | 光标处插 caption 占位并建锁定数据区域 name。resolve 是否成功。 |
deleteDataRegion(name) | 删除数据区域 name（不存在按宽松策略 no-op）。 |
locateDataRegion(name) | 定位 / 选中数据区域 name。 |
listDataRegions(prefix?) | 列已插入的数据区域名。prefix 省略默认按 AO_ 前缀过滤；显式空串 '' 返全部数据区域名。resolve string[]。 |
打开模式与文档族枚举
AtkonofficeOpenMode
传给 AtkonofficeCtrl.webOpen / open 的第二个参数：
| 常量 | 序号 | 适用 | 含义 |
|---|---|---|---|
NormalEdit | 2 | Word | 普通读写编辑 |
ReadOnly | 3 | Word | 只读查看 |
RevisionOnly | 0 | Word | 仅修订（track changes） |
CommentOnly | 6 | Word | 仅批注 |
XlsNormalEdit | 7 | Excel | 普通读写编辑 |
XlsReadOnly | 8 | Excel | 只读查看 |
XlsSubmitForm | 9 | Excel | 提交表单编辑 |
PptNormalEdit | 10 | PPT | 普通读写编辑 |
PptReadOnly | 11 | PPT | 只读查看 |
辅助：fromName("NormalEdit")（按名，大小写不敏感）/ fromOpenType(2)（按序号）/ getOpenType()。
DocFamily
webCreate 的文档族入参：
| 常量 | 新建类型 | 对应打开模式 |
|---|---|---|
WORD | 空白 .docx | NormalEdit |
EXCEL | 空白 .xlsx | XlsNormalEdit |
PPT | 空白 .pptx | PptNormalEdit |
辅助：getOpenMode() / getWireType()（word/excel/ppt）/ fromWireType("word")。
窗口外观枚举
AtkonofficeBorderStyle（setWindowBorder）：NONE（无边框无标题栏）/SIZABLE（标准可缩放边框，默认）。AtkonofficeTheme（setWindowTheme）：LIGHT/DARK/SYSTEM（跟随操作系统，默认）。
比对 diff
Word 比对的结构化 diff（session.on('compareDiff') 的负载 AtkonofficeCompareDiff），用法见 Word · 文档比对。
- 顶层：
docId/compareDocId/summary/revisions； summary（AtkonofficeCompareDiffSummary）：inserts/deletes/formatChanges/moves计数；revisions（AtkonofficeCompareDiffRevision[]）：逐条修订，含类型、落在哪侧、坐标区间与原文文本。
它含文档内容，只在编辑页内可订阅，不回流到外层浏览器页。
类型声明
SDK 随包发布 TypeScript 类型声明（@atkonoffice/sdk 的 types），主要接口：AtkonofficeConfig / AtkonofficeOpenRequest / AtkonofficeOpenResult / AtkonofficeWindowOptions / AtkonofficeDocSaved / AtkonofficeDocOpened / AtkonofficeDocBeforeSave / AtkonofficeSession / AtkonofficeSessionEvent / AtkonofficeSessionWord / AtkonofficeToolButtonHandle / AtkonofficeCompareDiff 及其子类型。