@univerjs/sheets 0.6.0 → 0.6.1

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

@@ -29,8 +29,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the Workbook instance
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const workbook = activeSpreadsheet.getWorkbook();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const workbook = fWorkbook.getWorkbook();
+     * console.log(workbook);
      * ```
      */
     getWorkbook(): Workbook;
@@ -40,8 +41,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the id of the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const id = activeSpreadsheet.getId();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const unitId = fWorkbook.getId();
+     * console.log(unitId);
      * ```
      */
     getId(): string;
@@ -51,20 +53,20 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the name of the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const name = activeSpreadsheet.getName();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const name = fWorkbook.getName();
+     * console.log(name);
      * ```
      */
     getName(): string;
     /**
      * 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
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.setName('MyWorkbook');
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.setName('MyWorkbook');
      * ```
      */
     setName(name: string): void;
@@ -74,8 +76,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below saves the workbook snapshot data
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const snapshot = activeSpreadsheet.save();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const snapshot = fWorkbook.save();
+     * console.log(snapshot);
      * ```
      */
     save(): IWorkbookData;
@@ -97,8 +100,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the active sheet of the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const activeSheet = activeSpreadsheet.getActiveSheet();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     * console.log(fWorksheet);
      * ```
      */
     getActiveSheet(): FWorksheet;
@@ -108,8 +112,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets all the worksheets in the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const sheets = activeSpreadsheet.getSheets();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const sheets = fWorkbook.getSheets();
+     * console.log(sheets);
      * ```
      */
     getSheets(): FWorksheet[];
@@ -122,8 +127,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below creates a new sheet
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const newSheet = activeSpreadsheet.create('MyNewSheet', 10, 10);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const newSheet = fWorkbook.create('MyNewSheet', 10, 10);
+     * console.log(newSheet);
      * ```
      */
     create(name: string, rows: number, column: number): FWorksheet;
@@ -134,8 +140,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets a worksheet by sheet id
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const sheet = activeSpreadsheet.getSheetBySheetId('sheetId');
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const sheet = fWorkbook.getSheetBySheetId('sheetId');
+     * console.log(sheet);
      * ```
      */
     getSheetBySheetId(sheetId: string): FWorksheet | null;
@@ -146,8 +153,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets a worksheet by sheet name
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const sheet = fWorkbook.getSheetByName('Sheet1');
+     * console.log(sheet);
      * ```
      */
     getSheetByName(name: string): FWorksheet | null;
@@ -158,9 +166,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @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);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const sheet = fWorkbook.getSheets()[1];
+     * fWorkbook.setActiveSheet(sheet);
      * ```
      */
     setActiveSheet(sheet: FWorksheet | string): FWorksheet;
@@ -172,12 +180,12 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below inserts a new sheet into the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.insertSheet();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.insertSheet();
      *
      * // The code below inserts a new sheet into the workbook, using a custom name
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.insertSheet('MyNewSheet');
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.insertSheet('MyNewSheet');
      * ```
      */
     insertSheet(sheetName?: string): FWorksheet;
@@ -188,9 +196,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below deletes the specified worksheet
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
-     * activeSpreadsheet.deleteSheet(sheet);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const sheet = fWorkbook.getSheets()[1];
+     * fWorkbook.deleteSheet(sheet);
      * ```
      */
     deleteSheet(sheet: FWorksheet | string): boolean;
@@ -200,8 +208,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below undoes the last action
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.undo();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.undo();
      * ```
      */
     undo(): FWorkbook;
@@ -211,8 +219,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below redoes the last undone action
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.redo();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.redo();
      * ```
      */
     redo(): FWorkbook;
@@ -228,9 +236,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @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);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.onBeforeCommandExecute((command) => {
+     *   console.log('Before command execute:', command);
      * });
      * ```
      */
