@univerjs/sheets 0.5.4 → 0.5.5-experimental.20250123-34738ff

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

@@ -3,7 +3,8 @@ import { ISelectionWithStyle } from '@univerjs/sheets';
 import { FRange } from './f-range';
 import { FWorksheet } from './f-worksheet';
 /**
- * @description Represents the active selection in the sheet.
+ * Represents the active selection in the sheet.
+ *
  * @example
  * ```ts
  * const fWorkbook = univerAPI.getActiveWorkbook()
@@ -12,6 +13,7 @@ import { FWorksheet } from './f-worksheet';
  * const activeRange = fSelection.getActiveRange();
  * console.log(activeRange);
  * ```
+ * @hideconstructor
  */
 export declare class FSelection {
     private readonly _workbook;
@@ -22,16 +24,40 @@ export declare class FSelection {
     /**
      * Represents the active selection in the sheet. Which means the selection contains the active cell.
      * @returns {FRange | null} The active selection.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fSelection = fWorksheet.getSelection();
+     * const activeRange = fSelection.getActiveRange();
+     * console.log(activeRange);
+     * ```
      */
     getActiveRange(): FRange | null;
     /**
      * Represents the active selection list in the sheet.
      * @returns {FRange[]} The active selection list.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fSelection = fWorksheet.getSelection();
+     * const activeRangeList = fSelection.getActiveRangeList();
+     * console.log(activeRangeList);
+     * ```
      */
     getActiveRangeList(): FRange[];
     /**
      * Represents the current select cell in the sheet.
      * @returns {ISelectionCell} The current select cell info.Pay attention to the type of the return value.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fSelection = fWorksheet.getSelection();
+     * const currentCell = fSelection.getCurrentCell();
+     * console.log(currentCell);
+     * ```
      */
     getCurrentCell(): Nullable<ISelectionCell>;
     /**

package/lib/types/facade/f-sheet-hooks.d.ts

@@ -1,4 +1,7 @@
 import { FBase, Injector } from '@univerjs/core';
+/**
+ * @hideconstructor
+ */
 export declare class FSheetHooks extends FBase {
     protected readonly _injector: Injector;
     constructor(_injector: Injector);

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

@@ -3,6 +3,9 @@ import { FWorksheet } from './f-worksheet';
 import { FDefinedNameBuilder } from './f-defined-name';
 import { FPermission } from './f-permission';
 import { FWorkbook } from './f-workbook';
+/**
+ * @ignore
+ */
 export interface IFUniverSheetsMixin {
     /**
      * @deprecated use `univerAPI.createWorkbook` instead.
@@ -77,9 +80,9 @@ export interface IFUniverSheetsMixin {
      * @example
      * ```ts
      * univerAPI.addEvent(univerAPI.event.CommandExecuted, (commandInfo) => {
-     *      const target = univerAPI.getCommandSheetTarget(commandInfo);
-     *      if (!target) return;
-     *      const { workbook, worksheet } = target;
+     *   const target = univerAPI.getCommandSheetTarget(commandInfo);
+     *   if (!target) return;
+     *   const { workbook, worksheet } = target;
      * });
      * ```
      */
@@ -87,6 +90,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<{
@@ -98,6 +115,9 @@ export declare class FUniverSheetsMixin extends FUniver implements IFUniverSheet
         worksheet: FWorksheet;
     }>;
     private _initWorkbookEvent;
+    /**
+     * @ignore
+     */
     _initialize(injector: Injector): void;
     createUniverSheet(data: Partial<IWorkbookData>): FWorkbook;
     createWorkbook(data: Partial<IWorkbookData>): FWorkbook;
@@ -108,6 +128,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,10 +1,14 @@
-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 { IRangeThemeStyleJSON, RangeThemeStyle, SheetsSelectionsService } from '@univerjs/sheets';
 import { FontLine as _FontLine, FRange } from './f-range';
 import { FDefinedName } from './f-defined-name';
 import { FPermission } from './f-permission';
 import { FWorksheet } from './f-worksheet';
+/**
+ * Facade API object bounded to a workbook. It provides a set of methods to interact with the workbook.
+ * @hideconstructor
+ */
 export declare class FWorkbook extends FBaseInitialable {
     protected readonly _workbook: Workbook;
     protected readonly _injector: Injector;
@@ -18,39 +22,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
-     * @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
+     * Get the Workbook instance.
+     * @returns {Workbook} The Workbook instance.
      * @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 +58,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 +80,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 +114,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 +128,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 +140,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 +152,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 +162,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 +182,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 +192,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 +206,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,13 +223,13 @@ 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
      * const activeSpreadsheet = univerAPI.getActiveWorkbook();
      * activeSpreadsheet.onBeforeCommandExecute((command) => {
-     *    console.log('Command executed:', command);
+     *   console.log('Command executed:', command);
      * });
      * ```
      */
@@ -253,7 +242,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 +250,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * activeSpreadsheet.onCommandExecuted((command) => {
      *   console.log('Command executed:', command);
      * });
+     * ```
      */
     onCommandExecuted(callback: CommandListener): IDisposable;
     /**
@@ -271,7 +261,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 +272,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 +310,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 +317,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 +447,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 +461,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,16 +486,17 @@ 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';
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const rangeThemeStyle = new RangeThemeStyle('MyTheme');
      * rangeThemeStyle.setSecondRowStyle({
-     *    bg: {
-     *       rgb: 'rgb(214,231,241)',
-     *    },
+     *   bg: {
+     *     rgb: 'rgb(214,231,241)',
+     *   },
      * });
      * fWorkbook.registerRangeTheme(rangeThemeStyle);
      * ```
@@ -512,7 +504,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();
@@ -520,6 +513,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     unregisterRangeTheme(themeName: string): void;
+    createRangeThemeStyle(themeName: string, themeStyleJson?: Omit<IRangeThemeStyleJSON, 'name'>): RangeThemeStyle;
     /**
      * Set custom metadata of workbook
      * @param {CustomData | undefined} custom custom metadata
@@ -542,6 +536,9 @@ export declare class FWorkbook extends FBaseInitialable {
      */
     getCustomMetadata(): CustomData | undefined;
 }
+/**
+ * @ignore
+ */
 export declare namespace FWorkbook {
     type FontLine = _FontLine;
     type FontStyle = _FontLine;