@univerjs/sheets 0.5.4 → 0.5.5-nightly.202501201336

package/lib/types/facade/f-univer.d.ts

@@ -87,6 +87,20 @@ export interface IFUniverSheetsMixin {
         workbook: FWorkbook;
         worksheet: FWorksheet;
     }>;
+    /**
+     * Get the active sheet.
+     * @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} The active sheet.
+     * @example
+     * ```ts
+     * const target = univerAPI.getActiveSheet();
+     * if (!target) return;
+     * const { workbook, worksheet } = target;
+     * ```
+     */
+    getActiveSheet(): Nullable<{
+        workbook: FWorkbook;
+        worksheet: FWorksheet;
+    }>;
 }
 export declare class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
     getCommandSheetTarget(commandInfo: ICommandInfo<object>): Nullable<{
@@ -108,6 +122,22 @@ export declare class FUniverSheetsMixin extends FUniver implements IFUniverSheet
     getPermission(): FPermission;
     onUniverSheetCreated(callback: (workbook: FWorkbook) => void): IDisposable;
     newDefinedName(): FDefinedNameBuilder;
+    getActiveSheet(): Nullable<{
+        workbook: FWorkbook;
+        worksheet: FWorksheet;
+    }>;
+    private _fireBeforeActiveSheetChange;
+    private _fireActiveSheetChanged;
+    private _fireBeforeSheetDelete;
+    private _fireSheetDeleted;
+    private _fireBeforeSheetMove;
+    private _fireSheetMoved;
+    private _fireBeforeSheetNameChange;
+    private _fireSheetNameChanged;
+    private _fireBeforeSheetTabColorChange;
+    private _fireSheetTabColorChanged;
+    private _fireBeforeSheetHideChange;
+    private _fireSheetHideChanged;
 }
 declare module '@univerjs/core' {
     interface FUniver extends IFUniverSheetsMixin {

package/lib/types/facade/f-workbook.d.ts

@@ -1,4 +1,4 @@
-import { CommandListener, CustomData, IDisposable, IEventParamConfig, IRange, IWorkbookData, LocaleType, Workbook, FBaseInitialable, FEnum, FEventName, ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService, LocaleService } from '@univerjs/core';
+import { CommandListener, CustomData, IDisposable, IRange, IWorkbookData, LocaleType, Workbook, FBaseInitialable, ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService, LocaleService } from '@univerjs/core';
 import { ISetDefinedNameMutationParam, IDefinedNamesService } from '@univerjs/engine-formula';
 import { RangeThemeStyle, SheetsSelectionsService } from '@univerjs/sheets';
 import { FontLine as _FontLine, FRange } from './f-range';
@@ -18,39 +18,17 @@ export declare class FWorkbook extends FBaseInitialable {
     protected readonly _definedNamesService: IDefinedNamesService;
     readonly id: string;
     constructor(_workbook: Workbook, _injector: Injector, _resourceLoaderService: IResourceLoaderService, _selectionManagerService: SheetsSelectionsService, _univerInstanceService: IUniverInstanceService, _commandService: ICommandService, _permissionService: IPermissionService, _logService: ILogService, _localeService: LocaleService, _definedNamesService: IDefinedNamesService);
-    getWorkbook(): Workbook;
-    private _eventRegistry;
-    private _ensureEventRegistry;
     /**
-     * Add an event listener
-     * @param event key of event
-     * @param callback callback when event triggered
-     * @returns {Disposable} The Disposable instance, for remove the listener
+     * Get the Workbook instance.
+     * @returns {Workbook} The Workbook instance.
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.event.UnitCreated, (params) => {
-     *     console.log('unit created', params);
-     * });
-     * ```
-     */
-    addEvent(event: keyof IEventParamConfig, callback: (params: IEventParamConfig[typeof event]) => void): IDisposable;
-    /**
-     * Fire an event, used in internal only.
-     * @param event {string} key of event
-     * @param params {any} params of event
-     * @returns {boolean} should cancel
-     * @example
-     * ```ts
-     * this.fireEvent(univerAPI.event.UnitCreated, params);
+     * // The code below gets the Workbook instance
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const workbook = activeSpreadsheet.getWorkbook();
      * ```
      */
-    protected fireEvent<T extends keyof IEventParamConfig>(event: T, params: IEventParamConfig[T]): boolean | undefined;
-    addUIEvent(event: keyof IEventParamConfig, _callback: (params: IEventParamConfig[typeof event]) => void): void;
-    get Enum(): FEnum;
-    /**
-     * @returns {FEventName} The event name.
-     */
-    get Event(): FEventName;
+    getWorkbook(): Workbook;
     /**
      * Get the id of the workbook.
      * @returns {string} The id of the workbook.
@@ -76,6 +54,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Set the name of the workbook.
      * @param {string} name The new name of the workbook.
+     * @returns {void}
      * @example
      * ```ts
      * // The code below sets the name of the workbook
@@ -97,8 +76,14 @@ export declare class FWorkbook extends FBaseInitialable {
     save(): IWorkbookData;
     /**
      * @deprecated use 'save' instead.
-     * @returns {*}  {IWorkbookData} Workbook snapshot data
+     * @returns {IWorkbookData} Workbook snapshot data
      * @memberof FWorkbook
+     * @example
+     * ```ts
+     * // The code below saves the workbook snapshot data
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const snapshot = activeSpreadsheet.getSnapshot();
+     * ```
      */
     getSnapshot(): IWorkbookData;
     /**
@@ -125,10 +110,10 @@ export declare class FWorkbook extends FBaseInitialable {
     getSheets(): FWorksheet[];
     /**
      * Create a new worksheet and returns a handle to it.
-     * @param name Name of the new sheet
-     * @param rows How may rows would the new sheet have
-     * @param column How many columns would the new sheet have
-     * @returns The new created sheet
+     * @param {string} name Name of the new sheet
+     * @param {number} rows How many rows would the new sheet have
+     * @param {number} column How many columns would the new sheet have
+     * @returns {FWorksheet} The new created sheet
      * @example
      * ```ts
      * // The code below creates a new sheet
@@ -139,8 +124,8 @@ export declare class FWorkbook extends FBaseInitialable {
     create(name: string, rows: number, column: number): FWorksheet;
     /**
      * Get a worksheet by sheet id.
-     * @param sheetId The id of the sheet to get.
-     * @returns The worksheet with given sheet id
+     * @param {string} sheetId The id of the sheet to get.
+     * @returns {FWorksheet | null} The worksheet with given sheet id
      * @example
      * ```ts
      * // The code below gets a worksheet by sheet id
@@ -151,8 +136,8 @@ export declare class FWorkbook extends FBaseInitialable {
     getSheetBySheetId(sheetId: string): FWorksheet | null;
     /**
      * Get a worksheet by sheet name.
-     * @param name The name of the sheet to get.
-     * @returns The worksheet with given sheet name
+     * @param {string} name The name of the sheet to get.
+     * @returns {FWorksheet | null} The worksheet with given sheet name
      * @example
      * ```ts
      * // The code below gets a worksheet by sheet name
@@ -163,8 +148,8 @@ export declare class FWorkbook extends FBaseInitialable {
     getSheetByName(name: string): FWorksheet | null;
     /**
      * Sets the given worksheet to be the active worksheet in the workbook.
-     * @param sheet The worksheet to set as the active worksheet.
-     * @returns The active worksheet
+     * @param {FWorksheet | string} sheet The worksheet to set as the active worksheet.
+     * @returns {FWorksheet} The active worksheet
      * @example
      * ```ts
      * // The code below sets the given worksheet to be the active worksheet
@@ -173,12 +158,12 @@ export declare class FWorkbook extends FBaseInitialable {
      * activeSpreadsheet.setActiveSheet(sheet);
      * ```
      */
-    setActiveSheet(sheet: FWorksheet): FWorksheet;
+    setActiveSheet(sheet: FWorksheet | string): FWorksheet;
     /**
      * Inserts a new worksheet into the workbook.
      * Using a default sheet name. The new sheet becomes the active sheet
-     * @param sheetName - (optional) The name of the new sheet
-     * @returns The new sheet
+     * @param {string} [sheetName] The name of the new sheet
+     * @returns {FWorksheet} The new sheet
      * @example
      * ```ts
      * // The code below inserts a new sheet into the workbook
@@ -193,7 +178,7 @@ export declare class FWorkbook extends FBaseInitialable {
     insertSheet(sheetName?: string): FWorksheet;
     /**
      * Deletes the specified worksheet.
-     * @param sheet The worksheet to delete.
+     * @param {FWorksheet | string} sheet The worksheet to delete.
      * @returns {boolean} True if the worksheet was deleted, false otherwise.
      * @example
      * ```ts
@@ -203,7 +188,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * activeSpreadsheet.deleteSheet(sheet);
      * ```
      */
-    deleteSheet(sheet: FWorksheet): boolean;
+    deleteSheet(sheet: FWorksheet | string): boolean;
     /**
      * Undo the last action.
      * @returns {FWorkbook} A promise that resolves to true if the undo was successful, false otherwise.
@@ -217,7 +202,7 @@ export declare class FWorkbook extends FBaseInitialable {
     undo(): FWorkbook;
     /**
      * Redo the last undone action.
-     * @returns A promise that resolves to true if the redo was successful, false otherwise.
+     * @returns {FWorkbook} A promise that resolves to true if the redo was successful, false otherwise.
      * @example
      * ```ts
      * // The code below redoes the last undone action
@@ -234,7 +219,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Register a callback that will be triggered before invoking a command targeting the Univer sheet.
      * @param {onBeforeCommandExecuteCallback} callback the callback.
-     * @returns A function to dispose the listening.
+     * @returns {IDisposable} A function to dispose the listening.
      * @example
      * ```ts
      * // The code below registers a callback that will be triggered before invoking a command targeting the Univer sheet
@@ -253,7 +238,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Register a callback that will be triggered when a command is invoked targeting the Univer sheet.
      * @param {onCommandExecutedCallback} callback the callback.
-     * @returns A function to dispose the listening.
+     * @returns {IDisposable} A function to dispose the listening.
      * @example
      * ```ts
      * // The code below registers a callback that will be triggered when a command is invoked targeting the Univer sheet
@@ -261,6 +246,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * activeSpreadsheet.onCommandExecuted((command) => {
      *   console.log('Command executed:', command);
      * });
+     * ```
      */
     onCommandExecuted(callback: CommandListener): IDisposable;
     /**
@@ -271,7 +257,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Register a callback that will be triggered when the selection changes.
      * @param {onSelectionChangeCallback} callback The callback.
-     * @returns A function to dispose the listening
+     * @returns {IDisposable} A function to dispose the listening
      */
     onSelectionChange(callback: (selections: IRange[]) => void): IDisposable;
     /**
@@ -282,13 +268,13 @@ export declare class FWorkbook extends FBaseInitialable {
     setEditable(value: boolean): FWorkbook;
     /**
      * Sets the selection region for active sheet.
-     * @param range The range to set as the active selection.
+     * @param {FRange} range The range to set as the active selection.
      * @returns {FWorkbook} FWorkbook instance
      */
     setActiveRange(range: FRange): FWorkbook;
     /**
      * Returns the selected range in the active sheet, or null if there is no active range.
-     * @returns the active range
+     * @returns {FRange | null} The active range
      */
     getActiveRange(): FRange | null;
     /**
@@ -320,7 +306,6 @@ export declare class FWorkbook extends FBaseInitialable {
      * @returns {FWorksheet} The duplicated worksheet
      * @example
      * ```ts
-     * // The code below duplicates the active sheet
      *  const activeSpreadsheet = univerAPI.getActiveWorkbook();
      *  activeSpreadsheet.duplicateActiveSheet();
      * ```
@@ -328,7 +313,7 @@ export declare class FWorkbook extends FBaseInitialable {
     duplicateActiveSheet(): FWorksheet;
     /**
      * Get the number of sheets in the workbook.
-     * @returns The number of sheets in the workbook
+     * @returns {number} The number of sheets in the workbook
      * @example
      * ```ts
      * // The code below gets the number of sheets in the workbook
@@ -458,6 +443,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Insert a defined name by builder param.
      * @param {ISetDefinedNameMutationParam} param The param to insert the defined name
+     * @returns {void}
      * @example
      * ```ts
      * // The code below inserts a defined name by builder param
@@ -471,6 +457,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Update the defined name with the given name.
      * @param {ISetDefinedNameMutationParam} param The param to insert the defined name
+     * @returns {void}
      * @example
      * ```ts
      * // The code below updates the defined name with the given name
@@ -495,7 +482,8 @@ export declare class FWorkbook extends FBaseInitialable {
     getRegisteredRangeThemes(): string[];
     /**
      * Register a custom range theme style.
-     * @param rangeThemeStyle
+     * @param {RangeThemeStyle} rangeThemeStyle The range theme style to register
+     * @returns {void}
      * @example
      * ```ts
      * // import {RangeThemeStyle} from '@univerjs/sheets';
@@ -512,7 +500,8 @@ export declare class FWorkbook extends FBaseInitialable {
     registerRangeTheme(rangeThemeStyle: RangeThemeStyle): void;
     /**
      * Unregister a custom range theme style.
-     * @param themeName
+     * @param {string} themeName The name of the theme to unregister
+     * @returns {void}
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();