@@ -247,8 +255,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @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) => {
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.onCommandExecuted((command) => {
      *   console.log('Command executed:', command);
      * });
      * ```
@@ -263,23 +271,49 @@ export declare class FWorkbook extends FBaseInitialable {
      * Register a callback that will be triggered when the selection changes.
      * @param {onSelectionChangeCallback} callback The callback.
      * @returns {IDisposable} A function to dispose the listening
+     * @example
+     * ```ts
+     * // The code below registers a callback that will be triggered when the selection changes
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.onSelectionChange((selections) => {
+     *   console.log('Selection changed:', selections);
+     * });
+     * ```
      */
     onSelectionChange(callback: (selections: IRange[]) => void): IDisposable;
     /**
      * 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
+     * @example
+     * ```ts
+     * // The code below sets the editing permissions of the workbook
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.setEditable(false);
+     * ```
      */
     setEditable(value: boolean): FWorkbook;
     /**
      * Sets the selection region for active sheet.
      * @param {FRange} range The range to set as the active selection.
      * @returns {FWorkbook} FWorkbook instance
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const range = fWorkbook.getActiveSheet().getRange('A10:B10');
+     * fWorkbook.setActiveRange(range);
+     * ```
      */
     setActiveRange(range: FRange): FWorkbook;
     /**
      * Returns the selected range in the active sheet, or null if there is no active range.
      * @returns {FRange | null} The active range
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const activeRange = fWorkbook.getActiveRange();
+     * console.log(activeRange);
+     * ```
      */
     getActiveRange(): FRange | null;
     /**
@@ -287,9 +321,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @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
-     * // sheet in a variable
-     * const sheet = univerAPI.getActiveWorkbook().deleteActiveSheet();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.deleteActiveSheet();
      * ```
      */
     deleteActiveSheet(): boolean;
@@ -300,9 +333,10 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below duplicates the given worksheet
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const activeSheet = activeSpreadsheet.getActiveSheet();
-     * activeSpreadsheet.duplicateSheet(activeSheet);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const activeSheet = fWorkbook.getActiveSheet();
+     * const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet);
+     * console.log(duplicatedSheet);
      * ```
      */
     duplicateSheet(sheet: FWorksheet): FWorksheet;
@@ -311,8 +345,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @returns {FWorksheet} The duplicated worksheet
      * @example
      * ```ts
-     *  const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     *  activeSpreadsheet.duplicateActiveSheet();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const duplicatedSheet = fWorkbook.duplicateActiveSheet();
+     * console.log(duplicatedSheet);
      * ```
      */
     duplicateActiveSheet(): FWorksheet;
@@ -322,8 +357,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the number of sheets in the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const numSheets = activeSpreadsheet.getNumSheets();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * console.log(fWorkbook.getNumSheets());
      * ```
      */
     getNumSheets(): number;
@@ -333,13 +368,13 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the locale of the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const locale = activeSpreadsheet.getLocale();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * console.log(fWorkbook.getLocale());
      * ```
      */
     getLocale(): LocaleType;
     /**
-     * @deprecated use setSpreadsheetLocale instead.
+     * @deprecated use `setSpreadsheetLocale` instead.
      * @param {LocaleType} locale - The locale to set
      */
     setLocale(locale: LocaleType): void;
@@ -350,8 +385,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below sets the locale of the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.setLocale(LocaleType.EN_US);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.setSpreadsheetLocale(univerAPI.Enum.LocaleType.EN_US);
+     * console.log(fWorkbook.getLocale());
      * ```
      */
     setSpreadsheetLocale(locale: LocaleType): FWorkbook;
@@ -361,8 +397,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the URL of the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const url = activeSpreadsheet.getUrl();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const url = fWorkbook.getUrl();
+     * console.log(url);
      * ```
      */
     getUrl(): string;
@@ -374,9 +411,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below moves the sheet to the specified index
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const sheet = activeSpreadsheet.getActiveSheet();
-     * activeSpreadsheet.moveSheet(sheet, 1);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const sheet = fWorkbook.getActiveSheet();
+     * fWorkbook.moveSheet(sheet, 1);
      * ```
      */
     moveSheet(sheet: FWorksheet, index: number): FWorkbook;
