weboffice-js-sdk 2.0.2 → 2.0.3-beta.5

package/README.md

@@ -0,0 +1,493 @@
+# 石墨 JS SDK
+
+此 SDK 对应石墨 SDK 2.0 产品，目的是让石墨 SDK 2.0 产品的客户能够快速接入 SDK，并和石墨文档套件进行前端交互。
+
+关于石墨 SDK 2.0 产品的详细内容请移步 [SDK 2.0 官网](https://platform.shimo.im/v2/)。
+
+_注：此 SDK 无法用于石墨文档官网产品 (即 shimo.im) 。_
+
+## [文档详情](https://shimo-open.github.io/shimo-js-sdk/#/)
+
+### 安装
+
+```shell
+# 通过 npm
+npm install --save shimo-js-sdk
+
+# 通过 yarn
+yarn add shimo-js-sdk
+```
+
+### 初始化 iframe
+
+```js
+const { connect } = require('shimo-js-sdk')
+
+connect({
+  fileId: '您系统中的 file id',
+  endpoint: '石墨服务的地址',
+  signature: '用您的 app id 和 secret 签发的签名',
+  token: '用于您系统识别用户请求的 token',
+  container: document.querySelector('#shimo-file'), // iframe 挂载的目标容器元素
+  lang: 'en' // 未指定此参数时，使用浏览器默认语言
+  userUuid：'您的uuid', // 仅在v2版本回调时需要传入(co-1.3+支持)
+}).then((shimoSDK) => {
+  // ...
+})
+```
+
+参数说明请参考 [docs/interfaces/connectoptions.md](docs/interfaces/ConnectOptions.md)。
+
+返回值：
+
+```
+Promise<ShimoSDK>
+```
+
+**使用传统的 `<script>` 的方式加载：**
+
+1. 使用 [npm view](https://docs.npmjs.com/cli/v7/commands/npm-view) 和 [npm pack](https://docs.npmjs.com/cli/v7/commands/npm-pack) 下载代码包 (`.tgz` 格式)
+2. 将 `.tgz` 解压缩后的 `dist` 目录下的文件放置到您托管静态资源的空间，然后使用 `<script>` 引入 `index.js` 资源
+3. 通过 `window.ShimoJSSDK` 对象获取对应的方法
+
+```js
+const { connect, FileType } = window.ShimoJSSDK
+// 等价于
+const { connect, FileType } = require('shimo-js-sdk')
+```
+
+#### 使用示例
+
+```js
+const { connect } = require('shimo-js-sdk')
+
+const fileId = '1234'
+const uuid = 'youruuid'
+
+// 从您的后端服务获取用于石墨鉴权的签名和 token
+const { signature, token } = await getCredentialsFromServer()
+
+connect({
+  fileId: fileId,
+  endpoint: 'https://shimo-sdk-endpoint/', // endpoint 因环境而异，请联系技术支持
+  signature: signature,
+  token: token,
+  container: document.querySelector('#shimo-file'), // iframe 挂载的目标容器元素
+  userUuid: uuid
+}).then((sdk) => {
+  // sdk 即为 ShimoSDK 实例
+})
+```
+
+调用 `connect()` 时，会以传入参数为基础，初始化一个 `<iframe>` 并插入 `container` 对应的元素中。
+
+返回的 `sdk` 为 `ShimoSDK` 实例，用于和 SDK、编辑器交互。
+
+### SDK 和编辑器实例
+
+石墨 JS SDK 共有两种实例用于和 JS SDK 交互：
+
+- `ShimoSDK` 由 `connect()` 返回，处理初始化编辑器和编辑器交互的工作
+- `Editor` 文档编辑器，直接和文档内容交互。**`Editor` 所有接口均返回 Promise**
+
+两者之间各有独立的方法和事件，具体请查看 `docs` 目录的文档。
+
+获取编辑器实例和与其交互：
+
+```js
+const { FileType } = require('shimo-js-sdk')
+
+// 获取编辑器实例
+const editor = sdk.getEditor()
+
+// 调用通用事件
+editor.on('saveStatusChanged', (payload) => {
+  console.log(payload.status)
+})
+
+// 调用特定类型文档的方法
+if (sdk.fileType === FileType.Document) {
+  editor.showHistory()
+}
+```
+
+若为 `TypeScript`，可使用 `Generic`：
+
+```typescript
+const { Document } = require('shimo-js-sdk')
+
+const editor = sdk.getEditor<Document.Editor>()
+editor.on('saveStatusChanged', (payload) => {
+  console.log(payload.status)
+})
+
+await editor.showHistory()
+```
+
+### HeaderBars 使用说明
+
+`sdk.headerBars` 提供显式 facade，不依赖 editor Proxy 路径猜测能力。
+
+```ts
+const sdk = await connect(options)
+
+// 顶栏显示状态（属性读写）
+sdk.headerBars.visible = false
+await sdk.headerBars.setVisible(true)
+
+// 命令增删改查
+await sdk.headerBars.addCommand(
+  { id: 'custom-export', section: 'more' },
+  'download'
+)
+const command = sdk.headerBars.getCommand('custom-export')
+
+// 命令状态（属性读写）
+command.visible = true
+command.disabled = false
+
+// 外层覆盖命令点击回调（优先于 iframe 默认回调）
+command.onCommandClick = async () => {
+  console.log('custom-export clicked')
+}
+```
+
+### 协作者模块使用说明
+
+当 iframe 套件开启协作者能力后（依赖 `ENABLE_SDK_COLLABORATORS_MODULE` 开关），shimo-js-sdk 使用方可按以下方式接入：
+
+1. **监听 `collaboratorsChanged`**
+
+```ts
+const sdk = await connect(options)
+const editor = sdk.getEditor()
+
+editor.on('collaboratorsChanged', (payload) => {
+  // payload.type: 'snapshot' | 'enter' | 'leave'
+  // payload.collaborators: 协作者全量列表
+  renderCollaborators(payload)
+
+  if (payload.type === 'enter') {
+    console.log('新协作者进入:', payload.enterUsers)
+  } else if (payload.type === 'leave') {
+    console.log('协作者离开:', payload.leaveUsers)
+  }
+})
+```
+
+3. **主动获取协作者列表**
+
+```ts
+const collaborators = editor.getCollaborators()
+renderCollaborators({ type: 'snapshot', collaborators })
+```
+
+4. **调试提示**
+   - 未收到事件时，检查 iframe 内的 window 对象是否有 `window.__RUNTIME_ENV__.ENABLE_SDK_COLLABORATORS_MODULE` 属性且为 true。
+   - 可在 iframe 页面 DevTools 中查看 `collaboratorsChanged` 是否触发，或观察 WebSocket `COLLABROOM` 消息。
+
+### 「系统已禁止编辑」确认回调
+
+当 iframe 内因为 `STATUS_FORBIDDEN` 弹出“系统已禁止编辑”提示后，用户点击确认按钮，会额外派发一个 `editForbiddenConfirmed` 编辑器事件：
+
+```ts
+editor.on('editForbiddenConfirmed', ({ reason }) => {
+  if (reason === 'STATUS_FORBIDDEN') {
+    // 执行 iframe 外层自己的确认回调
+  }
+})
+```
+
+### `signature` 和 `token`
+
+- `signature` 为石墨区分请求来源，并实现数据隔离的基础
+- `token` 为您用于识别回调请求来源、是否合法的依据
+
+具体说明请查阅在线文档：[https://platform.shimo.im/v2/docs/concepts/](https://platform.shimo.im/v2/docs/concepts/)。
+
+由于 `signature` 和 `token` 有过期时间，一般也不建议设置过长的时间，但为了减少因过期导致的用户体验问题，`ShimoSDK` 提供 `setCredentials({ signature, token })` 方法用于动态更新。
+
+```js
+/**
+ * 从您的后端服务获取用于石墨鉴权的签名和 token
+ * @deprecated
+*/
+let { signature, token, expires } = await getCredentialsFromServer()
+
+const shimoSDK = await connect({ ... })
+
+setInterval(
+  () => {
+    // 建议过期时间为7天
+    // 当剩余时间不到3.5天就过期时进行更新
+    if (expires - Date.now() < 1000 * 3600 * 24 * 3.5) {
+      const resp = await getCredentialsFromServer()
+      await shimoSDK.setCredentials({
+        signature: resp.signature,
+        token: resp.token
+      })
+      expires = resp.expires
+    }
+  },
+  60 * 1000
+)
+// 以上为旧版本更新鉴权方式，新版本（v1.2.23+）请参照如下方式进行更新
+const shimoSDK = await connect({
+  signature: '[your signature]',
+  token: '[your token]',
+  // 更新鉴权的时间间隔，单位为毫秒
+  // 若过期时间为7天，则建议设置为1000 * 3600 * 24 * 3.5 （3.5天）
+  refreshCredentialsInterval: 1000 * 3600 * 24 * 3.5,
+  getCredentials: async () => {
+    const res = await getCredentialsFromServer()
+    return {
+      signature: res.signature,
+      token: res.token,
+    }
+  }
+})
+```
+
+### 如何处理 URL
+
+由于石墨 SDK 以 `iframe` 的形式挂载到当前页面，`iframe.src` 对应的 URL 并不适合用于分享，而且在一些功能上，比如 @ 文件，需要用到您系统中对应的 URL 格式，比如 `https://your-domain/files/:id`。
+
+为了解决这个问题，石墨 SDK 引入 `generateUrl()` 和 `openLink()` 方法：
+
+```js
+import { UrlSharingType } from 'shimo-js-sdk'
+
+const shimoSDK = await connect({
+  ...,
+
+  generateUrl(fileId: string, info: GenerateUrlInfo): string {
+    if (info?.sharingType === UrlSharingType.FormFill) {
+      return `https://your-domain/files/${fileId}/fill-form`
+    }
+
+    if (info?.sharingText) {
+      return `https://your-domain/files/${fileId} ${info.sharingText}`
+    }
+
+    return `https://your-domain/files/${fileId}`
+  },
+
+  openLink(url: string): void {
+    // 以 React Router 为例
+
+    // 假设 url 是 'https://your-domain/files/1'，在当前页跳转，其他则新窗口打开
+    if (url.includes('your-domain/files/')) {
+      const u = new URL(url)
+      history.push(u.pathname)
+    } else {
+      window.open(url)
+    }
+  },
+
+  // 从当前 url 中解析出文件 id 并返回
+  // 假设 url 是 'https://your-domain/files/123'，则返回 { fileId: '123' }
+  getFileInfoFromUrl(url: string): {fileId:string} {
+    let fromId
+    const urlWithoutParams = url.split('?')[0]
+    let splitPath = urlWithoutParams.split('/')
+    fromId = splitPath[splitPath.length - 1]
+    return Promise.resolve({
+        fileId: fromId
+    })
+  }
+})
+```
+
+#### URL 的上下文信息
+
+为了在 URL 上传递上下文信息，比如 URL 指向的段落、单元格，在调用 `generateUrl()` 生成 URL 后，会在 URL 后附加一个 `smParams=PARAMS` 的参数：
+
+```
+https://your-domain/files/:id?smParams=PARAMS
+```
+
+**如无特殊需要，请保留该参数。**
+
+默认情况下，调用 `connect()` 会从当前 `location.search` 中提取 `smParams`，如果遇到需要自定义参数的场合，可以通过 `connect({ smParams: PARAMS })` 参数修改。
+
+`smParams` 为经过 [base62](https://github.com/felipecarrillo100/base62str) 序列化后的 `Record<string, unknown>` 对象。
+
+**在传入 `smParams` 参数时，将不会从 `location.search` 中获取数据**，如果想保留原有信息，可以这样传递：
+
+```js
+const paramsList: Array<string | Record<string, unknown>>
+
+const originParams = new URLSearchParams(location.search).get('smParams')
+// 保留原来的上下文信息
+if (originParams) {
+  paramsList.push(originParams)
+}
+
+// 添加自定义的上下文信息
+paramsList.push({
+  myVar: 'myVal'
+})
+
+connect({
+  smParams: paramsList
+})
+```
+
+#### URL Info
+
+`generateUrl(fileId, info)` 中的 `info` 是用于对 URL 进行一些特殊处理的。
+
+`sharingText`：石墨默认提供的分享文本：比如
+
+- `https://your-domain/files/1 xxx 邀请您参与《标题》协作，请复制粘贴后在浏览器打开`
+- `https://your-domain/files/1/fill-form xxx 邀请您填写《标题》表单，……`
+
+`sharingType`：表示此次 `generateUrl()` 对应的行为类型，比如：
+
+- `UrlSharingType.Form` 代表一般的打开编辑表单的行为
+- `UrlSharingType.FormPreview` 代表打开预览表单页面的行为
+- `UrlSharingType.FormFill` 代表打开填写表单页面的行为
+
+您需要根据具体类型，生成不同的 URL，比如：
+
+- `UrlSharingType.Form`、`UrlSharingType.FormPreview` 等一般需要进行鉴权，因此可以用 `/files/${fileId}`
+- `UrlSharingType.FormFill` 填写表单一般不需要登录鉴权，因此可以用另一个独立的路由，比如 `/files/${fileId}/fill-form`
+
+在实际操作中，您可以根据 `sharingType` 按需为 URL 添加分享文本。**若添加了分享文本，则需要您在 `parseUrl()` 中对 URL 进行处理**，比如：
+
+```js
+// url: 'https://your-domain/files/1 xxx 邀请您参与《标题》协作，请复制粘贴后在浏览器打开'
+parseUrl(url: string) {
+  return url.split(' ')[0] // 返回 'https://your-domain/files/1
+}
+```
+
+### 打开表格编辑器时展示指定工作表 (Sheet)
+
+**使用本章节用法时，请先了解 [URL 的上下文信息](#url-的上下文信息) 章节**。
+
+此用法适用于表格中存在多个工作表 (Sheet) ，希望在打开编辑器时，直接展示某个工作表格而非默认的第一个工作表。如用于希望直接分享表格的某个工作表链接给其他协作者，他人在打开后可直接查看指定的工作表。
+
+首先通过 `docs/interfaces/Spreadsheet.Editor.md` 表格的编辑器 `getActiveSheetId` 方法获取当前处于激活状态的工作表 ID ，此 ID 可用于追加在接入方自身的 URL 上作为参数。
+
+如通过 `URL QueryString` 方式传递：`https://your-domain.com/files/abcdefg?sheetId=XXXXX&smParams=XXXXXXXXXXXXXXXXXXXXXX`
+
+`sheetId` 仅为参数名举例，接入方可结合自身业务命名。
+
+```js
+const paramsList: Array<string | Record<string, unknown>>
+const queryParams = new URLSearchParams(location.search)
+
+const originParams = queryParams.get('smParams')
+const sheetId = queryParams.get('sheetId')
+
+// 保留原来的上下文信息
+if (originParams) {
+  paramsList.push(originParams)
+}
+// paramsList
+// => [originParamsStringValue]
+
+// 添加自定义的上下文信息
+paramsList.push({ sheetId: '通过 QueryString 中获取的 sheetId' })
+// paramsList
+// => [originParamsStringValue, {"sheetId": "XXXXX"}]
+
+connect({
+  smParams: paramsList
+})
+```
+
+### 打开编辑器时，定位至在正文中 at 某用户或评论的位置
+
+支持类型：
+
+- `轻文档` - `document`
+- `表格` - `spreadsheet`
+- `传统文档` - `documentPro`
+
+**使用本章节用法时，请先了解 [URL 的上下文信息](#url-的上下文信息) 章节**。
+
+此用法适用于:
+
+- 定位@用户： 在接入方系统的文件中 at 了指定用户，在回调接口中收到 `石墨 SDK 事件` 中的 `mention_at` 类型事件，并获取 `mentionAt.guid` 字段作为参数拼接至接入方的访问链接上，在接入方系统通知对应用户时，推送的链接可直接打开对应文件并定位至当前用户被 at 的正文位置，以便于查看对应位置相关内容。
+- 新增评论： 在接入方系统的文件中新增了评论，在回调接口中收到 `石墨 SDK 事件` 中的 `comment` 类型事件，并获取 `comment.selectionGuid` 字段作为参数拼接至接入方的访问链接上，在接入方系统通知对应用户时，推送的链接可直接打开对应文件并定位至当前新增的评论位置，以便于查看对应位置相关内容。
+
+如通过 `URL QueryString` 方式传递：`https://your-domain.com/files/abcdefg?mentionId=XXXXX&smParams=XXXXXXXXXXXXXXXXXXXXXX`
+
+`mentionId` 仅为参数名举例，接入方可结合自身业务命名。
+
+```js
+const paramsList: Array<string | Record<string, unknown>>
+const queryParams = new URLSearchParams(location.search)
+
+const originParams = queryParams.get('smParams')
+const mentionId = queryParams.get('mentionId')
+
+// 保留原来的上下文信息
+if (originParams) {
+  paramsList.push(originParams)
+}
+// paramsList
+// => [originParamsStringValue]
+
+// 添加自定义的上下文信息
+paramsList.push({ hash: '通过 QueryString 中获取的 mentionId' })
+// paramsList
+// => [originParamsStringValue, {"hash": "XXXXX"}]
+
+connect({
+  smParams: paramsList
+})
+```
+
+### 覆盖编辑器内置 toast 文案
+
+支持的套件类型：
+
+- `表单` - `form`
+- `传统文档` - `documentPro`
+- `专业幻灯片` - `presentation`
+- `表格` - `spreadsheet`
+- `应用表格` - `table`
+
+仅对支持 `ui` 配置的套件生效。
+
+当前已文档化支持字段：
+
+- `ui.toast.tips.edit.noPermission`
+
+```typescript
+import { connect } from 'shimo-js-sdk'
+
+const shimoSDK = await connect({
+  ui: {
+    toast: {
+      tips: {
+        edit: {
+          noPermission: '你没有编辑权限'
+        }
+      }
+    }
+  }
+})
+```
+
+### 显示自定义 toast
+
+支持的套件类型：
+
+- `表格` - `spreadsheet`
+
+此方法可显示接入方自定义 toast，具体用法如下
+
+```typescript
+import { connect, ShowToastOptions } from 'shimo-js-sdk'
+
+const shimoSDK = await connect({
+  // 初始化sdk时传了该方法将会拦截编辑器内的toast
+  showToast: (options: ShowToastOptions) => {
+    // show your toast
+  }
+})
+```

package/{OfficeSDK.d.ts → dist/OfficeSDK.d.ts}

@@ -6,7 +6,42 @@ import 'proxy-polyfill';
 import { TinyEmitter } from 'tiny-emitter';
 import { ContainerMethod, ContainerRect, DisableMentionCards, FileType, InvokeMethod, MouseMovePayload, ReadyState, PerformanceEntry, DeviceMode, GenerateUrlHandler, APIAdaptor, RequestContext, ShowToastOptions, Credentials } from 'weboffice-js-sdk-shared';
 import { Document, DocumentPro, Presentation, Spreadsheet, Table, Form, Flowchart } from '.';
+import { EmptyPageOptions } from './types/EmptyPage';
 import { BaseEditor } from './types/BaseEditor';
+export interface HeaderBarsCommandDefinition {
+    id: string;
+    section?: string;
+    order?: number;
+    label?: string;
+    visible?: boolean;
+    disabled?: boolean;
+    editable?: boolean;
+    type?: 'action' | 'structural';
+    renderType?: string;
+    src?: string;
+    onClick?: () => void | Promise<void>;
+}
+export interface HeaderBarsCommandState extends HeaderBarsCommandDefinition {
+    type: 'action' | 'structural';
+}
+export interface HeaderBarsCommandRef {
+    readonly id: string;
+    visible: boolean;
+    disabled: boolean;
+    editable?: boolean;
+    onCommandClick?: () => void | Promise<void>;
+    getState: () => HeaderBarsCommandState | undefined;
+}
+export interface HeaderBarsFacade {
+    visible: boolean;
+    getVisible: () => Promise<boolean>;
+    setVisible: (visible: boolean) => Promise<void>;
+    addCommand: (command: HeaderBarsCommandDefinition, posCommand: string, pos?: 'before' | 'after') => Promise<boolean>;
+    getCommand: (id: string) => HeaderBarsCommandRef;
+    listViewCommands: () => Promise<HeaderBarsCommandState[]>;
+    setTitleDraft: (title: string) => Promise<void>;
+    confirmTitleChange: (title: string) => Promise<void>;
+}
 export declare const MessageEvent: typeof InvokeMethod;
 export declare class OfficeSDK extends TinyEmitter {
     /**
@@ -50,9 +85,9 @@ export declare class OfficeSDK extends TinyEmitter {
      * @deprecated - 用 `sdk.getEditor<T>()` 替代
      */
     flowchart?: Flowchart.Editor;
+    readonly headerBars: HeaderBarsFacade;
     private _fileType;
     private readonly messageHandler;
-    private loadingOverlay?;
     /**
      * 内部 event emitter，比如用来中转 editor 事件
      */
@@ -75,7 +110,18 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     private readonly endpoint;
     private readonly sameOrigin;
+    private headerBarsVisible;
+    private readonly headerBarsCommands;
+    private readonly headerBarsCommandOverrides;
+    private readonly headerBarsCommandRefs;
     private readonly onViewportResize;
+    /**
+     * 归一化后的缺省页配置，构造时一次算完，后续仅读取。
+     */
+    private readonly normalizedEmptyPage;
+    private readonly preloadAckTimeoutMs;
+    private readonly preloadDoneTimeoutMs;
+    private readonly preloadReadyTimeoutMs;
     constructor(options: OfficeSDKOptions);
     get fileType(): FileType;
     get readyState(): ReadyState;
@@ -110,15 +156,20 @@ export declare class OfficeSDK extends TinyEmitter {
      * 比如受浏览器限制无法发出 postMessage() 时，Promise 将会一直 pending。
      */
     init(): Promise<void>;
-    private setupLoadingOverlay;
-    private removeLoadingOverlay;
-    private ensureLoadingStyle;
     private initIframe;
+    private runPreloadHandshake;
     private initChannel;
     /**
      * 初始化处理编辑器需要容器返回数据的方法
      */
     private bindContainerMethodHandlers;
+    private initHeaderBarsFacade;
+    private invokeHeaderBars;
+    private syncHeaderBarsCommands;
+    private applyHeaderBarsChanged;
+    private syncHeaderBarsVisible;
+    private setHeaderBarsVisible;
+    private getHeaderBarsCommandRef;
     private initEditor;
     private shouldHandleMessage;
     private getContainerRect;
@@ -188,11 +239,25 @@ export declare enum Event {
      * OfficeSDK 状态变化事件
      */
     ReadyState = "readyState",
+    /**
+     * 编辑器真正完成"首屏渲染"的信号。
+     *
+     * 由 iframe 内编辑器在自身渲染稳定后通过 channel 发送，SDK 侧转发为本事件。
+     * 宿主可按需监听它来区分 SDK Ready 与编辑器视觉首屏完成。
+     */
+    EditorRendered = "editorRendered",
     /**
      * 编辑器事件
      */
     EditorEvent = "editorEvent"
 }
+/**
+ * iframe 内侧用来上报"编辑器已完成首屏渲染"的 channel 事件名。
+ *
+ * 与 `InvokeMethod.ReadyState` 的枚举值保持在同一命名空间，但不入 shared 包，
+ * 以免跨端版本耦合。iframe 侧约定写字符串即可。
+ */
+export declare const EDITOR_RENDERED_EVENT = "editorRendered";
 export interface Message {
     uuid?: string;
     event: string;
@@ -222,6 +287,20 @@ export type EventCallback = (...args: any[]) => any;
 export interface SDKToastOptions {
     [key: string]: string | SDKToastOptions | undefined;
 }
+/**
+ * iframe 内置加载页配置，只支持可序列化字段。
+ */
+export interface LoadingOptions {
+    /**
+     * 自定义加载页 Logo。传字符串时作为图片 URL / dataURL 使用；
+     * 传 false 时隐藏 Logo；不传时使用 iframe 内默认石墨 Logo。
+     */
+    logo?: string | false;
+    /**
+     * 自定义加载页提示文案。不传时使用 iframe 内默认文案。
+     */
+    tip?: string;
+}
 /**
  * OfficeSDK 初始化参数
  */
@@ -256,6 +335,10 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
     params?: {
         [key: string]: string;
     };
+    /**
+     * 当前打开模式。`preview` 用于预览态，其余场景默认按 `edit` 处理。
+     */
+    mode?: 'edit' | 'preview';
     /**
      * 石墨 SDK URL 参数 url?smParams={params}，用于传递石墨 SDK 内部需要的参数。
      */
@@ -311,14 +394,24 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
      * 是否禁用默认的签名组件，以支持自定义签名组件。受版本限制，部分版本的特定类型文档才支持。
      */
     disableSignatureComponent?: boolean;
+    /**
+     * 控制 headerbar 组件是否展示，false 表示隐藏。
+     */
+    headerBarsVisible?: boolean;
     /**
      * 是否显示内置的加载动画，只在静态资源加载到编辑器渲染这个阶段显示
      */
     showLoadingEffect?: boolean;
     /**
-     * 是否展示 SDK 默认的加载遮罩，覆盖 container，默认 false
+     * 是否启用 iframe 内置默认加载页，默认 false。
+     * 隐藏后接入方可自定义外部 loading。
      */
     showLoading?: boolean;
+    /**
+     * iframe 内置加载页配置。仅在 `showLoading === true`
+     * 或 `showLoadingEffect === true` 时透传给 iframe。
+     */
+    loadingOptions?: LoadingOptions;
     /**
      * 用于在编辑器发起 API 请求时，对请求参数进行修改的函数。详细用法见文档。
      */
@@ -335,4 +428,17 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
      * 加密后的用户id
      */
     userUuid?: string;
+    /**
+     * 缺省页（Empty Page）配置。
+     * - 不传或传 `true`：启用默认缺省页能力（有内置图片与默认文案，**无按钮**）
+     * - 传 `false`：完全关闭
+     * - 传对象：精细控制启用的 scene、token 过期策略，以及每个 scene 的
+     *   文案/按钮自定义（`overrides`）。默认不渲染任何按钮，宿主需要按钮时必须
+     *   在 `overrides[scene].primary/secondary` 里显式配置 label，点击统一触发
+     *   `emptyPageAction` 事件由宿主处理。
+     *
+     * 相关事件：`emptyPageShown` / `emptyPageAction` / `emptyPageHidden`。
+     * 详见 `./types/EmptyPage.ts`。
+     */
+    emptyPage?: boolean | EmptyPageOptions;
 }

package/{index.d.ts → dist/index.d.ts}

@@ -9,5 +9,7 @@ import { EventMap as BaseEventMap, BaseEditor } from './types/BaseEditor';
 export * from 'weboffice-js-sdk-shared';
 export * from './connect';
 export * from './OfficeSDK';
+export type { EmptyPageScene, EmptyPageOptions, EmptyPageActionOverride, EmptyPageContentOverride, NormalizedEmptyPageOptions, EmptyPageShownPayload, EmptyPageActionPayload, EmptyPageHiddenPayload, FileOpenFailedReason, TokenExpiredStrategy } from './types/EmptyPage';
+export { ALL_EMPTY_PAGE_SCENES, normalizeEmptyPageOptions } from './types/EmptyPage';
 export { BaseEditor, DocumentPro, Document, Spreadsheet, Presentation, Table, Form, Flowchart, BaseEventMap };
 export declare const START_PARAMS_FIELD = "smParams";