weboffice-js-sdk 2.0.5-beta.1 → 2.0.5-beta.11

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,52 @@ connect({
 
 其中：
 
-- `disableAiEntry` 为可选布尔值，透传到 iframe 内 `ShimoSDK` 的 AI 入口开关能力。
+- `disableAiEntry` 为可选布尔值，透传到 iframe 内 `OfficeSDK` 的 AI 入口开关能力。
 - `theme` 为可选主题对象，宿主侧仅负责透传；未传时 iframe 内仍使用默认主题配置。
 
+### V2 统一编辑 / 预览入口
+
+V2 使用独立的 `connectV2()`，旧 `connect()` 保持兼容。V2 要求 `type` 和 `mode` 必填：
+
+```typescript
+import { connectV2 } from 'weboffice-js-sdk'
+
+const sdk = await connectV2({
+  fileId: 'your-file-id',
+  endpoint: 'https://your-shimo-endpoint',
+  signature: 'your-signature',
+  token: 'your-token',
+  container: document.querySelector('#shimo-file'),
+  type: 'writer',
+  mode: 'edit',
+  refreshCredentialsInterval: 600000
+})
+```
+
+支持的 `type` 包括 `file`、`document`、`documentPro`、`writer`、`spreadsheet`、`presentation`、`table` 和 `form`。`writer` 与 `documentPro` 当前共存，`writer` 目前处于内测阶段。当前 `type` 主要作为 iframe 后续基于 `manifest.json` 选择资源的预留字段，不改变后端编辑准备判断。
+
 返回值：
 
 ```
-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 +105,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 +125,7 @@ connect({
 获取编辑器实例和与其交互：
 
 ```js
-const { FileType } = require('shimo-js-sdk')
+const { FileType } = require('weboffice-js-sdk')
 
 // 获取编辑器实例
 const editor = sdk.getEditor()
@@ -123,7 +144,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 +214,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 +258,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 +320,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 +523,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 +547,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,12 +9,10 @@ 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, 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';
-import type { BrandingFacade } from './OfficeSDK.branding';
 export * from './OfficeSDK.facade.types';
 export * from './OfficeSDK.headerBars';
-export * from './OfficeSDK.branding';
 export declare const MessageEvent: typeof InvokeMethod;
 export declare class OfficeSDK extends TinyEmitter {
     /**
@@ -80,8 +78,9 @@ export declare class OfficeSDK extends TinyEmitter {
     version?: VersionFacade;
     /**
      * 当前套件支持的演示能力。
+     * 文档与表格支持 start / quit，幻灯片套件额外支持完整演示能力。
      */
-    presentation?: PresentationFacade;
+    presentation?: OfficeSDKPresentationFacade;
     /**
      * 当前套件支持的选区能力。
      */
@@ -170,7 +169,6 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     flowchart?: Flowchart.Editor;
     readonly headerBars: HeaderBarsFacade;
-    readonly branding: BrandingFacade;
     private _fileType;
     private readonly messageHandler;
     /**
@@ -203,12 +201,16 @@ export declare class OfficeSDK extends TinyEmitter {
     private readonly headerBarsCommandRefs;
     private headerBarsTitleChangeHandler?;
     private headerBarsTitleChangeSubscribed;
-    private editorFooterLogo?;
     private readonly onViewportResize;
     /**
      * 归一化后的缺省页配置，构造时一次算完，后续仅读取。
      */
     private readonly normalizedEmptyPage;
+    private readonly preloadCredentialsMessageHandler;
+    private pendingInitializationErrorHandler?;
+    private pendingInitializationError?;
+    private preloadCredentialsPromise?;
+    private disconnected;
     private readonly preloadAckTimeoutMs;
     private readonly preloadDoneTimeoutMs;
     private readonly preloadReadyTimeoutMs;
@@ -281,6 +283,8 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     ready(): Promise<void>;
     private initIframe;
+    private handlePreloadMessage;
+    private getPreloadCredentials;
     private runPreloadHandshake;
     private initChannel;
     /**
@@ -288,7 +292,6 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     private bindContainerMethodHandlers;
     private initHeaderBarsFacade;
-    private initBrandingFacade;
     /**
      * 订阅 iframe 侧 titleChange 事件，并在宿主设置了 headerBars.onTitleChange 时转发标题值。
      * 输入：无。
@@ -296,12 +299,9 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     private ensureHeaderBarsTitleChangeSubscription;
     private invokeHeaderBars;
-    private invokeBranding;
     private syncHeaderBarsCommands;
     private createHeaderBarsHost;
-    private createBrandingHost;
     private applyHeaderBarsChanged;
-    private applyBrandingChanged;
     private syncHeaderBarsVisible;
     private setHeaderBarsVisible;
     private getHeaderBarsCommandRef;
@@ -473,7 +473,7 @@ export interface SDKToastOptions {
 }
 /**
  * 透传给 iframe 编辑器的主题配置。
- * 当前 shimo-js-sdk 仅负责跨 iframe 传输，不在宿主侧约束字段细节。
+ * 当前 weboffice-js-sdk 仅负责跨 iframe 传输，不在宿主侧约束字段细节。
  */
 export interface CommonThemeConfig {
     [key: string]: unknown;
@@ -604,7 +604,7 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
     headerBarsVisible?: boolean;
     /**
      * 是否隐藏 iframe 内 AI 入口。
-     * 对应 iframe 内 ShimoSDK 的现有 AI 入口开关能力。
+     * 对应 iframe 内 OfficeSDK 的现有 AI 入口开关能力。
      */
     disableAiEntry?: boolean;
     /**

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

@@ -162,7 +162,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 +431,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 +458,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 +514,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 +629,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 +683,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;
@@ -827,7 +840,7 @@ export interface OfficeSDKRootFacadeState {
     mention?: MentionFacade;
     content?: ContentFacade;
     version?: VersionFacade;
-    presentation?: PresentationFacade;
+    presentation?: OfficeSDKPresentationFacade;
     selection?: DocsSelectionFacade | PresentationSelectionFacade;
     search?: DocsSearchFacade;
     outline?: DocsOutlineFacade;

package/dist/connect.d.ts

@@ -1,6 +1,19 @@
 import { OfficeSDK, OfficeSDKOptions } from './OfficeSDK';
+import { type ConnectV2FileType } from './types/ConnectV2';
+export { CONNECT_V2_FILE_TYPES, isConnectV2FileType, isConnectV2Mode, validateConnectV2Options } from './types/ConnectV2';
+export type { ConnectV2FileType } from './types/ConnectV2';
 export interface ConnectOptions extends OfficeSDKOptions {
 }
+export interface ConnectV2Options extends ConnectOptions {
+    /**
+     * V2 套件类型。当前用于 iframe 侧资源选择预留。
+     */
+    type: ConnectV2FileType;
+    /**
+     * V2 打开模式。
+     */
+    mode: 'edit' | 'preview';
+}
 /**
  * 初始化 SDK，返回 Promise，当 ReadState 变为 Ready 或 Failed 时，Promise 将被 resolve。
  * Promise resovled 不代表编辑器已经完整加载完毕，只代表 SDK 已经准备好了。
@@ -8,3 +21,9 @@ export interface ConnectOptions extends OfficeSDKOptions {
  * 比如受浏览器限制无法发出 postMessage() 时，Promise 将会一直 pending。
  */
 export declare function connect(options: ConnectOptions): Promise<OfficeSDK>;
+/**
+ * 初始化 V2 统一编辑 / 预览入口。
+ *
+ * V2 在运行时强制校验 type 和 mode，底层 iframe 初始化流程与旧 connect 共用。
+ */
+export declare function connectV2(options: ConnectV2Options): Promise<OfficeSDK>;

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, 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,6 +9,7 @@ type DocsSelection = Extract<RootSelection, {
 type PresentationSelection = Extract<RootSelection, {
     getTextRange: (value?: PresentationTextRangeValue) => Promise<PresentationTextRangeFacade | null>;
 }>;
+type RootPresentation = NonNullable<OfficeSDK['presentation']>;
 export type EditorFacadeContractAssertions = [
     Assert<IsAssignable<NonNullable<OfficeSDK['title']>['setTitle'], (title: string) => Promise<void>>>,
     Assert<IsAssignable<NonNullable<OfficeSDK['title']>['addChangedListener'], (listener: (title: string) => void) => () => void>>,
@@ -15,9 +17,14 @@ export type EditorFacadeContractAssertions = [
     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,12 +45,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<OfficeSDK['branding']['getEditorFooterLogo'], () => Promise<import('./OfficeSDK').SDKBrandConfig | undefined>>>,
-    Assert<IsAssignable<OfficeSDK['branding']['setEditorFooterLogoSrc'], (src: string) => Promise<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 {};