@univerjs/sheets 0.5.3 → 0.5.4-experimental.20250114-7c09c35

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

@@ -1,39 +1,43 @@
-import { IDisposable, Injector, IWorkbookData, FUniver } from '@univerjs/core';
+import { ICommandInfo, IDisposable, Injector, IWorkbookData, Nullable, FUniver } from '@univerjs/core';
+import { FWorksheet } from './f-worksheet';
 import { FDefinedNameBuilder } from './f-defined-name';
 import { FPermission } from './f-permission';
 import { FWorkbook } from './f-workbook';
 export interface IFUniverSheetsMixin {
+    /**
+     * @deprecated use `univerAPI.createWorkbook` instead.
+     */
+    createUniverSheet(data: Partial<IWorkbookData>): FWorkbook;
     /**
      * Create a new spreadsheet and get the API handler of that spreadsheet.
-     *
      * @param {Partial<IWorkbookData>} data The snapshot of the spreadsheet.
      * @returns {FWorkbook} FWorkbook API instance.
      * @example
      * ```ts
-     * univerAPI.createUniverSheet({ id: 'Sheet1', name: 'Sheet1' });
+     * univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' });
      * ```
      */
-    createUniverSheet(data: Partial<IWorkbookData>): FWorkbook;
+    createWorkbook(data: Partial<IWorkbookData>): FWorkbook;
     /**
      * Get the currently focused Univer spreadsheet.
      * @returns {FWorkbook | null} The currently focused Univer spreadsheet.
      * @example
      * ```ts
-     * univerAPI.getActiveUniverSheet();
+     * univerAPI.getActiveWorkbook();
      * ```
      */
-    getActiveUniverSheet(): FWorkbook | null;
+    getActiveWorkbook(): FWorkbook | null;
     /**
-     * @deprecated use `getActiveUniverSheet` as instead.
+     * @deprecated use `univerAPI.getActiveWorkbook` instead
      */
-    getActiveWorkbook(): FWorkbook | null;
+    getActiveUniverSheet(): FWorkbook | null;
     /**
      * Get the spreadsheet API handler by the spreadsheet id.
-     *
      * @param {string} id The spreadsheet id.
      * @returns {FWorkbook | null} The spreadsheet API instance.
      */
     getUniverSheet(id: string): FWorkbook | null;
+    getWorkbook(id: string): FWorkbook | null;
     /**
      * Get the PermissionInstance.
      * @deprecated This function is deprecated and will be removed in version 0.6.0. Please use the function with the same name on the `FWorkbook` instance instead.
@@ -46,20 +50,61 @@ export interface IFUniverSheetsMixin {
     /**
      * Create a new defined name builder.
      * @returns {FDefinedNameBuilder} - The defined name builder.
-     *
      * @example
      * ```ts
      * univerAPI.newDefinedName();
      * ```
      */
     newDefinedName(): FDefinedNameBuilder;
+    /**
+     * Get the target of the sheet.
+     * @param {string} unitId - The unitId of the sheet.
+     * @param {string} subUnitId - The subUnitId of the sheet.
+     * @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} - The target of the sheet.
+     * @example
+     * ```ts
+     * univerAPI.getSheetTarget('unitId', 'subUnitId');
+     * ```
+     */
+    getSheetTarget(unitId: string, subUnitId: string): Nullable<{
+        workbook: FWorkbook;
+        worksheet: FWorksheet;
+    }>;
+    /**
+     * Get the target of the sheet.
+     * @param {ICommandInfo<object>} commandInfo - The commandInfo of the command.
+     * @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} - The target of the sheet.
+     * @example
+     * ```ts
+     * univerAPI.addEvent(univerAPI.event.CommandExecuted, (commandInfo) => {
+     *      const target = univerAPI.getCommandSheetTarget(commandInfo);
+     *      if (!target) return;
+     *      const { workbook, worksheet } = target;
+     * });
+     * ```
+     */
+    getCommandSheetTarget(commandInfo: ICommandInfo<object>): Nullable<{
+        workbook: FWorkbook;
+        worksheet: FWorksheet;
+    }>;
 }
 export declare class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
+    getCommandSheetTarget(commandInfo: ICommandInfo<object>): Nullable<{
+        workbook: FWorkbook;
+        worksheet: FWorksheet;
+    }>;
+    getSheetTarget(unitId: string, subUnitId: string): Nullable<{
+        workbook: FWorkbook;
+        worksheet: FWorksheet;
+    }>;
+    private _initWorkbookEvent;
     _initialize(injector: Injector): void;
     createUniverSheet(data: Partial<IWorkbookData>): FWorkbook;
