@univerjs/sheets 0.5.3 → 0.5.4

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

@@ -1,4 +1,4 @@
-import { CellValue, ICellData, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable, Workbook, Worksheet, FBaseInitialable, ICommandService, Injector, WrapStrategy } from '@univerjs/core';
+import { CellValue, CustomData, ICellData, IDocumentData, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable, Workbook, Worksheet, FBaseInitialable, ICommandService, Injector, RichTextValue, WrapStrategy } from '@univerjs/core';
 import { SplitDelimiterEnum } from '@univerjs/sheets';
 import { FHorizontalAlignment, FVerticalAlignment } from './utils';
 import { FormulaDataModel } from '@univerjs/engine-formula';
@@ -15,51 +15,44 @@ export declare class FRange extends FBaseInitialable {
     constructor(_workbook: Workbook, _worksheet: Worksheet, _range: IRange, _injector: Injector, _commandService: ICommandService, _formulaDataModel: FormulaDataModel);
     /**
      * Get the unit ID of the current workbook
-     *
-     * @return The unit ID of the workbook
+     * @returns The unit ID of the workbook
      */
     getUnitId(): string;
     /**
      * Gets the name of the worksheet
-     *
-     * @return The name of the worksheet
+     * @returns The name of the worksheet
      */
     getSheetName(): string;
+    /**
+     * Gets the ID of the worksheet
+     * @returns The ID of the worksheet
+     */
+    getSheetId(): string;
     /**
      * Gets the area where the statement is applied
-     *
-     * @return The area where the statement is applied
+     * @returns The area where the statement is applied
      */
     getRange(): IRange;
     /**
      * Gets the starting row number of the applied area
-     *
-     * @return The starting row number of the area
+     * @returns The starting row number of the area
      */
     getRow(): number;
     /**
      * Gets the starting column number of the applied area
-     *
-     * @return The starting column number of the area
+     * @returns The starting column number of the area
      */
     getColumn(): number;
     /**
      * Gets the width of the applied area
-     *
-     * @return The width of the area
+     * @returns The width of the area
      */
     getWidth(): number;
     /**
      * Gets the height of the applied area
-     *
-     * @return The height of the area
+     * @returns The height of the area
      */
     getHeight(): number;
-    /**
-     * Return first cell model data in this range
-     * @returns The cell model data
-     */
-    getCellData(): ICellData | null;
     /**
      * Return range whether this range is merged
      * @returns if true is merged
@@ -67,72 +60,243 @@ export declare class FRange extends FBaseInitialable {
     isMerged(): boolean;
     /**
      * Return first cell style data in this range
-     * @returns The cell style data
+     * @returns {IStyleData | null} The cell style data
      */
     getCellStyleData(): IStyleData | null;
     /**
      * Returns the value of the cell at the start of this range.
-     * @returns The value of the cell.
+     * @returns {CellValue | null} The value of the cell.
      */
     getValue(): CellValue | null;
     /**
      * Returns the rectangular grid of values for this range.
      * Returns a two-dimensional array of values, indexed by row, then by column.
-     * @returns A two-dimensional array of values.
+     * @returns {Nullable<CellValue>[][]} A two-dimensional array of values.
      */
     getValues(): Nullable<CellValue>[][];
+    /**
+     * Return first cell model data in this range
+     * @returns {ICellData | null} The cell model data
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getCellData()
+     * ```
+     */
+    getCellData(): ICellData | null;
     /**
      * Returns the cell data for the cells in the range.
-     * @returns A two-dimensional array of cell data.
+     * @returns {Nullable<ICellData>[][]} A two-dimensional array of cell data.
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getCellDatas()
+     * ```
+     */
+    getCellDatas(): Nullable<ICellData>[][];
+    /**
+     * @deprecated use `getCellDatas` instead.
      */
     getCellDataGrid(): Nullable<ICellData>[][];
+    /**
+     * Returns the rich text value for the cell at the start of this range.
+     * @returns {Nullable<RichTextValue>} The rich text value
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getRichTextValue()
+     * ```
+     */
+    getRichTextValue(): Nullable<RichTextValue>;
+    /**
+     * Returns the rich text value for the cells in the range.
+     * @returns {Nullable<RichTextValue>[][]} A two-dimensional array of RichTextValue objects.
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getRichTextValues()
+     * ```
+     */
+    getRichTextValues(): Nullable<RichTextValue>[][];
+    /**
+     * Returns the value and rich text value for the cell at the start of this range.
+     * @returns {Nullable<CellValue | RichTextValue>} The value and rich text value
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getValueAndRichTextValue()
+     * ```
+     */
+    getValueAndRichTextValue(): Nullable<CellValue | RichTextValue>;
+    /**
+     * Returns the value and rich text value for the cells in the range.
+     * @returns {Nullable<CellValue | RichTextValue>[][]} A two-dimensional array of value and rich text value
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getValueAndRichTextValues()
+     * ```
+     */
+    getValueAndRichTextValues(): Nullable<CellValue | RichTextValue>[][];
     /**
      * Returns the formulas (A1 notation) for the cells in the range. Entries in the 2D array are empty strings for cells with no formula.
-     * @returns A two-dimensional array of formulas in string format.
+     * @returns {string[][]} A two-dimensional array of formulas in string format.
+     * @example
+     * ```ts
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getFormulas()
+     * ```
      */
     getFormulas(): string[][];
     getWrap(): boolean;
     getWrapStrategy(): WrapStrategy;
     getHorizontalAlignment(): string;
     getVerticalAlignment(): string;
+    /**
+     * Set custom meta data for first cell in current range.
+     * @param {CustomData} data The custom meta data
+     * @returns {FRange} This range, for chaining
+     * ```ts
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .setCustomMetaData({ key: 'value' });
+     * ```
+     */
+    setCustomMetaData(data: CustomData): FRange;
+    /**
+     * Set custom meta data for current range.
+     * @param {CustomData[][]} datas The custom meta data
+     * @returns {FRange} This range, for chaining
+     * ```ts
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .setCustomMetaDatas([[{ key: 'value' }]]);
+     * ```
+     */
+    setCustomMetaDatas(datas: CustomData[][]): FRange;
+    /**
+     * Returns the custom meta data for the cell at the start of this range.
+     * @returns {CustomData | null} The custom meta data
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getCustomMetaData()
+     * ```
+     */
+    getCustomMetaData(): CustomData | null;
+    /**
+     * Returns the custom meta data for the cells in the range.
+     * @returns {CustomData[][]} A two-dimensional array of custom meta data
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .getCustomMetaDatas()
+     * ```
+     */
+    getCustomMetaDatas(): Nullable<CustomData>[][];
     /**
      * Set background color for current range.
      * @param color {string}
      * @example
      * ```
-     * univerAPI.getActiveWorkbook().getActiveSheet().getActiveRange().setBackgroundColor('red')
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .setBackgroundColor('red')
      * ```
      */
     setBackgroundColor(color: string): FRange;
     /**
      * Set background color for current range.
      * @example
-     * ```
+     * ```typescript
      * univerAPI.getActiveWorkbook().getActiveSheet().getActiveRange().setBackground('red')
      * ```
      * @param color {string}
      */
     setBackground(color: string): FRange;
     /**
-     * The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
-     * @param value
+     * Set new value for current cell, first cell in this range.
+     * @param {CellValue | ICellData} value The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
      */
     setValue(value: CellValue | ICellData): FRange;
+    /**
+     * Set new value for current cell, first cell in this range.
+     * @param {CellValue | ICellData} value  The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
+     * ```ts
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .setValueForCell(1);
+     * ```
+     */
+    setValueForCell(value: CellValue | ICellData): FRange;
+    /**
+     * Set the rich text value for the cell at the start of this range.
+     * @param {RichTextValue | IDocumentData} value The rich text value
+     * @returns {FRange} The range
+     * @example
+     * ```
+     * univerAPI.getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .setRichTextValueForCell(new RichTextValue().insertText('Hello'));
+     * ```
+     */
+    setRichTextValueForCell(value: RichTextValue | IDocumentData): FRange;
+    /**
+     * Set the rich text value for the cells in the range.
+     * @param {RichTextValue[][]} values The rich text value
+     * @returns {FRange} The range
+     * @example
+     * ```ts
+     * univerAPI
+     *  .getActiveWorkbook()
+     *  .getActiveSheet()
+     *  .getActiveRange()
+     *  .setRichTextValues([[new RichTextValue().insertText('Hello')]]);
+     * ```
+     */
+    setRichTextValues(values: (RichTextValue | IDocumentData)[][]): FRange;
     /**
      * Set the cell wrap of the given range.
      * Cells with wrap enabled (the default) resize to display their full content. Cells with wrap disabled display as much as possible in the cell without resizing or running to multiple lines.
+     * @param isWrapEnabled
      */
     setWrap(isWrapEnabled: boolean): FRange;
     /**
      * Sets the text wrapping strategy for the cells in the range.
+     * @param strategy
      */
     setWrapStrategy(strategy: WrapStrategy): FRange;
     /**
      * Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
+     * @param alignment
      */
     setVerticalAlignment(alignment: FVerticalAlignment): FRange;
     /**
      * Set the horizontal (left to right) alignment for the given range (left/center/right).
+     * @param alignment
      */
     setHorizontalAlignment(alignment: FHorizontalAlignment): FRange;
     /**
@@ -157,10 +321,12 @@ export declare class FRange extends FBaseInitialable {
     setFontLine(fontLine: FontLine | null): this;
     /**
      * Sets the font underline style of the given ITextDecoration
+     * @param value
      */
     private _setFontUnderline;
     /**
      * Sets the font strikethrough style of the given ITextDecoration
+     * @param value
      */
     private _setFontStrikethrough;
     /**
@@ -180,36 +346,80 @@ export declare class FRange extends FBaseInitialable {
     setFontColor(color: string | null): this;
     /**
      * Merge cells in a range into one merged cell
-     *
      * @param [defaultMerge] - If true, only the value in the upper left cell is retained.
-     *
      * @returns This range, for chaining
+     * @example
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * const worksheet = workbook.getActiveSheet();
+     * const range = worksheet.getRange(0, 0, 2, 2);
+     * const merge = range.merge();
+     * const isMerged = merge.isMerged();
+     * console.log('debugger', isMerged);
+     * ```
      */
     merge(defaultMerge?: boolean): FRange;
     /**
      * Merges cells in a range horizontally.
-     *
      * @param [defaultMerge] - If true, only the value in the upper left cell is retained.
-     *
      * @returns This range, for chaining
+     * @example
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * const worksheet = workbook.getActiveSheet();
+     * const range = worksheet.getRange(2, 2, 2, 2);
+     * const merge = range.mergeAcross();
+     * const allMerge = worksheet.getMergeData();
+     * console.log(allMerge.length); // There will be two merged cells.
+     * ```
      */
     mergeAcross(defaultMerge?: boolean): FRange;
     /**
      * Merges cells in a range vertically.
-     *
      * @param [defaultMerge] - If true, only the value in the upper left cell is retained.
-     *
      * @returns This range, for chaining
+     * @example
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * const worksheet = workbook.getActiveSheet();
+     * const range = worksheet.getRange(4, 4, 2, 2);
+     * const merge = range.mergeVertically();
+     * const allMerge = worksheet.getMergeData();
+     * console.log(allMerge.length); // There will be two merged cells.
+     * ```
      */
     mergeVertically(defaultMerge?: boolean): FRange;
     /**
      * Returns true if cells in the current range overlap a merged cell.
      * @returns {boolean} is overlap with a merged cell
+     * @example
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * const worksheet = workbook.getActiveSheet();
+     * const range = worksheet.getRange(0,0,2,2);
+     * const merge = range.merge();
+     * const anchor = worksheet.getRange(0,0);
+     * const isPartOfMerge = anchor.isPartOfMerge();
+     * console.log('debugger, isPartOfMerge) // true
+     * ```
      */
     isPartOfMerge(): boolean;
     /**
      * Break all horizontally- or vertically-merged cells contained within the range list into individual cells again.
      * @returns This range, for chaining
+     * @example
+     * ```ts
+     * const workbook = univerAPI.getActiveWorkbook();
+     * const worksheet = workbook.getActiveSheet();
+     * const range = worksheet.getRange(0,0,2,2);
+     * const merge = range.merge();
+     * const anchor = worksheet.getRange(0,0);
+     * const isPartOfMergeFirst = anchor.isPartOfMerge();
+     * console.log('debugger' isPartOfMergeFirst) // true
+     * range.breakApart();
+     * const isPartOfMergeSecond = anchor.isPartOfMerge();
+     * console.log('debugger' isPartOfMergeSecond) // false
+     * ```
      */
     breakApart(): FRange;
     /**
@@ -230,6 +440,7 @@ export declare class FRange extends FBaseInitialable {
     forEach(callback: (row: number, col: number, cell: ICellData) => void): void;
     /**
      * Returns a string description of the range, in A1 notation.
+     * @param withSheet
      * @returns {string} The A1 notation of the range.
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();

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;