@@ -387,14 +424,20 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below moves the active sheet to the specified index
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.moveActiveSheet(1);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.moveActiveSheet(1);
      * ```
      */
     moveActiveSheet(index: number): FWorkbook;
     /**
      * Get the PermissionInstance.
      * @returns {FPermission} - The PermissionInstance.
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const permission = fWorkbook.getPermission();
+     * console.log(permission);
+     * ```
      */
     getPermission(): FPermission;
     /**
@@ -404,8 +447,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the defined name by name
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const definedName = activeSpreadsheet.getDefinedName('MyDefinedName');
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const definedName = fWorkbook.getDefinedName('MyDefinedName');
+     * console.log(definedName);
      * ```
      */
     getDefinedName(name: string): FDefinedName | null;
@@ -415,8 +459,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets all the defined names in the workbook
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const definedNames = activeSpreadsheet.getDefinedNames();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const definedNames = fWorkbook.getDefinedNames();
+     * console.log(definedNames);
      * ```
      */
     getDefinedNames(): FDefinedName[];
@@ -428,8 +473,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below inserts a defined name
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * activeSpreadsheet.insertDefinedName('MyDefinedName', 'Sheet1!A1');
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!A1');
      * ```
      */
     insertDefinedName(name: string, formulaOrRefString: string): FWorkbook;
@@ -440,8 +485,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below deletes the defined name with the given name
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const deleted = activeSpreadsheet.deleteDefinedName('MyDefinedName');
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * fWorkbook.deleteDefinedName('MyDefinedName');
      * ```
      */
     deleteDefinedName(name: string): boolean;
@@ -452,10 +497,13 @@ export declare class FWorkbook extends FBaseInitialable {
      * @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);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const definedNameBuilder = univerAPI.newDefinedName()
+     *   .setRef('Sheet1!$A$1')
+     *   .setName('MyDefinedName')
+     *   .setComment('This is a comment')
+     *   .build();
+     * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
      * ```
      */
     insertDefinedNameBuilder(param: ISetDefinedNameMutationParam): void;
@@ -466,10 +514,12 @@ export declare class FWorkbook extends FBaseInitialable {
      * @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);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const definedNameBuilder = fWorkbook.getDefinedName('MyDefinedName').toBuilder();
+     * const param = definedNameBuilder.setRef('Sheet1!A2')
+     *   .setName('NewDefinedName')
+     *   .build();
+     * fWorkbook.updateDefinedNameBuilder(param);
      * ```
      */
     updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): void;
@@ -479,8 +529,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * // The code below gets the registered range themes
-     * const activeSpreadsheet = univerAPI.getActiveWorkbook();
-     * const themes = activeSpreadsheet.getRegisteredRangeThemes();
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const themes = fWorkbook.getRegisteredRangeThemes();
      * console.log(themes);
      * ```
      */
@@ -493,10 +543,11 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```ts
      * // import {RangeThemeStyle} from '@univerjs/sheets';
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const rangeThemeStyle = new RangeThemeStyle('MyTheme');
-     * rangeThemeStyle.setSecondRowStyle({
-     *   bg: {
-     *     rgb: 'rgb(214,231,241)',
+     * const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
+     *   secondRowStyle: {
+     *     bg: {
+     *       rgb: 'rgb(214,231,241)',
+     *     },
      *   },
      * });
      * fWorkbook.registerRangeTheme(rangeThemeStyle);
@@ -514,6 +565,24 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     unregisterRangeTheme(themeName: string): void;
+    /**
+     * Create a range theme style.
+     * @param {string} themeName - The name of the theme to register
+     * @param {Omit<IRangeThemeStyleJSON, 'name'>} themeStyleJson - The theme style json to register
+     * @returns {RangeThemeStyle} - The created range theme style
+     * @example
+     * ```ts
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
+     *   secondRowStyle: {
+     *     bg: {
+     *       rgb: 'rgb(214,231,241)',
+     *     },
+     *   },
+     * });
+     * console.log(rangeThemeStyle);
+     * ```
+     */
     createRangeThemeStyle(themeName: string, themeStyleJson?: Omit<IRangeThemeStyleJSON, 'name'>): RangeThemeStyle;
     /**
      * Set custom metadata of workbook
@@ -533,6 +602,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const custom = fWorkbook.getCustomMetadata();
+     * console.log(custom);
      * ```
      */
     getCustomMetadata(): CustomData | undefined;