-    getActiveUniverSheet(): FWorkbook | null;
+    createWorkbook(data: Partial<IWorkbookData>): FWorkbook;
     getActiveWorkbook(): FWorkbook | null;
+    getActiveUniverSheet(): FWorkbook | null;
     getUniverSheet(id: string): FWorkbook | null;
+    getWorkbook(id: string): FWorkbook | null;
     getPermission(): FPermission;
     onUniverSheetCreated(callback: (workbook: FWorkbook) => void): IDisposable;
     newDefinedName(): FDefinedNameBuilder;

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

@@ -1,9 +1,9 @@
-import { CommandListener, IDisposable, IRange, IWorkbookData, LocaleType, Workbook, FBaseInitialable, ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService, LocaleService } from '@univerjs/core';
+import { CommandListener, CustomData, IDisposable, IEventParamConfig, IRange, IWorkbookData, LocaleType, Workbook, FBaseInitialable, FEnum, FEventName, 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';
 import { FDefinedName } from './f-defined-name';
 import { FPermission } from './f-permission';
-import { FRange } from './f-range';
 import { FWorksheet } from './f-worksheet';
 export declare class FWorkbook extends FBaseInitialable {
     protected readonly _workbook: Workbook;
@@ -18,6 +18,39 @@ 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
+     * @example
+     * ```ts
+     * this.fireEvent(univerAPI.event.UnitCreated, params);
+     * ```
+     */
+    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;
     /**
      * Get the id of the workbook.
      * @returns {string} The id of the workbook.
@@ -52,8 +85,8 @@ export declare class FWorkbook extends FBaseInitialable {
      */
     setName(name: string): void;
     /**
-     * save workbook snapshot data, including conditional formatting, data validation, and other plugin data.
-     * @return Workbook snapshot data
+     * Save workbook snapshot data, including conditional formatting, data validation, and other plugin data.
+     * @returns {IWorkbookData} Workbook snapshot data
      * @example
      * ```ts
      * // The code below saves the workbook snapshot data
@@ -64,13 +97,13 @@ export declare class FWorkbook extends FBaseInitialable {
     save(): IWorkbookData;
     /**
      * @deprecated use 'save' instead.
-     * @return {*}  {IWorkbookData} Workbook snapshot data
+     * @returns {*}  {IWorkbookData} Workbook snapshot data
      * @memberof FWorkbook
      */
     getSnapshot(): IWorkbookData;
     /**
      * Get the active sheet of the workbook.
-     * @returns The active sheet of the workbook
+     * @returns {FWorksheet} The active sheet of the workbook
      * @example
      * ```ts
      * // The code below gets the active sheet of the workbook
@@ -81,7 +114,7 @@ export declare class FWorkbook extends FBaseInitialable {
     getActiveSheet(): FWorksheet;
     /**
      * Gets all the worksheets in this workbook
-     * @returns An array of all the worksheets in the workbook
+     * @returns {FWorksheet[]} An array of all the worksheets in the workbook
      * @example
      * ```ts
      * // The code below gets all the worksheets in the workbook
@@ -107,7 +140,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Get a worksheet by sheet id.
      * @param sheetId The id of the sheet to get.
-     * @return The worksheet with given sheet id
+     * @returns The worksheet with given sheet id
      * @example
      * ```ts
      * // The code below gets a worksheet by sheet id
@@ -161,6 +194,7 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Deletes the specified worksheet.
      * @param sheet The worksheet to delete.
+     * @returns {boolean} True if the worksheet was deleted, false otherwise.
      * @example
      * ```ts
      * // The code below deletes the specified worksheet
@@ -172,7 +206,7 @@ export declare class FWorkbook extends FBaseInitialable {
     deleteSheet(sheet: FWorksheet): boolean;
     /**
      * Undo the last action.
-     * @returns A promise that resolves to true if the undo was successful, false otherwise.
+     * @returns {FWorkbook} A promise that resolves to true if the undo was successful, false otherwise.
      * @example
      * ```ts
      * // The code below undoes the last action
@@ -231,7 +265,6 @@ export declare class FWorkbook extends FBaseInitialable {
     onCommandExecuted(callback: CommandListener): IDisposable;
     /**
      * Callback for selection changes.
-     *
      * @callback onSelectionChangeCallback
      * @param {IRange[]} selections The new selection.
      */
@@ -244,13 +277,15 @@ export declare class FWorkbook extends FBaseInitialable {
     /**
      * Used to modify the editing permissions of the workbook. When the value is false, editing is not allowed.
      * @param {boolean} value  editable value want to set
+     * @returns {FWorkbook} FWorkbook instance
      */
-    setEditable(value: boolean): void;
+    setEditable(value: boolean): FWorkbook;
     /**
-     * Sets the active selection region for this sheet.
+     * Sets the selection region for active sheet.
      * @param range The range to set as the active selection.
+     * @returns {FWorkbook} FWorkbook instance
      */
-    setActiveRange(range: FRange): void;
+    setActiveRange(range: FRange): FWorkbook;
     /**
      * Returns the selected range in the active sheet, or null if there is no active range.
      * @returns the active range
@@ -258,6 +293,7 @@ export declare class FWorkbook extends FBaseInitialable {
     getActiveRange(): FRange | null;
     /**
      * Deletes the currently active sheet.
+     * @returns {boolean} true if the sheet was deleted, false otherwise
      * @example
      * ```ts
      * // The code below deletes the currently active sheet and stores the new active
@@ -312,9 +348,15 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     getLocale(): LocaleType;
+    /**
+     * @deprecated use setSpreadsheetLocale instead.
+     * @param {LocaleType} locale - The locale to set
+     */
+    setLocale(locale: LocaleType): void;
     /**
      * Set the locale of the workbook.
      * @param {LocaleType} locale The locale to set
+     * @returns {FWorkbook} This workbook, for chaining
      * @example
      * ```ts
      * // The code below sets the locale of the workbook
@@ -322,7 +364,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * activeSpreadsheet.setLocale(LocaleType.EN_US);
      * ```
      */
-    setLocale(locale: LocaleType): void;
+    setSpreadsheetLocale(locale: LocaleType): FWorkbook;
     /**
      * Get the URL of the workbook.
      * @returns {string} The URL of the workbook
@@ -362,7 +404,6 @@ export declare class FWorkbook extends FBaseInitialable {
     moveActiveSheet(index: number): FWorkbook;
     /**
      * Get the PermissionInstance.
-     *
      * @returns {FPermission} - The PermissionInstance.
      */
     getPermission(): FPermission;
@@ -393,6 +434,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * Insert a defined name.
      * @param {string} name The name of the defined name to insert
      * @param {string} formulaOrRefString The formula(=sum(A2:b10)) or reference(A1) string of the defined name to insert
+     * @returns {FWorkbook} The current FWorkbook instance
      * @example
      * ```ts
      * // The code below inserts a defined name
@@ -400,7 +442,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * activeSpreadsheet.insertDefinedName('MyDefinedName', 'Sheet1!A1');
      * ```
      */
-    insertDefinedName(name: string, formulaOrRefString: string): void;
+    insertDefinedName(name: string, formulaOrRefString: string): FWorkbook;
     /**
      * Delete the defined name with the given name.
      * @param {string} name The name of the defined name to delete
@@ -414,7 +456,7 @@ export declare class FWorkbook extends FBaseInitialable {
      */
     deleteDefinedName(name: string): boolean;
     /**
-     * insert a defined name by builder param
+     * Insert a defined name by builder param.
      * @param {ISetDefinedNameMutationParam} param The param to insert the defined name
      * @example
      * ```ts
@@ -453,6 +495,7 @@ export declare class FWorkbook extends FBaseInitialable {
     getRegisteredRangeThemes(): string[];
     /**
      * Register a custom range theme style.
+     * @param rangeThemeStyle
      * @example
      * ```ts
      * // import {RangeThemeStyle} from '@univerjs/sheets';
@@ -469,6 +512,7 @@ export declare class FWorkbook extends FBaseInitialable {
     registerRangeTheme(rangeThemeStyle: RangeThemeStyle): void;
     /**
      * Unregister a custom range theme style.
+     * @param themeName
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -476,4 +520,30 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     unregisterRangeTheme(themeName: string): void;
+    /**
+     * Set custom metadata of workbook
+     * @param {CustomData | undefined} custom custom metadata
+     * @returns {FWorkbook} FWorkbook
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.setCustomMetadata({ key: 'value' });
+     * ```
+     */
+    setCustomMetadata(custom: CustomData | undefined): FWorkbook;
+    /**
+     * Get custom metadata of workbook
+     * @returns {CustomData | undefined} custom metadata
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const custom = fWorkbook.getCustomMetadata();
+     * ```
+     */
+    getCustomMetadata(): CustomData | undefined;
+}
+export declare namespace FWorkbook {
+    type FontLine = _FontLine;
+    type FontStyle = _FontLine;
+    type FontWeight = _FontLine;
 }