weboffice-js-sdk 2.0.3-beta.7 → 2.0.3-beta.9

package/README.md

@@ -152,6 +152,35 @@ command.onCommandClick = async () => {
 }
 ```
 
+### Docs `slashMenu` 初始化参数
+
+`connect()` 支持为 docs 套件透传 `slashMenu` 初始化参数。该配置只在 docs 文件类型下生效，`button.callback` 会保留在宿主页执行，iframe 内点击按钮后会通过 SDK 通道回调到宿主。
+
+```ts
+const sdk = await connect({
+  ...options,
+  slashMenu: {
+    entries: [
+      {
+        name: 'aiMenu',
+        type: 'entry',
+        label: '智能 AI',
+        children: [
+          {
+            name: 'openDocsAiPanel',
+            type: 'button',
+            label: '打开 AI 面板',
+            callback: () => {
+              console.log('docs slash menu clicked')
+            }
+          }
+        ]
+      }
+    ]
+  }
+})
+```
+
 ### 协作者模块使用说明
 
 当 iframe 套件开启协作者能力后（依赖 `ENABLE_SDK_COLLABORATORS_MODULE` 开关），shimo-js-sdk 使用方可按以下方式接入：

package/dist/OfficeSDK.d.ts

@@ -8,40 +8,11 @@ import { ContainerMethod, ContainerRect, DisableMentionCards, FileType, InvokeMe
 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 type HeaderBarsTitleChangeHandler = (title: string) => void | Promise<void>;
-export interface HeaderBarsFacade {
-    visible: boolean;
-    onTitleChange?: HeaderBarsTitleChangeHandler;
-    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[]>;
-}
+import { SlashMenuOptions } from './types/SlashMenu';
+import type { CollaboratorFacade, CommentsFacade, ContentFacade, DiscussionFacade, DocsSearchFacade, DocsSelectionFacade, DocsSettingsFacade, DocsSidebarFacade, DocsTOCsFacade, DocsTablesFacade, ExternalAppFacade, HistoryFacade, LocksFacade, MentionFacade, PresentationEventSubscriptionFacade, PresentationFacade, 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';
 export declare const MessageEvent: typeof InvokeMethod;
 export declare class OfficeSDK extends TinyEmitter {
     /**
@@ -66,10 +37,121 @@ export declare class OfficeSDK extends TinyEmitter {
      */
     spreadsheet?: Spreadsheet.Editor;
     /**
-     * 专业幻灯片编辑器实例
-     * @deprecated - 用 `sdk.getEditor<T>()` 替代
+     * 当前套件支持的标题能力。
+     */
+    title?: TitleFacade;
+    /**
+     * 当前套件支持的历史能力。
+     */
+    history?: HistoryFacade;
+    /**
+     * 当前套件支持的评论能力。
+     */
+    comments?: CommentsFacade;
+    /**
+     * 当前套件支持的讨论能力。
+     */
+    discussion?: DiscussionFacade;
+    /**
+     * 当前套件支持的编写者侧边栏能力。
+     */
+    collaborator?: CollaboratorFacade;
+    /**
+     * 当前套件支持的第三方应用插入能力。
+     */
+    externalApp?: ExternalAppFacade;
+    /**
+     * 当前套件支持的锁定能力。
+     */
+    locks?: LocksFacade;
+    /**
+     * 当前套件支持的提及定位能力。
+     */
+    mention?: MentionFacade;
+    /**
+     * 当前套件支持的内容写入能力。
+     */
+    content?: ContentFacade;
+    /**
+     * 当前套件支持的版本能力。
+     */
+    version?: VersionFacade;
+    /**
+     * 当前套件支持的演示能力。
+     */
+    presentation?: PresentationFacade;
+    /**
+     * 当前套件支持的选区能力。
+     */
+    selection?: DocsSelectionFacade | PresentationSelectionFacade;
+    /**
+     * 当前套件支持的搜索能力。
+     */
+    search?: DocsSearchFacade;
+    /**
+     * 当前套件支持的目录能力。
+     */
+    TOCs?: DocsTOCsFacade;
+    /**
+     * 当前套件支持的侧边栏能力。
+     */
+    sidebar?: DocsSidebarFacade;
+    /**
+     * 当前套件支持的表格集合能力。
+     */
+    tables?: DocsTablesFacade;
+    /**
+     * 当前套件支持的设置能力。
+     */
+    settings?: DocsSettingsFacade;
+    /**
+     * 当前套件支持的工作簿能力。
+     */
+    workbook?: SheetWorkbookFacade;
+    /**
+     * 当前套件支持的当前工作表能力。
+     */
+    activeSheet?: SheetWorksheetFacade;
+    /**
+     * 当前套件支持的图表能力。
+     */
+    charts?: SheetChartsFacade;
+    /**
+     * 当前套件支持的多选区能力。
+     */
+    selections?: SheetSelectionsFacade;
+    /**
+     * 当前套件支持的幻灯片集合能力。
      */
-    presentation?: Presentation.Editor;
+    slides?: PresentationSlidesFacade;
+    /**
+     * 当前套件支持的文本能力。
+     */
+    text?: PresentationTextFacade;
+    /**
+     * 当前套件支持的缩放能力。
+     */
+    zoom?: PresentationZoomFacade;
+    /**
+     * 当前套件支持的事件订阅能力。
+     */
+    eventSubscription?: PresentationEventSubscriptionFacade;
+    /**
+     * 当前套件支持的批量变更能力。
+     */
+    batchChanges?: <T>(callback: () => T | Promise<T>) => Promise<Awaited<T>>;
+    /**
+     * 当前套件支持的导出能力。
+     */
+    export?: (type: string) => Promise<void>;
+    /**
+     * 当前套件支持的打印能力。
+     */
+    print?: () => Promise<void>;
+    /**
+     * 当前套件支持的聚焦能力。
+     */
+    setFocus?: (isFocus: boolean) => Promise<void>;
     /**
      * 应用表格编辑器实例
      * @deprecated - 用 `sdk.getEditor<T>()` 替代
@@ -113,6 +195,8 @@ export declare class OfficeSDK extends TinyEmitter {
     private headerBarsVisible;
     private readonly headerBarsCommands;
     private readonly headerBarsCommandOverrides;
+    private readonly slashMenuCallbacks;
+    private readonly editorFacadeCallbacks;
     private readonly headerBarsCommandRefs;
     private headerBarsTitleChangeHandler?;
     private headerBarsTitleChangeSubscribed;
@@ -127,6 +211,36 @@ export declare class OfficeSDK extends TinyEmitter {
     constructor(options: OfficeSDKOptions);
     get fileType(): FileType;
     get readyState(): ReadyState;
+    /**
+     * 判断当前实例是否应该向 iframe 暴露 slashMenu。
+     * 输入：无，读取当前文件类型与 startParams.type 提示。
+     * 输出：仅在明确是 docs，或尚未拿到文件类型且没有明确非 docs 提示时返回 true。
+     */
+    private shouldExposeSlashMenu;
+    /**
+     * 从 startParams 中提取文件类型提示。
+     * 输入：无。
+     * 输出：标准化后的 type 字符串；若未配置则返回 undefined。
+     */
+    private getSlashMenuTypeHint;
+    /**
+     * 将宿主传入的 slashMenu 转成可跨 iframe 传输的纯数据结构。
+     * 输入：当前实例上的 `OfficeSDKOptions.slashMenu`。
+     * 输出：去除真实函数、附带 callbackId 的 slashMenu 配置；不适用时返回 undefined。
+     */
+    private createSerializedSlashMenu;
+    /**
+     * 递归序列化 slashMenu 菜单项，并登记 button callback。
+     * 输入：菜单项数组与当前递归路径。
+     * 输出：仅包含结构化克隆安全字段的菜单项数组。
+     */
+    private serializeSlashMenuItems;
+    /**
+     * 为 slashMenu button callback 生成稳定 id 并注册到内存表。
+     * 输入：菜单路径与可选 callback。
+     * 输出：注册后的 callbackId；若未提供 callback 则返回 undefined。
+     */
+    private registerSlashMenuCallback;
     getEditor<T extends BaseEditor | Document.Editor | DocumentPro.Editor | Presentation.Editor | Spreadsheet.Editor | Form.Editor | Flowchart.Editor | Table.Editor = BaseEditor>(): T;
     /**
      * 更新鉴权 signature 和 token
@@ -158,6 +272,10 @@ export declare class OfficeSDK extends TinyEmitter {
      * 比如受浏览器限制无法发出 postMessage() 时，Promise 将会一直 pending。
      */
     init(): Promise<void>;
+    /**
+     * 等待 SDK 进入 Ready 状态。若已 ready，则直接返回。
+     */
+    ready(): Promise<void>;
     private initIframe;
     private runPreloadHandshake;
     private initChannel;
@@ -174,10 +292,60 @@ export declare class OfficeSDK extends TinyEmitter {
     private ensureHeaderBarsTitleChangeSubscription;
     private invokeHeaderBars;
     private syncHeaderBarsCommands;
+    private createHeaderBarsHost;
     private applyHeaderBarsChanged;
     private syncHeaderBarsVisible;
     private setHeaderBarsVisible;
     private getHeaderBarsCommandRef;
+    /**
+     * 注册一个可供 iframe 侧反向调用的 facade callback。
+     * 输入：宿主侧 callback。
+     * 输出：供跨窗协议使用的 callbackId。
+     */
+    private registerEditorFacadeCallback;
+    /**
+     * 注销已注册的 facade callback。
+     * 输入：callbackId。
+     * 输出：无。
+     */
+    private unregisterEditorFacadeCallback;
+    /**
+     * 创建基于 method-path 的模块 facade。
+     * 输入：模块前缀与少量自定义实现覆盖。
+     * 输出：其余方法按 `${prefix}.${method}` 自动桥接。
+     */
+    private createEditorFacadeModule;
+    /**
+     * 为 value-based locator 创建本地对象 facade。
+     * 输入：method-path 前缀、locator 和静态属性。
+     * 输出：支持继续远程调用的本地 facade。
+     */
+    private createValueObjectFacade;
+    /**
+     * 注册一个基于 callback 协议的 listener。
+     * 输入：注册方法名与监听器。
+     * 输出：供宿主侧取消注册的函数。
+     */
+    private registerEditorFacadeListener;
+    private installRootFacade;
+    /**
+     * 重置根级能力命名空间，避免不同套件间字段残留。
+     * 输入：无。
+     * 输出：将所有 facade 字段置空。
+     */
+    private clearRootFacade;
+    /**
+     * 调用显式 editor facade method-path。
+     * 输入：method-path 与参数数组。
+     * 输出：返回 iframe 侧序列化结果。
+     */
+    private invokeEditorFacade;
+    /**
+     * 为结构化 facade 建立 editor 事件监听，并返回取消监听函数。
+     * 输入：事件名与监听器。
+     * 输出：返回一个可取消当前监听的函数。
+     */
+    private listenEditorEvent;
     private initEditor;
     private shouldHandleMessage;
     private getContainerRect;
@@ -419,6 +587,12 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
      * 控制 headerbar 组件是否展示，false 表示隐藏。
      */
     headerBarsVisible?: boolean;
+    /**
+     * docs 斜杠菜单配置。
+     * 仅 docs 文件类型生效；`button.callback` 实际运行在宿主页，
+     * 会在 iframe 内点击菜单按钮后通过 postMessage/channel 回调触发。
+     */
+    slashMenu?: SlashMenuOptions;
     /**
      * 是否显示内置的加载动画，只在静态资源加载到编辑器渲染这个阶段显示
      */

package/dist/OfficeSDK.facade.d.ts

@@ -0,0 +1,15 @@
+import { FileType } from 'weboffice-js-sdk-shared';
+import type { OfficeSDKRootFacadeState } from './OfficeSDK.facade.types';
+type EditorFacadeCallback = (...args: unknown[]) => unknown | Promise<unknown>;
+interface FacadeHost {
+    fileType: FileType;
+    invokeEditorFacade<T>(method: string, args?: unknown[]): Promise<T>;
+    listenEditorEvent<T>(event: string, listener: (payload: T) => void): () => void;
+    createEditorFacadeModule<T extends object>(prefix: string, staticFields?: Partial<T>): T;
+    createValueObjectFacade<T extends object>(prefix: string, locator: Record<string, unknown>, staticFields: Partial<T>): T;
+    registerEditorFacadeListener<T>(method: string, listener: (payload: T) => void): () => void;
+    registerEditorFacadeCallback(callback: EditorFacadeCallback): string;
+    unregisterEditorFacadeCallback(callbackId: string): void;
+}
+export declare function buildRootFacadeState(host: FacadeHost): OfficeSDKRootFacadeState;
+export {};