weboffice-js-sdk 2.0.5-beta.15 → 2.0.5-beta.17

package/README.md

@@ -47,6 +47,27 @@ connect({
 - `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` 选择资源的预留字段，不改变后端编辑准备判断。
+
 返回值：
 
 ```

package/dist/OfficeSDK.d.ts

@@ -9,12 +9,12 @@ 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 { ContentVersion } from './types/ConnectV2';
 import type { CollaboratorFacade, CommentsFacade, ContentFacade, DiscussionFacade, DocsActiveOutlineFacade, 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 { OfficeSDKMethodPath } from './OfficeSDK.methods';
 import type { HeaderBarsFacade } from './OfficeSDK.headerBars';
 export * from './OfficeSDK.facade.types';
 export * from './OfficeSDK.headerBars';
-export { toHeaderBarsCallbackAnchorRect } from './headerBarsAnchor';
 export declare const MessageEvent: typeof InvokeMethod;
 export declare class OfficeSDK extends TinyEmitter {
     /**
@@ -185,6 +185,7 @@ export declare class OfficeSDK extends TinyEmitter {
     private readonly emitter;
     private channel;
     private readonly connectOptions;
+    private readonly contentVersion?;
     private _readyState;
     private editor;
     private readonly startParams;
@@ -204,22 +205,27 @@ export declare class OfficeSDK extends TinyEmitter {
     private headerBarsVisible;
     private readonly headerBarsCommands;
     private readonly headerBarsCommandOverrides;
-    private readonly headerBarsCommandEventOverrides;
-    private headerBarsCapabilities;
     private readonly slashMenuCallbacks;
     private readonly editorFacadeCallbacks;
     private readonly headerBarsCommandRefs;
     private headerBarsTitleChangeHandler?;
     private headerBarsTitleChangeSubscribed;
     private readonly onViewportResize;
+    private readonly onOutsidePointerDown;
+    private outsidePointerEventName?;
     /**
      * 归一化后的缺省页配置，构造时一次算完，后续仅读取。
      */
     private readonly normalizedEmptyPage;
+    private readonly preloadCredentialsMessageHandler;
+    private pendingInitializationErrorHandler?;
+    private pendingInitializationError?;
+    private preloadCredentialsPromise?;
+    private disconnected;
     private readonly preloadAckTimeoutMs;
     private readonly preloadDoneTimeoutMs;
     private readonly preloadReadyTimeoutMs;
-    constructor(options: OfficeSDKOptions);
+    constructor(options: OfficeSDKOptions, contentVersion?: ContentVersion);
     get fileType(): FileType;
     get readyState(): ReadyState;
     /**
@@ -275,6 +281,24 @@ export declare class OfficeSDK extends TinyEmitter {
      * 获取性能信息片段列表，由于性能标记是分段的、异步的，因此每次调用时获取的列表有可能不一致
      */
     getPerformanceEntries(): Promise<PerformanceEntry[]>;
+    /**
+     * 在父文档 capture 阶段监听真实按下，点到本 iframe 之外时通知 iframe 结束编辑。
+     * 输入：无。
+     * 输出：无返回值，重复绑定会被忽略。
+     */
+    private bindOutsideIframePointerListener;
+    /**
+     * 拆除父文档上的 iframe 外按下监听。
+     * 输入：无。
+     * 输出：无返回值；未绑定时直接返回。
+     */
+    private unbindOutsideIframePointerListener;
+    /**
+     * 处理父页按下：目标不是本 iframe 时 fire-and-forget 通知 iframe。
+     * 输入：父文档上的 pointerdown/mousedown 事件。
+     * 输出：无返回值；channel 失败时吞掉，避免打断宿主页面。
+     */
+    private notifyOutsidePointerDown;
     disconnect(): void;
     /**
      * 初始化 SDK，返回 Promise，当 ReadState 变为 Ready 或 Failed 时，Promise 将被 resolve。
@@ -288,6 +312,8 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     ready(): Promise<void>;
     private initIframe;
+    private handlePreloadMessage;
+    private getPreloadCredentials;
     private runPreloadHandshake;
     private initChannel;
     /**
@@ -302,11 +328,6 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     private ensureHeaderBarsTitleChangeSubscription;
     private invokeHeaderBars;
-    /**
-     * 将 iframe viewport 坐标转换为宿主 window viewport 坐标。
-     * 输入为 iframe 内事件矩形；输出不包含任何 DOM 对象。
-     */
-    private toHeaderBarsCallbackAnchorRect;
     private syncHeaderBarsCommands;
     private createHeaderBarsHost;
     private applyHeaderBarsChanged;

package/dist/OfficeSDK.headerBars.d.ts

@@ -1,5 +1,4 @@
 export declare const HEADER_BARS_METHOD: {
-    readonly getCapabilities: "headerBars.getCapabilities";
     readonly getVisible: "headerBars.getVisible";
     readonly setVisible: "headerBars.setVisible";
     readonly addCommand: "headerBars.addCommand";
@@ -13,12 +12,6 @@ export declare const HEADER_BARS_METHOD: {
     readonly setCommandCallbackEnabled: "headerBars.setCommandCallbackEnabled";
     readonly listViewCommands: "headerBars.listViewCommands";
     readonly handleCommandClick: "headerBars.handleCommandClick";
-    readonly addCommands: "headerBars.addCommands";
-    readonly setSectionVisible: "headerBars.setSectionVisible";
-    readonly setCommandOptions: "headerBars.setCommandOptions";
-    readonly setCommandOpen: "headerBars.setCommandOpen";
-    readonly setCommandEventCallbackEnabled: "headerBars.setCommandEventCallbackEnabled";
-    readonly handleCommandEvent: "headerBars.handleCommandEvent";
 };
 export declare const HEADER_BARS_CHANGED_EVENT = "headerBars:changed";
 export interface HeaderBarsCommandDefinition {
@@ -33,21 +26,10 @@ export interface HeaderBarsCommandDefinition {
     type?: 'action' | 'structural';
     renderType?: string;
     src?: string;
-    danger?: boolean;
-    disabledTip?: string;
-    itemType?: 'command' | 'divider';
-    trigger?: 'hover' | 'click';
-    open?: boolean;
-    style?: HeaderBarsCommandStyle;
-    toast?: Record<string, unknown>;
-    subItems?: HeaderBarsCommandDefinition[];
     onClick?: () => void | Promise<void>;
-    onOpen?: HeaderBarsCommandOpenHandler;
-    onClose?: HeaderBarsCommandCloseHandler;
 }
 export interface HeaderBarsCommandState extends HeaderBarsCommandDefinition {
     type: 'action' | 'structural';
-    open?: boolean;
 }
 export interface HeaderBarsCommandRef {
     readonly id: string;
@@ -57,87 +39,9 @@ export interface HeaderBarsCommandRef {
     src?: string;
     label?: string;
     editable?: boolean;
-    open: boolean;
-    style?: HeaderBarsCommandStyle;
-    subItems?: HeaderBarsCommandDefinition[];
     onCommandClick?: () => void | Promise<void>;
-    onCommandOpen?: HeaderBarsCommandOpenHandler;
-    onCommandClose?: HeaderBarsCommandCloseHandler;
     getState: () => HeaderBarsCommandState | undefined;
 }
-export interface HeaderBarsCommandStyle {
-    color?: string;
-    fontSize?: number;
-    fontWeight?: number;
-    backgroundColor?: string;
-    borderColor?: string;
-    borderWidth?: number;
-    borderRadius?: number;
-    width?: number;
-    height?: number;
-}
-export interface HeaderBarsAnchorRect {
-    left: number;
-    top: number;
-    right: number;
-    bottom: number;
-    width: number;
-    height: number;
-    viewport: {
-        width: number;
-        height: number;
-    };
-    coordinateSpace: 'callback-window-viewport';
-}
-export interface HeaderBarsSourceAnchorRect {
-    left: number;
-    top: number;
-    right: number;
-    bottom: number;
-    width: number;
-    height: number;
-    viewport: {
-        width: number;
-        height: number;
-    };
-    coordinateSpace: 'sdk-iframe-viewport';
-}
-export interface HeaderBarsCommandEventPayload {
-    requestId: string;
-    sequence: number;
-    commandId: string;
-    event: 'click' | 'open' | 'close';
-    anchorRect: HeaderBarsSourceAnchorRect;
-    context?: Record<string, unknown>;
-}
-export type HeaderBarsCommandEventResult = 'handled' | 'unhandled' | 'failed' | 'timedOut';
-export interface HeaderBarsCommandEvent {
-    commandId: string;
-    event: 'click' | 'open' | 'close';
-    anchorRect: HeaderBarsAnchorRect;
-    context?: Record<string, unknown>;
-}
-export type HeaderBarsCommandClickHandler = (event?: HeaderBarsCommandEvent) => void | Promise<void>;
-export type HeaderBarsCommandOpenHandler = (commandId: string, anchorRect: HeaderBarsAnchorRect, context: Record<string, unknown>) => void | Promise<void>;
-export type HeaderBarsCommandCloseHandler = HeaderBarsCommandOpenHandler;
-type HeaderBarsEventHandler = (...args: any[]) => void | Promise<void>;
-export interface HeaderBarsCapabilities {
-    protocolVersion: 1 | 2;
-    features: {
-        treeCommands: boolean;
-        batchCommands: boolean;
-        sectionVisibility: boolean;
-        commandOptions: boolean;
-        commandOpenState: boolean;
-        commandEvents: boolean;
-        anchorEvents: boolean;
-    };
-}
-export interface HeaderBarsMutationResult {
-    success: boolean;
-    code?: string;
-    message?: string;
-}
 export type HeaderBarsTitleChangeHandler = (title: string) => void | Promise<void>;
 export interface HeaderBarsFacade {
     visible: boolean;
@@ -147,9 +51,6 @@ export interface HeaderBarsFacade {
     addCommand: (command: HeaderBarsCommandDefinition, posCommand: string, pos?: 'before' | 'after') => Promise<boolean>;
     getCommand: (id: string) => HeaderBarsCommandRef;
     listViewCommands: () => Promise<HeaderBarsCommandState[]>;
-    getCapabilities: () => Promise<HeaderBarsCapabilities>;
-    addCommands: (commands: HeaderBarsCommandDefinition[], posCommand: string, pos?: 'before' | 'after') => Promise<HeaderBarsMutationResult>;
-    setSectionVisible: (section: 'left' | 'right', visible: boolean) => Promise<HeaderBarsMutationResult>;
 }
 export interface HeaderBarsChangedPayload {
     reason?: string;
@@ -165,10 +66,6 @@ interface HeaderBarsHost {
     setVisibleState(visible: boolean): void;
     getCommandsMap(): Map<string, HeaderBarsCommandState>;
     getOverridesMap(): Map<string, (() => void | Promise<void>) | undefined>;
-    getEventOverridesMap(): Map<string, HeaderBarsEventHandler | undefined>;
-    getCapabilitiesState(): HeaderBarsCapabilities;
-    setCapabilitiesState(capabilities: HeaderBarsCapabilities): void;
-    getIframeElement(): HTMLElement | null;
     getRefsMap(): Map<string, HeaderBarsCommandRef>;
     getTitleHandler(): HeaderBarsTitleChangeHandler | undefined;
     setTitleHandler(handler: HeaderBarsTitleChangeHandler | undefined): void;

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>;