@univerjs/sheets 0.24.0 → 0.25.0-insiders.20260608-e4336f7

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

@@ -24,7 +24,8 @@ import { FWorksheet } from './f-worksheet';
  * @example
  * ```ts
  * const fWorkbook = univerAPI.getActiveWorkbook()
- * const fWorksheet = fWorkbook.getActiveSheet()
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1')
+ * if (!fWorksheet) return;
  * const fSelection = fWorksheet.getSelection();
  * const activeRange = fSelection.getActiveRange();
  * console.log(activeRange);
@@ -43,7 +44,8 @@ export declare class FSelection {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const fRange = fWorksheet.getRange('A10:B11');
      * fRange.activate();
      * const fSelection = fWorksheet.getSelection();
@@ -57,7 +59,8 @@ export declare class FSelection {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const fSelection = fWorksheet.getSelection();
      * const activeRangeList = fSelection.getActiveRangeList();
      * activeRangeList.forEach((range) => {
@@ -72,7 +75,8 @@ export declare class FSelection {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const fRange = fWorksheet.getRange('A10:B11');
      * fRange.activate();
      * const fSelection = fWorksheet.getSelection();
@@ -89,10 +93,11 @@ export declare class FSelection {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const fSelection = fWorksheet.getSelection();
      * const activeSheet = fSelection.getActiveSheet();
-     * console.log(activeSheet.equalTo(fWorksheet)); // true
+     * console.log(activeSheet.equalTo(fWorksheet));
      * ```
      */
     getActiveSheet(): FWorksheet;
