weboffice-js-sdk 2.0.4 → 2.0.5-beta.10

package/README.md

@@ -6,22 +6,22 @@
 
 _注：此 SDK 无法用于石墨文档官网产品 (即 shimo.im) 。_
 
-## [文档详情](https://shimo-open.github.io/shimo-js-sdk/#/)
+## [文档详情](https://shimo-open.github.io/weboffice-js-sdk/#/)
 
 ### 安装
 
 ```shell
 # 通过 npm
-npm install --save shimo-js-sdk
+npm install --save weboffice-js-sdk
 
 # 通过 yarn
-yarn add shimo-js-sdk
+yarn add weboffice-js-sdk
 ```
 
 ### 初始化 iframe
 
 ```js
-const { connect } = require('shimo-js-sdk')
+const { connect } = require('weboffice-js-sdk')
 
 connect({
   fileId: '您系统中的 file id',
@@ -29,13 +29,13 @@ connect({
   signature: '用您的 app id 和 secret 签发的签名',
   token: '用于您系统识别用户请求的 token',
   container: document.querySelector('#shimo-file'), // iframe 挂载的目标容器元素
-  lang: 'en', // 未指定此参数时，使用浏览器默认语言
+  lang: 'en-US', // 可选；未指定时使用编辑器默认语言
   disableAiEntry: true, // 可选，隐藏 iframe 内 AI 入口
   theme: {
     name: 'light'
   }, // 可选，透传给 iframe 内编辑器主题配置
   userUuid：'您的uuid' // 仅在v2版本回调时需要传入(co-1.3+支持)
-}).then((shimoSDK) => {
+}).then((officeSDK) => {
   // ...
 })
 ```
