@univerjs/sheets 0.5.1 → 0.5.2

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

@@ -1,11 +1,81 @@
-import { Workbook, Worksheet, Injector } from '@univerjs/core';
+import { Direction, ISelectionCell, Nullable, Workbook, Worksheet, Injector } from '@univerjs/core';
 import { ISelectionWithStyle } from '@univerjs/sheets';
 import { FRange } from './f-range';
+import { FWorksheet } from './f-worksheet';
+/**
+ * @description Represents the active selection in the sheet.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook()
+ * const fWorksheet = fWorkbook.getActiveSheet()
+ * const fSelection = fWorksheet.getSelection();
+ * const activeRange = fSelection.getActiveRange();
+ * console.log(activeRange);
+ * ```
+ */
 export declare class FSelection {
     private readonly _workbook;
     private readonly _worksheet;
     private readonly _selections;
     private readonly _injector;
     constructor(_workbook: Workbook, _worksheet: Worksheet, _selections: Readonly<ISelectionWithStyle[]>, _injector: Injector);
+    /**
+     * Represents the active selection in the sheet. Which means the selection contains the active cell.
+     * @returns {FRange | null} The active selection.
+     */
     getActiveRange(): FRange | null;
+    /**
+     * Represents the active selection list in the sheet.
+     * @returns {FRange[]} The active selection list.
+     */
+    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.
+     */
+    getCurrentCell(): Nullable<ISelectionCell>;
+    /**
+     * Returns the active sheet in the spreadsheet.
+     * @returns {FWorksheet} The active sheet in the spreadsheet.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fSelection = fWorksheet.getSelection();
+     * const activeSheet = fSelection.getActiveSheet();
+     * console.log(activeSheet.equalTo(fWorksheet)); // true
+     * ```
+     */
+    getActiveSheet(): FWorksheet;
+    /**
+     * Update the primary cell in the selection. if the primary cell not exists in selections, add it to the selections and clear the old selections.
+     * @param {FRange} cell The new primary cell to update.
+     * @returns {FSelection} The new selection after updating the primary cell.Because the selection is immutable, the return value is a new selection.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fSelection = fWorksheet.getSelection();
+     * const cell = fWorksheet.getCell('A1');
+     * const newSelection = fSelection.updatePrimaryCell(cell);
+     * console.log(newSelection.getActiveRange().getA1Notation()); // A1
+     * ```
+     */
+    updatePrimaryCell(cell: FRange): Promise<FSelection>;
+    /**
+     *Get the next primary cell in the specified direction. If the primary cell not exists in selections, return null.
+     * @param {Direction} direction The direction to move the primary cell.The enum value is maybe one of the following: UP(0),RIGHT(1), DOWN(2), LEFT(3).
+     * @returns {FRange | null} The next primary cell in the specified direction.
+     * @example
+     * ```ts
+     * // import { Direction } from '@univerjs/core';
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * // make sure the active cell is A1 and selection is A1:C3
+     * const fSelection = fWorksheet.getSelection();
+     * const nextCell = fSelection.getNextDataRange(Direction.RIGHT);
+     * console.log(nextCell?.getA1Notation()); // B1
+     * ```
+     */
+    getNextDataRange(direction: Direction): FRange | null;
 }

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