@@ -103,7 +108,8 @@ export declare class FSelection {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const fRange = fWorksheet.getRange('A10:B11');
      * fRange.activate();
      * const cell = fWorksheet.getRange('B11');
@@ -127,7 +133,8 @@ export declare class FSelection {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * // make sure the active cell is A1 and selection is A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.activate();

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

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { ICommandInfo, ICreateUnitOptions, IDisposable, Injector, IWorkbookData, Nullable } from '@univerjs/core';
+import type { ICreateUnitOptions, Injector, IWorkbookData } from '@univerjs/core';
 import type { FWorksheet } from './f-worksheet';
 import { FUniver } from '@univerjs/core/facade';
 import { FWorkbook } from './f-workbook';
@@ -21,31 +21,27 @@ import { FWorkbook } from './f-workbook';
  * @ignore
  */
 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.
      * @param {ICreateUnitOptions} options The options of creating the spreadsheet.
-     * @returns {FWorkbook} FWorkbook API instance.
+     * @returns {FWorkbook} The spreadsheet API instance.
      * @example
      * ```ts
-     * const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' });
+     * const fWorkbook = univerAPI.createWorkbook({ id: 'workbook-01', name: 'Workbook1' });
      * console.log(fWorkbook);
      * ```
      *
      * Add you can make the workbook not as the active workbook by setting options:
      * ```ts
-     * const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' }, { makeCurrent: false });
+     * const fWorkbook = univerAPI.createWorkbook({ id: 'workbook-01', name: 'Workbook1' }, { makeCurrent: false });
      * console.log(fWorkbook);
      * ```
      */
     createWorkbook(data: Partial<IWorkbookData>, options?: ICreateUnitOptions): FWorkbook;
     /**
      * Get the currently focused Univer spreadsheet.
-     * @returns {FWorkbook | null} The currently focused Univer spreadsheet.
+     * @returns {FWorkbook | null} The currently focused Univer spreadsheet API instance, or null if there is no active spreadsheet.
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -53,49 +49,18 @@ export interface IFUniverSheetsMixin {
      * ```
      */
     getActiveWorkbook(): FWorkbook | null;
-    /**
-     * @deprecated use `univerAPI.getActiveWorkbook` instead
-     */
-    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.
+     * @returns {FWorkbook | null} The spreadsheet API instance corresponding to the spreadsheet id, or null if not found.
      *
      * @example
      * ```ts
-     * const fWorkbook = univerAPI.getUniverSheet('Sheet1');
-     * console.log(fWorkbook);
-     *
-     * const fWorkbook = univerAPI.getWorkbook('Sheet1');
+     * const fWorkbook = univerAPI.getWorkbook('workbook-01');
      * console.log(fWorkbook);
      * ```
      */
-    getUniverSheet(id: string): FWorkbook | null;
     getWorkbook(id: string): FWorkbook | null;
-    /**
-     * @deprecated Use `univerAPI.addEvent(univerAPI.Event.UnitCreated, () => {})`
-     */
-    onUniverSheetCreated(callback: (workbook: FWorkbook) => void): IDisposable;
-    /**
-     * 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
-     * const unitId = 'workbook-01';
-     * const subUnitId = 'sheet-0001';
-     * const target = univerAPI.getSheetTarget(unitId, subUnitId);
-     * if (!target) return;
-     * const { workbook, worksheet } = target;
-     * console.log(workbook, worksheet);
-     * ```
-     */
-    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.
@@ -104,17 +69,23 @@ export interface IFUniverSheetsMixin {
      * ```ts
      * univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {
      *   const { options, ...commandInfo } = event;
-     *   const target = univerAPI.getCommandSheetTarget(commandInfo);
+     *   const target = univerAPI.getSheetCommandTarget(commandInfo.params);
      *   if (!target) return;
      *   const { workbook, worksheet } = target;
      *   console.log(workbook, worksheet);
      * });
      * ```
      */
-    getCommandSheetTarget(commandInfo: ICommandInfo<object>): Nullable<{
+    getSheetCommandTarget(params?: {
+        unitId?: string;
+        subUnitId?: string;
+        sheetId?: string;
+    }): {
         workbook: FWorkbook;
         worksheet: FWorksheet;
-    }>;
+        unitId: string;
+        subUnitId: string;
+    } | null;
     /**
      * Get the active sheet.
      * @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} The active sheet.
@@ -126,10 +97,10 @@ export interface IFUniverSheetsMixin {
      * console.log(workbook, worksheet);
      * ```
      */
-    getActiveSheet(): Nullable<{
+    getActiveSheet(): {
         workbook: FWorkbook;
         worksheet: FWorksheet;
-    }>;
+    } | null;
     /**
      * Set whether to enable synchronize the frozen state to other users in real-time collaboration.
      * @param {boolean} enabled - Whether to enable freeze sync. Default is true.
@@ -142,31 +113,29 @@ export interface IFUniverSheetsMixin {
     setFreezeSync(enabled: boolean): void;
 }
 export declare class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
-    getCommandSheetTarget(commandInfo: ICommandInfo<object>): Nullable<{
+    createWorkbook(data: Partial<IWorkbookData>, options?: ICreateUnitOptions): FWorkbook;
+    getActiveWorkbook(): FWorkbook | null;
+    getWorkbook(id: string): FWorkbook | null;
+    getSheetCommandTarget(params?: {
+        unitId?: string;
+        subUnitId?: string;
+        sheetId?: string;
+    }): {
         workbook: FWorkbook;
         worksheet: FWorksheet;
-    }>;
-    getSheetTarget(unitId: string, subUnitId: string): Nullable<{
+        unitId: string;
+        subUnitId: string;
+    } | null;
+    getActiveSheet(): {
         workbook: FWorkbook;
         worksheet: FWorksheet;
-    }>;
-    private _initWorkbookEvent;
+    } | null;
+    setFreezeSync(enabled: boolean): void;
     /**
      * @ignore
      */
     _initialize(injector: Injector): void;
-    createUniverSheet(data: Partial<IWorkbookData>, options?: ICreateUnitOptions): FWorkbook;
-    createWorkbook(data: Partial<IWorkbookData>, options?: ICreateUnitOptions): FWorkbook;
-    getActiveWorkbook(): FWorkbook | null;
-    getActiveUniverSheet(): FWorkbook | null;
-    getUniverSheet(id: string): FWorkbook | null;
-    getWorkbook(id: string): FWorkbook | null;
-    onUniverSheetCreated(callback: (workbook: FWorkbook) => void): IDisposable;
-    getActiveSheet(): Nullable<{
-        workbook: FWorkbook;
-        worksheet: FWorksheet;
-    }>;
-    setFreezeSync(enabled: boolean): void;
+    private _initWorkbookEvent;
 }
 declare module '@univerjs/core/facade' {
     interface FUniver extends IFUniverSheetsMixin {

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

@@ -13,11 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { CommandListener, CustomData, IDisposable, IRange, IStyleData, IWorkbookData, IWorksheetData, LocaleType, Workbook } from '@univerjs/core';
+import type { CommandListener, CustomData, IDisposable, IRange, IStyleData, IWorkbookData, IWorksheetData, Workbook } from '@univerjs/core';
 import type { ISetDefinedNameMutationParam } from '@univerjs/engine-formula';
 import type { IRangeThemeStyleJSON } from '@univerjs/sheets';
 import type { FontLine as _FontLine } from './f-range';
-import { ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService, LocaleService } from '@univerjs/core';
+import { ICommandService, ILogService, Injector, IPermissionService, IResourceLoaderService, IUniverInstanceService } from '@univerjs/core';
 import { FBaseInitialable } from '@univerjs/core/facade';
 import { IDefinedNamesService } from '@univerjs/engine-formula';
 import { RangeThemeStyle, SheetsSelectionsService } from '@univerjs/sheets';
@@ -38,10 +38,9 @@ export declare class FWorkbook extends FBaseInitialable {
     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, _localeService: LocaleService, _definedNamesService: IDefinedNamesService);
+    constructor(_workbook: Workbook, _injector: Injector, _resourceLoaderService: IResourceLoaderService, _selectionManagerService: SheetsSelectionsService, _univerInstanceService: IUniverInstanceService, _commandService: ICommandService, _permissionService: IPermissionService, _logService: ILogService, _definedNamesService: IDefinedNamesService);
     /**
      * Get the Workbook instance.
      * @returns {Workbook} The Workbook instance.
@@ -102,18 +101,6 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     save(): IWorkbookData;
-    /**
-     * @deprecated use 'save' instead.
-     * @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;
     /**
      * Get the active sheet of the workbook.
      * @returns {FWorksheet} The active sheet of the workbook
@@ -122,6 +109,7 @@ export declare class FWorkbook extends FBaseInitialable {
      * // The code below gets the active sheet of the workbook
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     * if (!fWorksheet) return;
      * console.log(fWorksheet);
      * ```
      */
@@ -374,7 +362,9 @@ export declare class FWorkbook extends FBaseInitialable {
      * @example
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const range = fWorkbook.getActiveSheet().getRange('A10:B10');
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
+     * const range = fWorksheet.getRange('A10:B10');
      * fWorkbook.setActiveRange(range);
      * ```
      */
@@ -418,7 +408,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```ts
      * // The code below duplicates the given worksheet
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const activeSheet = fWorkbook.getActiveSheet();
+     * const activeSheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!activeSheet) return;
      * const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet);
      * console.log(duplicatedSheet);
      * ```
@@ -446,35 +437,6 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```
      */
     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 fWorkbook = univerAPI.getActiveWorkbook();
-     * console.log(fWorkbook.getLocale());
-     * ```
-     */
-    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
-     * const fWorkbook = univerAPI.getActiveWorkbook();
-     * fWorkbook.setSpreadsheetLocale(univerAPI.Enum.LocaleType.EN_US);
-     * console.log(fWorkbook.getLocale());
-     * ```
-     */
-    setSpreadsheetLocale(locale: LocaleType): FWorkbook;
     /**
      * Get the URL of the workbook.
      * @returns {string} The URL of the workbook
@@ -496,7 +458,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * ```ts
      * // The code below moves the sheet to the specified index
      * const fWorkbook = univerAPI.getActiveWorkbook();
-     * const sheet = fWorkbook.getActiveSheet();
+     * const sheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!sheet) return;
      * fWorkbook.moveSheet(sheet, 1);
      * ```
      */
@@ -750,7 +713,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * fWorkbook.addStyles(styles);
      *
      * // Set values with the new styles
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   [{ v: 'Hello', s: 'custom-style-1' }, { v: 'Univer', s: 'custom-style-1' }],
@@ -783,7 +747,8 @@ export declare class FWorkbook extends FBaseInitialable {
      * fWorkbook.addStyles(styles);
      *
      * // Set values with the new styles
-     * const fWorksheet = fWorkbook.getActiveSheet();
+     * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+     * if (!fWorksheet) return;
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   [{ v: 'Hello', s: 'custom-style-1' }, { v: 'Univer', s: 'custom-style-1' }],