@@ -44,31 +44,31 @@ connect({
 
 其中：
 
-- `disableAiEntry` 为可选布尔值，透传到 iframe 内 `ShimoSDK` 的 AI 入口开关能力。
+- `disableAiEntry` 为可选布尔值，透传到 iframe 内 `OfficeSDK` 的 AI 入口开关能力。
 - `theme` 为可选主题对象，宿主侧仅负责透传；未传时 iframe 内仍使用默认主题配置。
 
 返回值：
 
 ```
-Promise<ShimoSDK>
+Promise<OfficeSDK>
 ```
 
 **使用传统的 `<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` 对象获取对应的方法
+3. 通过 `window.WebOfficeJSSDK` 对象获取对应的方法
 
 ```js
-const { connect, FileType } = window.ShimoJSSDK
+const { connect, FileType } = window.WebOfficeJSSDK
 // 等价于
-const { connect, FileType } = require('shimo-js-sdk')
+const { connect, FileType } = require('weboffice-js-sdk')
 ```
 
 #### 使用示例
 
 ```js
-const { connect } = require('shimo-js-sdk')
+const { connect } = require('weboffice-js-sdk')
 
 const fileId = '1234'
 const uuid = 'youruuid'
@@ -84,19 +84,19 @@ connect({
   container: document.querySelector('#shimo-file'), // iframe 挂载的目标容器元素
   userUuid: uuid
 }).then((sdk) => {
-  // sdk 即为 ShimoSDK 实例
+  // sdk 即为 OfficeSDK 实例
 })
 ```
 
 调用 `connect()` 时，会以传入参数为基础，初始化一个 `<iframe>` 并插入 `container` 对应的元素中。
 
-返回的 `sdk` 为 `ShimoSDK` 实例，用于和 SDK、编辑器交互。
+返回的 `sdk` 为 `OfficeSDK` 实例，用于和 SDK、编辑器交互。
 
 ### SDK 和编辑器实例
 
 石墨 JS SDK 共有两种实例用于和 JS SDK 交互：
 
-- `ShimoSDK` 由 `connect()` 返回，处理初始化编辑器和编辑器交互的工作
+- `OfficeSDK` 由 `connect()` 返回，处理初始化编辑器和编辑器交互的工作
 - `Editor` 文档编辑器，直接和文档内容交互。**`Editor` 所有接口均返回 Promise**
 
 两者之间各有独立的方法和事件，具体请查看 `docs` 目录的文档。
@@ -104,7 +104,7 @@ connect({
 获取编辑器实例和与其交互：
 
 ```js
-const { FileType } = require('shimo-js-sdk')
+const { FileType } = require('weboffice-js-sdk')
 
 // 获取编辑器实例
 const editor = sdk.getEditor()
@@ -123,7 +123,7 @@ if (sdk.fileType === FileType.Document) {
 若为 `TypeScript`，可使用 `Generic`：
 
 ```typescript
-const { Document } = require('shimo-js-sdk')
+const { Document } = require('weboffice-js-sdk')
 
 const editor = sdk.getEditor<Document.Editor>()
 editor.on('saveStatusChanged', (payload) => {
@@ -193,7 +193,7 @@ const sdk = await connect({
 
 ### 协作者模块使用说明
 
-当 iframe 套件开启协作者能力后（依赖 `ENABLE_SDK_COLLABORATORS_MODULE` 开关），shimo-js-sdk 使用方可按以下方式接入：
+当 iframe 套件开启协作者能力后（依赖 `ENABLE_SDK_COLLABORATORS_MODULE` 开关），weboffice-js-sdk 使用方可按以下方式接入：
 
 1. **监听 `collaboratorsChanged`**
 
@@ -237,56 +237,61 @@ editor.on('editForbiddenConfirmed', ({ reason }) => {
 })
 ```
 
-### `signature` 和 `token`
+### 凭证自动刷新（建议）
 
 - `signature` 为石墨区分请求来源，并实现数据隔离的基础
 - `token` 为您用于识别回调请求来源、是否合法的依据
 
-具体说明请查阅在线文档：[https://platform.shimo.im/v2/docs/concepts/](https://platform.shimo.im/v2/docs/concepts/)。
+由于 `signature` 和 `token` 有过期时间，建议在 `ConnectOptions` 中配置自动刷新，避免用户长时间编辑时因凭证失效而中断。
 
-由于 `signature` 和 `token` 有过期时间，一般也不建议设置过长的时间，但为了减少因过期导致的用户体验问题，`ShimoSDK` 提供 `setCredentials({ signature, token })` 方法用于动态更新。
+```typescript
+const { expireMs } = (await appService.getExpireConfig()).data
 
-```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,
-    }
-  }
-})
+const options: ConnectOptions = {
+  ...config,
+  // 在过期时长的 80% 处刷新，给网络重试等情况预留时间
+  refreshCredentialsInterval: Math.ceil(expireMs * 0.8),
+  getCredentials: async () => (await appService.getCredentials()).data
+}
+
+const officeSDK = await connect(options)
 ```
 
+示例配套接口：
+
+- `GET /api/apps/expire-config`：返回凭证过期时长，例如 `{ expireMs: 900000 }`
+- `GET /api/credentials`：返回新凭证，例如 `{ signature, token }`
+
+`getCredentials` 应从接入方后端获取最新凭证，并返回同时包含 `signature` 和 `token` 的对象。接口路径可按接入方系统实际情况调整。
+
+### 国际化：编辑器多语言（可选，co-1.8+）
+
+接入方可在调用 `connect` 时通过 `lang` 指定编辑器界面语言，传入对应语言码即可；用户选择“系统默认”时省略 `lang`（或传 `undefined`；纯 JavaScript 也可传 `null`）。
+
+```typescript
+const options: ConnectOptions = {
+  ...config,
+  ...(editorLang ? { lang: editorLang } : {}) // “系统默认”时不传 lang
+}
+
+const officeSDK = await connect(options)
+```
+
+1.8 版本编辑器支持以下 16 种语言：
+
+| 语言          | `lang` 语言码 | 语言             | `lang` 语言码 |
+| ------------- | ------------- | ---------------- | ------------- |
+| 简体中文      | `zh-CN`       | 繁體中文         | `zh-TW`       |
+| English       | `en-US`       | 日本語           | `ja-JP`       |
+| 한국어        | `ko-KR`       | Español          | `es-ES`       |
+| Português     | `pt-PT`       | Deutsch          | `de-DE`       |
+| Français      | `fr-FR`       | Italiano         | `it-IT`       |
+| Русский       | `ru-RU`       | Bahasa Indonesia | `id-ID`       |
+| Tiếng Việt    | `vi-VN`       | ไทย              | `th-TH`       |
+| Bahasa Melayu | `ms-MY`       | العربية          | `ar-SA`       |
+
+为兼容旧版写法，仍可传入 `en`、`ja`，SDK 会分别映射为 `en-US`、`ja-JP`。新接入建议使用表中的标准语言码。
+
 ### 如何处理 URL
 
 由于石墨 SDK 以 `iframe` 的形式挂载到当前页面，`iframe.src` 对应的 URL 并不适合用于分享，而且在一些功能上，比如 @ 文件，需要用到您系统中对应的 URL 格式，比如 `https://your-domain/files/:id`。
@@ -294,9 +299,9 @@ const shimoSDK = await connect({
 为了解决这个问题，石墨 SDK 引入 `generateUrl()` 和 `openLink()` 方法：
 
 ```js
-import { UrlSharingType } from 'shimo-js-sdk'
+import { UrlSharingType } from 'weboffice-js-sdk'
 
-const shimoSDK = await connect({
+const officeSDK = await connect({
   ...,
 
   generateUrl(fileId: string, info: GenerateUrlInfo): string {
@@ -497,9 +502,9 @@ connect({
 - `ui.toast.tips.edit.noPermission`
 
 ```typescript
-import { connect } from 'shimo-js-sdk'
+import { connect } from 'weboffice-js-sdk'
 
-const shimoSDK = await connect({
+const officeSDK = await connect({
   ui: {
     toast: {
       tips: {
@@ -521,9 +526,9 @@ const shimoSDK = await connect({
 此方法可显示接入方自定义 toast，具体用法如下
 
 ```typescript
-import { connect, ShowToastOptions } from 'shimo-js-sdk'
+import { connect, ShowToastOptions } from 'weboffice-js-sdk'
 
-const shimoSDK = await connect({
+const officeSDK = await connect({
   // 初始化sdk时传了该方法将会拦截编辑器内的toast
   showToast: (options: ShowToastOptions) => {
     // show your toast

package/dist/OfficeSDK.d.ts

@@ -9,7 +9,7 @@ import { Document, DocumentPro, Presentation, Spreadsheet, Table, Form, Flowchar
 import { EmptyPageOptions } from './types/EmptyPage';
 import { BaseEditor } from './types/BaseEditor';
 import { SlashMenuOptions } from './types/SlashMenu';
-import type { CollaboratorFacade, CommentsFacade, ContentFacade, DiscussionFacade, DocsOutlineFacade, DocsSearchFacade, DocsSelectionFacade, DocsSettingsFacade, DocsSidebarFacade, DocsTablesFacade, ExternalAppFacade, HistoryFacade, LocksFacade, MentionFacade, PresentationEventSubscriptionFacade, PresentationFacade, PresentationSelectionFacade, PresentationSlidesFacade, PresentationTextFacade, PresentationZoomFacade, SheetChartsFacade, SheetSelectionsFacade, SheetWorkbookFacade, SheetWorksheetFacade, TitleFacade, VersionFacade } from './OfficeSDK.facade.types';
+import type { CollaboratorFacade, CommentsFacade, ContentFacade, DiscussionFacade, DocsActiveDocumentFacade, DocsOutlineFacade, DocsSearchFacade, DocsSelectionFacade, DocsSettingsFacade, DocsSidebarFacade, DocsTablesFacade, ExternalAppFacade, HistoryFacade, LocksFacade, MentionFacade, OfficeSDKPresentationFacade, PresentationEventSubscriptionFacade, PresentationSelectionFacade, PresentationSlidesFacade, PresentationTextFacade, PresentationZoomFacade, SheetChartsFacade, SheetSelectionsFacade, SheetWorkbookFacade, SheetWorksheetFacade, TitleFacade, VersionFacade } from './OfficeSDK.facade.types';
 import type { HeaderBarsFacade } from './OfficeSDK.headerBars';
 export * from './OfficeSDK.facade.types';
 export * from './OfficeSDK.headerBars';
@@ -36,6 +36,8 @@ export declare class OfficeSDK extends TinyEmitter {
      * @deprecated - 用 `sdk.getEditor<T>()` 替代
      */
     spreadsheet?: Spreadsheet.Editor;
+    /** 当前轻文档的标准化、强类型文档入口。 */
+    ActiveDocument?: DocsActiveDocumentFacade;
     /**
      * 当前套件支持的标题能力。
      */
@@ -78,8 +80,9 @@ export declare class OfficeSDK extends TinyEmitter {
     version?: VersionFacade;
     /**
      * 当前套件支持的演示能力。
+     * 文档与表格支持 start / quit，幻灯片套件额外支持完整演示能力。
      */
-    presentation?: PresentationFacade;
+    presentation?: OfficeSDKPresentationFacade;
     /**
      * 当前套件支持的选区能力。
      */
@@ -309,6 +312,7 @@ export declare class OfficeSDK extends TinyEmitter {
      * 输出：无。
      */
     private unregisterEditorFacadeCallback;
+    private reportEditorFacadeError;
     /**
      * 创建基于 method-path 的模块 facade。
      * 输入：模块前缀与少量自定义实现覆盖。
@@ -465,7 +469,7 @@ export interface SDKToastOptions {
 }
 /**
  * 透传给 iframe 编辑器的主题配置。
- * 当前 shimo-js-sdk 仅负责跨 iframe 传输，不在宿主侧约束字段细节。
+ * 当前 weboffice-js-sdk 仅负责跨 iframe 传输，不在宿主侧约束字段细节。
  */
 export interface CommonThemeConfig {
     [key: string]: unknown;
@@ -596,7 +600,7 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
     headerBarsVisible?: boolean;
     /**
      * 是否隐藏 iframe 内 AI 入口。
-     * 对应 iframe 内 ShimoSDK 的现有 AI 入口开关能力。
+     * 对应 iframe 内 OfficeSDK 的现有 AI 入口开关能力。
      */
     disableAiEntry?: boolean;
     /**

package/dist/OfficeSDK.facade.d.ts

@@ -10,6 +10,7 @@ interface FacadeHost {
     registerEditorFacadeListener<T>(method: string, listener: (payload: T) => void): () => void;
     registerEditorFacadeCallback(callback: EditorFacadeCallback): string;
     unregisterEditorFacadeCallback(callbackId: string): void;
+    reportEditorFacadeError(message: string, error: unknown): void;
 }
 export declare function buildRootFacadeState(host: FacadeHost): OfficeSDKRootFacadeState;
 export {};

package/dist/OfficeSDK.facade.types.d.ts

@@ -3,6 +3,95 @@ export interface TitleFacade {
     addChangedListener: (listener: (title: string) => void) => () => void;
     setTitle: (title: string) => Promise<void>;
 }
+/**
+ * 可安全跨 iframe 传输的文档 Delta 快照。
+ *
+ * 这里只公开序列化结果和基础元数据，不承诺编辑器运行时对象上的
+ * compose / transform 等方法。
+ */
+export interface DocsEditorDeltaSnapshot {
+    length: number;
+    serialized: string;
+    stringify: () => string;
+}
+export interface DocsDocumentPermission {
+    read: boolean;
+    write: boolean;
+    comment: boolean;
+}
+export type DocsDownloadDocumentType = 'pdf' | 'word' | 'image' | 'md';
+export interface DocsProductFontFacade {
+    SetTextColor: (color: string) => Promise<boolean>;
+    SetHighLightColor: (color: string) => Promise<boolean>;
+    SetBold: (value?: boolean) => Promise<boolean>;
+    SetItalic: (value?: boolean) => Promise<boolean>;
+    SetUnderline: (value?: boolean) => Promise<boolean>;
+    SetStrike: (value?: boolean) => Promise<boolean>;
+}
+export interface DocsProductMarkdownFacade {
+    GetMarkdown: () => Promise<string>;
+    AppendMarkdown: (value: string) => Promise<DocsRangeValue>;
+    InsertMarkdown: (value: string) => Promise<DocsRangeValue>;
+    ValidateMarkdown: (value: string) => Promise<boolean>;
+}
+export interface DocsProductContentFacade {
+    ReplaceSelection: (value: string) => Promise<boolean>;
+    ReplaceAllContent: (value: string) => Promise<boolean>;
+}
+export interface DocsProductDocumentFacade {
+    GetContent: () => Promise<DocsEditorDeltaSnapshot>;
+    GetTitleContent: () => Promise<string>;
+    SetTitleContent: (title: string) => Promise<void>;
+    Font: DocsProductFontFacade;
+    Markdown: DocsProductMarkdownFacade;
+    Content: DocsProductContentFacade;
+}
+export interface DocsProductEditorFacade {
+    GetEditMode: () => Promise<string>;
+    Document: DocsProductDocumentFacade;
+}
+export interface DocsActiveDocumentFacade {
+    Editor: DocsProductEditorFacade;
+    Reference: DocsProductReferenceFacade;
+    Service: DocsProductServiceFacade;
+    Sub: DocsProductSubFacade;
+    Env: DocsProductEnvFacade;
+}
+/** 轻文档产品引用能力。 */
+export interface DocsProductReferenceFacade {
+    CanIUse: (scopes: string | string[]) => Promise<boolean>;
+}
+export interface DocsProductUserFacade {
+    GetUserInfo: () => Promise<unknown>;
+}
+export interface DocsProductPermissionFacade {
+    GetDocumentPermission: () => Promise<DocsDocumentPermission>;
+}
+export interface DocsProductExportFacade {
+    DownloadDocument: (format: DocsDownloadDocumentType) => Promise<void>;
+}
+export interface DocsProductCollaborationFacade {
+    GetSaveStatus: () => Promise<unknown>;
+}
+export interface DocsProductServiceFacade {
+    User: DocsProductUserFacade;
+    Permission: DocsProductPermissionFacade;
+    Export: DocsProductExportFacade;
+    Collaboration: DocsProductCollaborationFacade;
+}
+export interface DocsProductSubFacade {
+    OnDocumentChange: (handler: (delta: DocsEditorDeltaSnapshot) => void) => () => void;
+}
+export interface DocsProductLanguageFacade {
+    GetLanguage: () => Promise<string>;
+}
+export interface DocsProductModeFacade {
+    GetDocsMode: () => Promise<string>;
+}
+export interface DocsProductEnvFacade {
+    Language: DocsProductLanguageFacade;
+    DocsMode: DocsProductModeFacade;
+}
 export interface CommentsFacade {
     show: (type?: 'list' | 'card') => Promise<void>;
     hide: (type?: 'list' | 'card') => Promise<void>;
@@ -162,7 +251,9 @@ export interface ClipboardPasteParams {
 }
 export type SheetAppendDataAxis = 'row' | 'column';
 export interface SheetSelection {
-    getRange: (value?: SheetRangeValue) => SheetRangeFacade | null;
+    /** 当前 iframe runtime 内稳定的选区标识。 */
+    id: string;
+    getRange: (value?: SheetRangeValue) => Promise<SheetRangeFacade | null>;
     setRange: (value: SheetRangeValue | null) => Promise<void>;
 }
 export declare enum SheetRangeType {
@@ -429,24 +520,24 @@ export interface PresentationShapeBase {
     id: string;
     name: string;
     type: PresentationShapeType;
-    setFill: (fill: PresentationShapeFill) => void;
-    setLine: (line: PresentationShapeLine) => void;
-    setLayout: (layout: PresentationShapeLayout) => void;
-    remove: () => void;
+    setFill: (fill: PresentationShapeFill) => Promise<void>;
+    setLine: (line: PresentationShapeLine) => Promise<void>;
+    setLayout: (layout: PresentationShapeLayout) => Promise<void>;
+    remove: () => Promise<void>;
 }
 export type PresentationTextShapeType = Exclude<PresentationShapeType, PresentationLineShapeType>;
 export interface PresentationTextShape extends PresentationShapeBase {
     type: PresentationTextShapeType;
     textContent?: string;
-    setContent: (content: PresentationShapeContent) => void;
-    appendText: (text: string) => void;
-    appendParagraphs: (paragraphs: PresentationParagraph[]) => void;
+    setContent: (content: PresentationShapeContent) => Promise<void>;
+    appendText: (text: string) => Promise<void>;
+    appendParagraphs: (paragraphs: PresentationParagraph[]) => Promise<void>;
 }
 export type PresentationShape = PresentationShapeBase | PresentationTextShape;
 export type PresentationParagraphLineSpacing = 0.9 | 1.0 | 1.15 | 1.5 | 2.0 | 2.5 | 3.0;
 export interface PresentationTableCell {
-    setStyle: (style: PresentationTableCellStyle) => void;
-    clearStyle: () => void;
+    setStyle: (style: PresentationTableCellStyle) => Promise<void>;
+    clearStyle: () => Promise<void>;
 }
 export type PresentationTableCellStyle = PresentationTextStyle & PresentationParagraphStyle;
 export interface PresentationTableSelection {
@@ -456,25 +547,25 @@ export interface PresentationTableSelection {
     columnCount: number;
 }
 export interface PresentationTableRange {
-    setStyle: (style: PresentationTableCellStyle) => void;
-    clearStyle: () => void;
-    setSpan: () => void;
-    removeSpan: () => void;
+    setStyle: (style: PresentationTableCellStyle) => Promise<void>;
+    clearStyle: () => Promise<void>;
+    setSpan: () => Promise<void>;
+    removeSpan: () => Promise<void>;
 }
 export interface PresentationTableItem {
     id: string;
     rowCount: number;
     columnCount: number;
-    remove: () => void;
-    insertRows: (index: number, count: number, placement?: 'before' | 'after') => void;
-    insertColumns: (index: number, count: number, placement?: 'before' | 'after') => void;
-    deleteRows: (index: number, count: number) => void;
-    deleteColumns: (index: number, count: number) => void;
-    setRowHeight: (index: number, height: number) => void;
-    setColumnWidth: (index: number, width: number) => void;
-    getCell: (row: number, column: number) => PresentationTableCell | null;
-    getRange: (range: PresentationTableSelection) => PresentationTableRange | null;
-    setDirection: (direction: 'ltr' | 'rtl') => void;
+    remove: () => Promise<void>;
+    insertRows: (index: number, count: number, placement?: 'before' | 'after') => Promise<void>;
+    insertColumns: (index: number, count: number, placement?: 'before' | 'after') => Promise<void>;
+    deleteRows: (index: number, count: number) => Promise<void>;
+    deleteColumns: (index: number, count: number) => Promise<void>;
+    setRowHeight: (index: number, height: number) => Promise<void>;
+    setColumnWidth: (index: number, width: number) => Promise<void>;
+    getCell: (row: number, column: number) => Promise<PresentationTableCell | null>;
+    getRange: (range: PresentationTableSelection) => Promise<PresentationTableRange | null>;
+    setDirection: (direction: 'ltr' | 'rtl') => Promise<void>;
 }
 export interface PresentationTableOptions {
     offset: PresentationOffset;
@@ -512,14 +603,18 @@ export interface VersionFacade {
     hide?: () => Promise<void>;
     createRevision: (options?: RevisionCreateOptions) => Promise<undefined | null | DocumentErrorMessage>;
 }
-export interface PresentationFacade {
-    start: (index?: number) => Promise<void>;
+export interface BasicPresentationFacade {
+    start: () => Promise<void>;
     quit: () => Promise<void>;
+}
+export interface PresentationFacade extends BasicPresentationFacade {
+    start: (index?: number) => Promise<void>;
     startFromCurrent: () => Promise<void>;
     startRemoteLive: () => Promise<void>;
     startSpeakerView: () => Promise<void>;
     addChangeListener: (listener: (payload: unknown) => void) => () => void;
 }
+export type OfficeSDKPresentationFacade = BasicPresentationFacade | PresentationFacade;
 export interface DocsRangeFacade {
     start: number;
     end: number;
@@ -623,6 +718,12 @@ export interface SheetRangeFacade {
     column: number;
     rowCount: number;
     columnCount: number;
+    getBounding: () => Promise<{
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | null>;
     getText: (format?: 'plain' | 'matrix') => Promise<string | string[][]>;
     setText: (text: SheetRangeText) => Promise<void>;
     getHtml: () => Promise<string>;
@@ -671,6 +772,7 @@ export interface SheetWorksheetFacade {
         sheet: string;
         ranges: SheetRangeValue[] | null;
     }) => void) => () => void;
+    /** @deprecated 先 await worksheet.getRange(range)，再调用 range?.getBounding()。 */
     getBounding: (range: SheetRangeValue) => Promise<{
         left: number;
         top: number;
@@ -817,6 +919,7 @@ export interface PresentationEventSubscriptionFacade {
     addLoadedListener: (listener: () => void) => () => void;
 }
 export interface OfficeSDKRootFacadeState {
+    ActiveDocument?: DocsActiveDocumentFacade;
     title?: TitleFacade;
     history?: HistoryFacade;
     comments?: CommentsFacade;
@@ -827,7 +930,7 @@ export interface OfficeSDKRootFacadeState {
     mention?: MentionFacade;
     content?: ContentFacade;
     version?: VersionFacade;
-    presentation?: PresentationFacade;
+    presentation?: OfficeSDKPresentationFacade;
     selection?: DocsSelectionFacade | PresentationSelectionFacade;
     search?: DocsSearchFacade;
     outline?: DocsOutlineFacade;

package/dist/editorFacade.contract.d.ts

@@ -1,5 +1,6 @@
-import type { AddChartFromSelectionResult, DocsRangeFacade, DocsRangeValue, DocsTableFacade, EditorTextFormat, OfficeSDK, PresentationSlideFacade, PresentationShape, PresentationShapeBase, PresentationTextShape, PresentationTextRangeFacade, PresentationTextRangeValue, SheetRangeValue, SheetRangeFacade, SheetSelection } from './OfficeSDK';
+import type { AddChartFromSelectionResult, BasicPresentationFacade, DocsActiveDocumentFacade, DocsEditorDeltaSnapshot, DocsRangeFacade, DocsRangeValue, DocsTableFacade, EditorTextFormat, OfficeSDK, PresentationFacade, PresentationSlideFacade, PresentationShape, PresentationShapeBase, PresentationTableCell, PresentationTableItem, PresentationTableRange, PresentationTableSelection, PresentationTextShape, PresentationTextRangeFacade, PresentationTextRangeValue, SheetRangeValue, SheetRangeFacade, SheetSelection } from './OfficeSDK';
 type IsAssignable<T, U> = T extends U ? true : false;
+type IsEqual<T, U> = (<V>() => V extends T ? 1 : 2) extends <V>() => V extends U ? 1 : 2 ? (<V>() => V extends U ? 1 : 2) extends <V>() => V extends T ? 1 : 2 ? true : false : false;
 type Assert<T extends true> = T;
 type RootSelection = NonNullable<OfficeSDK['selection']>;
 type DocsSelection = Extract<RootSelection, {
@@ -8,16 +9,28 @@ type DocsSelection = Extract<RootSelection, {
 type PresentationSelection = Extract<RootSelection, {
     getTextRange: (value?: PresentationTextRangeValue) => Promise<PresentationTextRangeFacade | null>;
 }>;
+type RootPresentation = NonNullable<OfficeSDK['presentation']>;
 export type EditorFacadeContractAssertions = [
+    Assert<IsEqual<NonNullable<OfficeSDK['ActiveDocument']>, DocsActiveDocumentFacade>>,
+    Assert<IsEqual<DocsActiveDocumentFacade['Editor']['Document']['GetContent'], () => Promise<DocsEditorDeltaSnapshot>>>,
+    Assert<IsEqual<DocsActiveDocumentFacade['Editor']['Document']['Markdown']['AppendMarkdown'], (value: string) => Promise<DocsRangeValue>>>,
+    Assert<IsEqual<DocsActiveDocumentFacade['Service']['Permission']['GetDocumentPermission'], () => Promise<import('./OfficeSDK').DocsDocumentPermission>>>,
+    Assert<IsEqual<DocsActiveDocumentFacade['Service']['Export']['DownloadDocument'], (format: import('./OfficeSDK').DocsDownloadDocumentType) => Promise<void>>>,
+    Assert<IsEqual<DocsActiveDocumentFacade['Sub']['OnDocumentChange'], (handler: (delta: DocsEditorDeltaSnapshot) => void) => () => void>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['title']>['setTitle'], (title: string) => Promise<void>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['title']>['addChangedListener'], (listener: (title: string) => void) => () => void>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['locks']>['addRangeLock'], (options: import('./OfficeSDK').AddRangeLockParams) => Promise<void>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['history']>['show'], () => Promise<void>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['mention']>['locateCellByGuid'], (guid: string, notificationType?: import('./OfficeSDK').MentionTypes) => Promise<void>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['version']>['createRevision'], (options?: import('./OfficeSDK').RevisionCreateOptions) => Promise<undefined | null | import('./types/Document').DocumentErrorMessage>>>,
-    Assert<IsAssignable<NonNullable<OfficeSDK['presentation']>['start'], (index?: number) => Promise<void>>>,
-    Assert<IsAssignable<NonNullable<OfficeSDK['presentation']>['startFromCurrent'], () => Promise<void>>>,
-    Assert<IsAssignable<NonNullable<OfficeSDK['presentation']>['addChangeListener'], (listener: (payload: unknown) => void) => () => void>>,
+    Assert<IsAssignable<RootPresentation, BasicPresentationFacade>>,
+    Assert<IsAssignable<RootPresentation['start'], () => Promise<void>>>,
+    Assert<IsAssignable<RootPresentation['quit'], () => Promise<void>>>,
+    Assert<IsAssignable<PresentationFacade['start'], (index?: number) => Promise<void>>>,
+    Assert<IsAssignable<PresentationFacade['startFromCurrent'], () => Promise<void>>>,
+    Assert<IsAssignable<PresentationFacade['startRemoteLive'], () => Promise<void>>>,
+    Assert<IsAssignable<PresentationFacade['startSpeakerView'], () => Promise<void>>>,
+    Assert<IsAssignable<PresentationFacade['addChangeListener'], (listener: (payload: unknown) => void) => () => void>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['batchChanges']>, <T>(callback: () => T | Promise<T>) => Promise<Awaited<T>>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['print']>, () => Promise<void>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['export']>, (type: string) => Promise<void>>>,
@@ -38,10 +51,25 @@ export type EditorFacadeContractAssertions = [
     Assert<IsAssignable<NonNullable<OfficeSDK['text']>['apply'], (format: Partial<EditorTextFormat>, range?: PresentationTextRangeValue) => Promise<Partial<EditorTextFormat>>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['activeSheet']>['getSelections'], () => Promise<SheetSelection[] | null>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['activeSheet']>['getRange'], (value: SheetRangeValue) => Promise<SheetRangeFacade | null>>>,
+    Assert<IsEqual<SheetRangeFacade['getBounding'], () => Promise<{
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | null>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['selections']>['getAll'], () => Promise<SheetRangeValue[]>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['charts']>['addChartFromSelection'], (params?: import('./OfficeSDK').AddChartFromSelectionParams) => Promise<AddChartFromSelectionResult | undefined>>>,
     Assert<IsAssignable<PresentationSelection['getSelectedShapes'], (ids?: string[]) => Promise<PresentationShape[] | null>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['zoom']>['setPercentage'], (percentage: number) => Promise<void>>>,
-    Assert<IsAssignable<NonNullable<OfficeSDK['eventSubscription']>['addLoadedListener'], (listener: () => void) => () => void>>
+    Assert<IsAssignable<NonNullable<OfficeSDK['eventSubscription']>['addLoadedListener'], (listener: () => void) => () => void>>,
+    Assert<IsEqual<SheetSelection['getRange'], (value?: SheetRangeValue) => Promise<SheetRangeFacade | null>>>,
+    Assert<IsEqual<SheetSelection['id'], string>>,
+    Assert<IsEqual<PresentationShapeBase['setFill'], (fill: import('./OfficeSDK').PresentationShapeFill) => Promise<void>>>,
+    Assert<IsEqual<PresentationShapeBase['remove'], () => Promise<void>>>,
+    Assert<IsEqual<PresentationTableItem['getCell'], (row: number, column: number) => Promise<PresentationTableCell | null>>>,
+    Assert<IsEqual<PresentationTableItem['getRange'], (range: PresentationTableSelection) => Promise<PresentationTableRange | null>>>,
+    Assert<IsEqual<PresentationTableItem['insertRows'], (index: number, count: number, placement?: 'before' | 'after') => Promise<void>>>,
+    Assert<IsEqual<PresentationTableCell['clearStyle'], () => Promise<void>>>,
+    Assert<IsEqual<PresentationTableRange['setSpan'], () => Promise<void>>>
 ];
 export {};

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import * as Flowchart from './types/FlowChart';
 import { EventMap as BaseEventMap, BaseEditor } from './types/BaseEditor';
 export * from 'weboffice-js-sdk-shared';
 export * from './connect';
+export type { JSAPIAdapter, JSAPIContract, JSAPIContractCatalog, JSAPITransport } from './jsapi';
 export * from './OfficeSDK';
 export type { EmptyPageScene, EmptyPageOptions, EmptyPageActionOverride, EmptyPageContentOverride, NormalizedEmptyPageOptions, EmptyPageShownPayload, EmptyPageActionPayload, EmptyPageHiddenPayload, FileOpenFailedReason, TokenExpiredStrategy } from './types/EmptyPage';
 export type { SlashMenuButton, SlashMenuEntry, SlashMenuOptions } from './types/SlashMenu';