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

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 内部需要的参数。
      */
@@ -264,14 +347,27 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
      * 指定石墨 SDK 编辑器界面语言，添加到 iframe URLSearchParams 的参数列表。
      * 若未指定，则 iframe 使用服务器设置的默认语言。
      *
-     * 目前支持的语言取值：
+     * 目前支持的标准语言取值：
      * 1. zh-CN（简体中文）
-     * 2. en（英文）
-     * 3. ja（日文）
-     * 4. ar-SA（阿拉伯语）
-     * 5. ru-RU（俄语）
+     * 2. zh-TW（繁体中文）
+     * 3. en-US（英文）
+     * 4. ja-JP（日文）
+     * 5. ko-KR（韩文）
+     * 6. es-ES（西班牙语）
+     * 7. pt-PT（葡萄牙语）
+     * 8. de-DE（德语）
+     * 9. fr-FR（法语）
+     * 10. it-IT（意大利语）
+     * 11. ru-RU（俄语）
+     * 12. id-ID（印尼语）
+     * 13. vi-VN（越南语）
+     * 14. th-TH（泰语）
+     * 15. ms-MY（马来语）
+     * 16. ar-SA（阿拉伯语）
+     *
+     * 为兼容旧版写法，仍接受 en、ja，传入后会自动映射为 en-US、ja-JP。
      */
-    lang?: 'zh-CN' | 'en' | 'ja' | 'ar-SA' | 'ru-RU';
+    lang?: 'zh-CN' | 'zh-TW' | 'en-US' | 'ja-JP' | 'ko-KR' | 'es-ES' | 'pt-PT' | 'de-DE' | 'fr-FR' | 'it-IT' | 'ru-RU' | 'id-ID' | 'vi-VN' | 'th-TH' | 'ms-MY' | 'ar-SA' | 'en' | 'ja';
     /**
      * 是否禁用提及的浮动卡片组件
      */
@@ -311,14 +407,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 +441,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";