@@ -1,4 +1,5 @@
-import { IWorkbookData, FUniver } from '@univerjs/core';
+import { IDisposable, IWorkbookData, FUniver } from '@univerjs/core';
+import { FDefinedNameBuilder } from './f-defined-name';
 import { FPermission } from './f-permission';
 import { FWorkbook } from './f-workbook';
 export interface IFUniverSheetsMixin {
@@ -24,15 +25,28 @@ export interface IFUniverSheetsMixin {
     getUniverSheet(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.
      * @returns {FPermission} - The PermissionInstance.
      */
     getPermission(): FPermission;
+    /**
+     * Register a callback that will be triggered when a Univer Sheet is created.
+     */
+    onUniverSheetCreated(callback: (workbook: FWorkbook) => void): IDisposable;
+    /**
+     * Create a new defined name builder.
+     * @returns {FDefinedNameBuilder} - The defined name builder.
+     */
+    newDefinedName(): FDefinedNameBuilder;
 }
-export declare class FUniverSheetsMixin extends FUniver {
+export declare class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
     createUniverSheet(data: Partial<IWorkbookData>): FWorkbook;
     getActiveWorkbook(): FWorkbook | null;
+    getUniverSheet(id: string): FWorkbook | null;
     getPermission(): FPermission;
+    onUniverSheetCreated(callback: (workbook: FWorkbook) => void): IDisposable;
+    newDefinedName(): FDefinedNameBuilder;
 }
 declare module '@univerjs/core' {
     interface FUniver extends IFUniverSheetsMixin {

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

@@ -1,5 +1,8 @@
-import { CommandListener, IDisposable, IRange, IWorkbookData, Workbook, FBase, ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService } from '@univerjs/core';
+import { CommandListener, IDisposable, IRange, IWorkbookData, LocaleType, Workbook, FBase, ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService, LocaleService } from '@univerjs/core';
+import { ISetDefinedNameMutationParam, IDefinedNamesService } from '@univerjs/engine-formula';
 import { SheetsSelectionsService } from '@univerjs/sheets';
+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 FBase {
@@ -11,28 +14,80 @@ export declare class FWorkbook extends FBase {
     protected readonly _commandService: ICommandService;
     protected readonly _permissionService: IPermissionService;
     protected readonly _logService: ILogService;
+    protected readonly _localeService: LocaleService;
+    protected readonly _definedNamesService: IDefinedNamesService;
     readonly id: string;
-    constructor(_workbook: Workbook, _injector: Injector, _resourceLoaderService: IResourceLoaderService, _selectionManagerService: SheetsSelectionsService, _univerInstanceService: IUniverInstanceService, _commandService: ICommandService, _permissionService: IPermissionService, _logService: ILogService);
+    constructor(_workbook: Workbook, _injector: Injector, _resourceLoaderService: IResourceLoaderService, _selectionManagerService: SheetsSelectionsService, _univerInstanceService: IUniverInstanceService, _commandService: ICommandService, _permissionService: IPermissionService, _logService: ILogService, _localeService: LocaleService, _definedNamesService: IDefinedNamesService);
+    /**
+     * Get the id of the workbook.
+     * @returns {string} The id of the workbook.
+     * @example
+     * ```ts
+     * // The code below gets the id of the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const id = activeSpreadsheet.getId();
+     * ```
+     */
     getId(): string;
+    /**
+     * Get the name of the workbook.
+     * @returns {string} The name of the workbook.
+     * @example
+     * ```ts
+     * // The code below gets the name of the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const name = activeSpreadsheet.getName();
+     * ```
+     */
     getName(): string;
+    /**
+     * Set the name of the workbook.
+     * @param {string} name The new name of the workbook.
+     * @example
+     * ```ts
+     * // The code below sets the name of the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.setName('MyWorkbook');
+     * ```
+     */
+    setName(name: string): void;
     /**
      * save workbook snapshot data, including conditional formatting, data validation, and other plugin data.
+     * @return Workbook snapshot data
+     * @example
+     * ```ts
+     * // The code below saves the workbook snapshot data
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const snapshot = activeSpreadsheet.save();
+     * ```
      */
     save(): IWorkbookData;
     /**
      * @deprecated use 'save' instead.
-     * @return {*}  {IWorkbookData}
+     * @return {*}  {IWorkbookData} Workbook snapshot data
      * @memberof FWorkbook
      */
     getSnapshot(): IWorkbookData;
     /**
      * Get the active sheet of the workbook.
      * @returns The active sheet of the workbook
+     * @example
+     * ```ts
+     * // The code below gets the active sheet of the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const activeSheet = activeSpreadsheet.getActiveSheet();
+     * ```
      */
     getActiveSheet(): FWorksheet;
     /**
      * Gets all the worksheets in this workbook
      * @returns An array of all the worksheets in the workbook
+     * @example
+     * ```ts
+     * // The code below gets all the worksheets in the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const sheets = activeSpreadsheet.getSheets();
+     * ```
      */
     getSheets(): FWorksheet[];
     /**
@@ -41,51 +96,150 @@ export declare class FWorkbook extends FBase {
      * @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
+     * @example
+     * ```ts
+     * // The code below creates a new sheet
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const newSheet = activeSpreadsheet.create('MyNewSheet', 10, 10);
+     * ```
      */
     create(name: string, rows: number, column: number): FWorksheet;
     /**
      * Get a worksheet by sheet id.
      * @param sheetId The id of the sheet to get.
      * @return The worksheet with given sheet id
+     * @example
+     * ```ts
+     * // The code below gets a worksheet by sheet id
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const sheet = activeSpreadsheet.getSheetBySheetId('sheetId');
+     * ```
      */
     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
+     * @example
+     * ```ts
+     * // The code below gets a worksheet by sheet name
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
+     * ```
      */
     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
+     * @example
+     * ```ts
+     * // The code below sets the given worksheet to be the active worksheet
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
+     * activeSpreadsheet.setActiveSheet(sheet);
+     * ```
      */
     setActiveSheet(sheet: FWorksheet): 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
+     * @example
+     * ```ts
+     * // The code below inserts a new sheet into the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.insertSheet();
+     *
+     * // The code below inserts a new sheet into the workbook, using a custom name
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.insertSheet('MyNewSheet');
+     * ```
      */
-    insertSheet(): FWorksheet;
+    insertSheet(sheetName?: string): FWorksheet;
     /**
      * Deletes the specified worksheet.
      * @param sheet The worksheet to delete.
+     * @example
+     * ```ts
+     * // The code below deletes the specified worksheet
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
+     * activeSpreadsheet.deleteSheet(sheet);
+     * ```
+     */
+    deleteSheet(sheet: FWorksheet): Promise<boolean>;
+    /**
+     * Undo the last action.
+     * @returns A promise that resolves to true if the undo was successful, false otherwise.
+     * @example
+     * ```ts
+     * // The code below undoes the last action
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.undo();
+     * ```
      */
-    deleteSheet(sheet: FWorksheet): void;
     undo(): Promise<boolean>;
+    /**
+     * Redo the last undone action.
+     * @returns A promise that resolves to true if the redo was successful, false otherwise.
+     * @example
+     * ```ts
+     * // The code below redoes the last undone action
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.redo();
+     * ```
+     */
     redo(): Promise<boolean>;
+    /**
+     * Callback for command execution.
+     * @callback onBeforeCommandExecuteCallback
+     * @param {ICommandInfo<ISheetCommandSharedParams>} command The command that was executed.
+     */
     /**
      * Register a callback that will be triggered before invoking a command targeting the Univer sheet.
-     * @param callback the callback.
+     * @param {onBeforeCommandExecuteCallback} callback the callback.
      * @returns 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);
+     * });
+     * ```
      */
     onBeforeCommandExecute(callback: CommandListener): IDisposable;
+    /**
+     * Callback for command execution.
+     * @callback onCommandExecutedCallback
+     * @param {ICommandInfo<ISheetCommandSharedParams>} command The command that was executed
+     */
     /**
      * Register a callback that will be triggered when a command is invoked targeting the Univer sheet.
-     * @param callback the callback.
+     * @param {onCommandExecutedCallback} callback the callback.
      * @returns 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
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.onCommandExecuted((command) => {
+     *   console.log('Command executed:', command);
+     * });
      */
     onCommandExecuted(callback: CommandListener): IDisposable;
+    /**
+     * Callback for selection changes.
+     *
+     * @callback onSelectionChangeCallback
+     * @param {IRange[]} selections The new selection.
+     */
+    /**
+     * Register a callback that will be triggered when the selection changes.
+     * @param {onSelectionChangeCallback} callback The callback.
+     * @returns A function to dispose the listening
+     */
     onSelectionChange(callback: (selections: IRange[]) => void): IDisposable;
     /**
      * Used to modify the editing permissions of the workbook. When the value is false, editing is not allowed.
@@ -102,4 +256,188 @@ export declare class FWorkbook extends FBase {
      * @returns the active range
      */
     getActiveRange(): FRange | null;
+    /**
+     * Deletes the currently active sheet.
+     * @example
+     * ```ts
+     * // The code below deletes the currently active sheet and stores the new active
+     * // sheet in a variable
+     * const sheet = univerAPI.getActiveWorkbook().deleteActiveSheet();
+     * ```
+     */
+    deleteActiveSheet(): Promise<boolean>;
+    /**
+     * Duplicates the given worksheet.
+     * @param {FWorksheet} sheet The worksheet to duplicate.
+     * @returns {Promise<boolean>} true if the sheet was duplicated, false otherwise
+     * @example
+     * ```ts
+     * // The code below duplicates the given worksheet
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const activeSheet = activeSpreadsheet.getActiveSheet();
+     * activeSpreadsheet.duplicateSheet(activeSheet);
+     * ```
+     */
+    duplicateSheet(sheet: FWorksheet): Promise<boolean>;
+    /**
+     * Duplicates the active sheet.
+     * @returns {Promise<boolean>} true if the sheet was duplicated, false otherwise
+     * @example
+     * ```ts
+     * // The code below duplicates the active sheet
+     *  const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     *  activeSpreadsheet.duplicateActiveSheet();
+     * ```
+     */
+    duplicateActiveSheet(): Promise<boolean>;
+    /**
+     * Get the number of sheets in the workbook.
+     * @returns The number of sheets in the workbook
+     * @example
+     * ```ts
+     * // The code below gets the number of sheets in the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const numSheets = activeSpreadsheet.getNumSheets();
+     * ```
+     */
+    getNumSheets(): number;
+    /**
+     * Get the locale of the workbook.
+     * @returns {LocaleType} The locale of the workbook
+     * @example
+     * ```ts
+     * // The code below gets the locale of the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const locale = activeSpreadsheet.getLocale();
+     * ```
+     */
+    getLocale(): LocaleType;
+    /**
+     * Set the locale of the workbook.
+     * @param {LocaleType} locale The locale to set
+     * @example
+     * ```ts
+     * // The code below sets the locale of the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.setLocale(LocaleType.EN_US);
+     * ```
+     */
+    setLocale(locale: LocaleType): void;
+    /**
+     * Get the URL of the workbook.
+     * @returns {string} The URL of the workbook
+     * @example
+     * ```ts
+     * // The code below gets the URL of the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const url = activeSpreadsheet.getUrl();
+     * ```
+     */
+    getUrl(): string;
+    /**
+     * Move the sheet to the specified index.
+     * @param {FWorksheet} sheet The sheet to move
+     * @param {number} index The index to move the sheet to
+     * @returns {Promise<boolean>} true if the sheet was moved, false otherwise
+     * @example
+     * ```ts
+     * // The code below moves the sheet to the specified index
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const sheet = activeSpreadsheet.getActiveSheet();
+     * activeSpreadsheet.moveSheet(sheet, 1);
+     * ```
+     */
+    moveSheet(sheet: FWorksheet, index: number): Promise<boolean>;
+    /**
+     * Move the active sheet to the specified index.
+     * @param {number} index The index to move the active sheet to
+     * @returns {Promise<boolean>} true if the sheet was moved, false otherwise
+     * @example
+     * ```ts
+     * // The code below moves the active sheet to the specified index
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.moveActiveSheet(1);
+     * ```
+     */
+    moveActiveSheet(index: number): Promise<boolean>;
+    /**
+     * Get the PermissionInstance.
+     *
+     * @returns {FPermission} - The PermissionInstance.
+     */
+    getPermission(): FPermission;
+    /**
+     * Get the defined name by name.
+     * @param {string} name The name of the defined name to get
+     * @returns {FDefinedName | null} The defined name with the given name
+     * @example
+     * ```ts
+     * // The code below gets the defined name by name
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const definedName = activeSpreadsheet.getDefinedName('MyDefinedName');
+     * ```
+     */
+    getDefinedName(name: string): FDefinedName | null;
+    /**
+     * Get all the defined names in the workbook.
+     * @returns {FDefinedName[]} All the defined names in the workbook
+     * @example
+     * ```ts
+     * // The code below gets all the defined names in the workbook
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const definedNames = activeSpreadsheet.getDefinedNames();
+     * ```
+     */
+    getDefinedNames(): FDefinedName[];
+    /**
+     * 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
+     * @example
+     * ```ts
+     * // The code below inserts a defined name
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * activeSpreadsheet.insertDefinedName('MyDefinedName', 'Sheet1!A1');
+     * ```
+     */
+    insertDefinedName(name: string, formulaOrRefString: string): void;
+    /**
+     * Delete the defined name with the given name.
+     * @param {string} name The name of the defined name to delete
+     * @returns {boolean} true if the defined name was deleted, false otherwise
+     * @example
+     * ```ts
+     * // The code below deletes the defined name with the given name
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const deleted = activeSpreadsheet.deleteDefinedName('MyDefinedName');
+     * ```
+     */
+    deleteDefinedName(name: string): boolean;
+    /**
+     * insert a defined name by builder param
+     * @param {ISetDefinedNameMutationParam} param The param to insert the defined name
+     * @example
+     * ```ts
+     * // The code below inserts a defined name by builder param
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const builder = univerAPI.newDefinedName();
+     * const param = builder.setName('MyDefinedName').setRef('Sheet1!A1').build();
+     * activeSpreadsheet.insertDefinedNameBuilder(param);
+     * ```
+     */
+    insertDefinedNameBuilder(param: ISetDefinedNameMutationParam): void;
+    /**
+     * Update the defined name with the given name.
+     * @param {ISetDefinedNameMutationParam} param The param to insert the defined name
+     * @example
+     * ```ts
+     * // The code below updates the defined name with the given name
+     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+     * const builder = activeSpreadsheet.getDefinedName('MyDefinedName').toBuilder();
+     * builder.setRef('Sheet1!A2').setName('MyDefinedName1').build();
+     * activeSpreadsheet.updateDefinedNameBuilder(param);
+     *
+     * ```
+     */
+    updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): void;
 }