Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat(facade): add event support for sheets & sheets-ui (#4491)

zhangw635cc813daf2
diff --git a/packages/sheets-crosshair-highlight/src/facade/f-univer.ts b/packages/sheets-crosshair-highlight/src/facade/f-univer.ts
index 0f9f75a3fd..88d474c432 100644
--- a/packages/sheets-crosshair-highlight/src/facade/f-univer.ts
+++ b/packages/sheets-crosshair-highlight/src/facade/f-univer.ts
@@ -14,25 +14,160 @@
* limitations under the License.
*/
+import type { IEventBase, Injector } from '@univerjs/core';
import type { ISetCrosshairHighlightColorOperationParams } from '@univerjs/sheets-crosshair-highlight';
-import { FUniver } from '@univerjs/core';
-import { DisableCrosshairHighlightOperation, EnableCrosshairHighlightOperation, SetCrosshairHighlightColorOperation } from '@univerjs/sheets-crosshair-highlight';
+import type { FWorkbook, FWorksheet } from '@univerjs/sheets/facade';
+import { FUniver, ICommandService } from '@univerjs/core';
+import { CROSSHAIR_HIGHLIGHT_COLORS, DisableCrosshairHighlightOperation, EnableCrosshairHighlightOperation, SetCrosshairHighlightColorOperation, SheetsCrosshairHighlightService } from '@univerjs/sheets-crosshair-highlight';
+
+export interface IFSheetCrosshairHighlightEventMixin {
+ /**
+ * Triggered when the crosshair highlight is enabled or disabled.
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.CrosshairHighlightEnabledChanged, (event) => {
+ * const enabled = event.enabled;
+ * const workbook = event.workbook;
+ * const worksheet = event.worksheet;
+ * });
+ * ```
+ */
+ readonly CrosshairHighlightEnabledChanged: 'CrosshairHighlightEnabledChanged';
+ /**
+ * Triggered when the crosshair highlight color is changed.
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.CrosshairHighlightColorChanged, (event) => {
+ * const color = event.color;
+ * const workbook = event.workbook;
+ * const worksheet = event.worksheet;
+ * });
+ * ```
+ */
+ readonly CrosshairHighlightColorChanged: 'CrosshairHighlightColorChanged';
+}
+
+export interface ICrosshairHighlightEnabledChangedEvent extends IEventBase {
+ /**
+ * Whether the crosshair highlight is enabled.
+ */
+ enabled: boolean;
+ /**
+ * The workbook that the crosshair highlight is enabled in.
+ */
+ workbook: FWorkbook;
+ /**
+ * The worksheet that the crosshair highlight is enabled in.
+ */
+ worksheet: FWorksheet;
+}
+
+export interface ICrosshairHighlightColorChangedEvent extends IEventBase {
+ /**
+ * The color of the crosshair highlight.
+ */
+ color: string;
+ /**
+ * The workbook that the crosshair highlight is enabled in.
+ */
+ workbook: FWorkbook;
+ /**
+ * The worksheet that the crosshair highlight is enabled in.
+ */
+ worksheet: FWorksheet;
+}
+
+export class FSheetCrosshairHighlightEventMixin implements IFSheetCrosshairHighlightEventMixin {
+ get CrosshairHighlightEnabledChanged(): 'CrosshairHighlightEnabledChanged' {
+ return 'CrosshairHighlightEnabledChanged';
+ }
+
+ get CrosshairHighlightColorChanged(): 'CrosshairHighlightColorChanged' {
+ return 'CrosshairHighlightColorChanged';
+ }
+}
+
+export interface ISheetCrosshairHighlightEventConfigs {
+ CrosshairHighlightEnabledChanged: ICrosshairHighlightEnabledChangedEvent;
+ CrosshairHighlightColorChanged: ICrosshairHighlightColorChangedEvent;
+}
export interface IFUniverCrosshairHighlightMixin {
/**
* Enable or disable crosshair highlight.
* @param {boolean} enabled if crosshair highlight should be enabled
+ * @returns {FUniver} the FUniver instance
+ * @example
+ * ```ts
+ * univer.setCrosshairHighlightEnabled(true);
+ * ```
*/
setCrosshairHighlightEnabled(enabled: boolean): FUniver;
/**
* Set the color of the crosshair highlight.
* @param {string} color the color of the crosshair highlight
+ * @returns {FUniver} the FUniver instance
+ * @example
+ * ```ts
+ * univer.setCrosshairHighlightColor('#FF0000');
+ * ```
*/
setCrosshairHighlightColor(color: string): FUniver;
+
+ /**
+ * Get whether the crosshair highlight is enabled.
+ * @returns {boolean} whether the crosshair highlight is enabled
+ * @example
+ * ```ts
+ * const enabled = univer.getCrosshairHighlightEnabled();
+ * ```
+ */
+ getCrosshairHighlightEnabled(): boolean;
+
+ /**
+ * Get the color of the crosshair highlight.
+ * @returns {string} the color of the crosshair highlight
+ * @example
+ * ```ts
+ * const color = univer.getCrosshairHighlightColor();
+ * ```
+ */
+ getCrosshairHighlightColor(): string;
+
+ /**
+ * Get the available built-in colors for the crosshair highlight.
+ */
+ readonly CROSSHAIR_HIGHLIGHT_COLORS: string[];
}
export class FUniverCrosshairHighlightMixin extends FUniver implements IFUniverCrosshairHighlightMixin {
+ override _initialize(injector: Injector): void {
+ const commandService = injector.get(ICommandService);
+
+ this.disposeWithMe(commandService.onCommandExecuted((commandInfo) => {
+ if (commandInfo.id === EnableCrosshairHighlightOperation.id || commandInfo.id === DisableCrosshairHighlightOperation.id) {
+ const activeSheet = this.getActiveSheet();
+ if (!activeSheet) return;
+ if (!this._eventListend(this.Event.CrosshairHighlightEnabledChanged)) return;
+ this.fireEvent(this.Event.CrosshairHighlightEnabledChanged, {
+ enabled: this.getCrosshairHighlightEnabled(),
+ ...activeSheet,
+ });
+ }
+
+ if (commandInfo.id === SetCrosshairHighlightColorOperation.id) {
+ const activeSheet = this.getActiveSheet();
+ if (!activeSheet) return;
+ if (!this._eventListend(this.Event.CrosshairHighlightColorChanged)) return;
+ this.fireEvent(this.Event.CrosshairHighlightColorChanged, {
+ color: this.getCrosshairHighlightColor(),
+ ...activeSheet,
+ });
+ }
+ }));
+ }
+
override setCrosshairHighlightEnabled(enabled: boolean): FUniver {
if (enabled) {
this._commandService.syncExecuteCommand(EnableCrosshairHighlightOperation.id);
@@ -49,10 +184,30 @@ export class FUniverCrosshairHighlightMixin extends FUniver implements IFUniverC
} as ISetCrosshairHighlightColorOperationParams);
return this;
}
+
+ override getCrosshairHighlightEnabled(): boolean {
+ const crosshairHighlightService = this._injector.get(SheetsCrosshairHighlightService);
+ return crosshairHighlightService.enabled;
+ }
+
+ override getCrosshairHighlightColor(): string {
+ const crosshairHighlightService = this._injector.get(SheetsCrosshairHighlightService);
+ return crosshairHighlightService.color;
+ }
+
+ override get CROSSHAIR_HIGHLIGHT_COLORS(): string[] {
+ return CROSSHAIR_HIGHLIGHT_COLORS;
+ }
}
FUniver.extend(FUniverCrosshairHighlightMixin);
declare module '@univerjs/core' {
// eslint-disable-next-line ts/naming-convention
interface FUniver extends IFUniverCrosshairHighlightMixin {}
+
+ // eslint-disable-next-line ts/naming-convention
+ interface FEventName extends IFSheetCrosshairHighlightEventMixin {
+ }
+
+ interface IEventParamConfig extends ISheetCrosshairHighlightEventConfigs {}
}
diff --git a/packages/sheets-crosshair-highlight/src/index.ts b/packages/sheets-crosshair-highlight/src/index.ts
index f917a1647f..0bc2dfb5d4 100644
--- a/packages/sheets-crosshair-highlight/src/index.ts
+++ b/packages/sheets-crosshair-highlight/src/index.ts
@@ -17,7 +17,7 @@
import './global.css';
export { UniverSheetsCrosshairHighlightPlugin } from './plugin';
-export { CROSSHAIR_HIGHLIGHT_COLORS } from './services/crosshair.service';
+export { CROSSHAIR_HIGHLIGHT_COLORS, SheetsCrosshairHighlightService } from './services/crosshair.service';
// #region commands
diff --git a/packages/sheets-ui/src/controllers/hover-render.controller.ts b/packages/sheets-ui/src/controllers/hover-render.controller.ts
index 575040d21d..9e2fb1e8ec 100644
--- a/packages/sheets-ui/src/controllers/hover-render.controller.ts
+++ b/packages/sheets-ui/src/controllers/hover-render.controller.ts
@@ -18,6 +18,7 @@ import type { Nullable, Workbook } from '@univerjs/core';
import type { IRenderContext, IRenderModule } from '@univerjs/engine-render';
import type { ISheetSkeletonManagerParam } from '../services/sheet-skeleton-manager.service';
import { Disposable, DisposableCollection, fromEventSubject, Inject } from '@univerjs/core';
+import { SHEET_VIEW_KEY } from '../common/keys';
import { HoverManagerService } from '../services/hover-manager.service';
import { SheetScrollManagerService } from '../services/scroll-manager.service';
import { SheetSkeletonManagerService } from '../services/sheet-skeleton-manager.service';
@@ -41,6 +42,7 @@ export class HoverRenderController extends Disposable implements IRenderModule {
this._initScrollEvent();
}
+ // eslint-disable-next-line max-lines-per-function
private _initPointerEvent() {
const disposeSet = new DisposableCollection();
const handleSkeletonChange = (skeletonParam: Nullable<ISheetSkeletonManagerParam>) => {
@@ -50,7 +52,7 @@ export class HoverRenderController extends Disposable implements IRenderModule {
return;
}
- const { mainComponent, unitId } = this._context;
+ const { mainComponent, unitId, components } = this._context;
if (!mainComponent) {
return;
}
@@ -73,10 +75,53 @@ export class HoverRenderController extends Disposable implements IRenderModule {
this._hoverManagerService.triggerClick(unitId, evt.offsetX, evt.offsetY);
}));
+ disposeSet.add(mainComponent.onDblclick$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerDbClick(unitId, evt.offsetX, evt.offsetY);
+ }));
+
disposeSet.add(mainComponent.onPointerLeave$.subscribeEvent(() => {
- // this._hoverManagerService.triggerMouseLeave(unitId);
this._active = false;
}));
+
+ const rowHeader = components.get(SHEET_VIEW_KEY.ROW);
+ const colHeader = components.get(SHEET_VIEW_KEY.COLUMN);
+ if (rowHeader) {
+ disposeSet.add(rowHeader.onPointerMove$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerRowHeaderMouseMove(unitId, evt.offsetX, evt.offsetY);
+ }));
+
+ disposeSet.add(rowHeader.onPointerDown$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerRowHeaderPoniterDown(unitId, evt.offsetX, evt.offsetY);
+ }));
+
+ disposeSet.add(rowHeader.onPointerUp$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerRowHeaderPoniterUp(unitId, evt.offsetX, evt.offsetY);
+ this._hoverManagerService.triggerRowHeaderClick(unitId, evt.offsetX, evt.offsetY);
+ }));
+
+ disposeSet.add(rowHeader.onDblclick$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerRowHeaderDbClick(unitId, evt.offsetX, evt.offsetY);
+ }));
+ }
+
+ if (colHeader) {
+ disposeSet.add(colHeader.onPointerMove$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerColHeaderMouseMove(unitId, evt.offsetX, evt.offsetY);
+ }));
+
+ disposeSet.add(colHeader.onPointerDown$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerColHeaderPoniterDown(unitId, evt.offsetX, evt.offsetY);
+ }));
+
+ disposeSet.add(colHeader.onPointerUp$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerColHeaderPoniterUp(unitId, evt.offsetX, evt.offsetY);
+ this._hoverManagerService.triggerColHeaderClick(unitId, evt.offsetX, evt.offsetY);
+ }));
+
+ disposeSet.add(colHeader.onDblclick$.subscribeEvent((evt) => {
+ this._hoverManagerService.triggerColHeaderDbClick(unitId, evt.offsetX, evt.offsetY);
+ }));
+ }
};
handleSkeletonChange(this._sheetSkeletonManagerService.getCurrent());
diff --git a/packages/sheets-ui/src/facade/f-event.ts b/packages/sheets-ui/src/facade/f-event.ts
index 323680cc16..b60bc4148f 100644
--- a/packages/sheets-ui/src/facade/f-event.ts
+++ b/packages/sheets-ui/src/facade/f-event.ts
@@ -15,7 +15,8 @@
*/
import type { IEventBase, IRange, RichTextValue } from '@univerjs/core';
-import type { DeviceInputEventType } from '@univerjs/engine-render';
+import type { DeviceInputEventType, SpreadsheetSkeleton } from '@univerjs/engine-render';
+import type { CommandListenerSkeletonChange, CommandListenerValueChange } from '@univerjs/sheets';
import type { FRange, FWorkbook, FWorksheet } from '@univerjs/sheets/facade';
import type { KeyCode } from '@univerjs/ui';
import { FEventName } from '@univerjs/core';
@@ -264,7 +265,9 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when a cell is clicked
* @example
* ```ts
- * univerAPI.getActiveWorkbook().addEvent('CellClicked', (p)=> console.log(p));
+ * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.CellClicked, (params)=> {
+ * const { worksheet, workbook, row, column, value, isZenEditor } = params;
+ * });
* ```
*/
readonly CellClicked: 'CellClicked';
@@ -272,7 +275,9 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when a cell is pointer down
* @example
* ```ts
- * univerAPI.getActiveWorkbook().addEvent('CellPointerDown', (p)=> console.log(p));
+ * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.CellPointerDown, (params)=> {
+ * const { worksheet, workbook, row, column } = params;
+ * });
* ```
*/
readonly CellPointerDown: 'CellPointerDown';
@@ -281,7 +286,9 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when a cell is pointer up
* @example
* ```ts
- * univerAPI.getActiveWorkbook().addEvent('CellPointerUp', (p)=> console.log(p));
+ * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.CellPointerUp, (params)=> {
+ * const { worksheet, workbook, row, column } = params;
+ * });
* ```
*/
readonly CellPointerUp: 'CellPointerUp';
@@ -290,7 +297,9 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when a cell is hovered
* @example
* ```ts
- * univerAPI.getActiveWorkbook().addEvent('CellHover', (p)=> console.log(p));
+ * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.CellHover, (params)=> {
+ * const { worksheet, workbook, row, column } = params;
+ * });
* ```
*/
readonly CellHover: 'CellHover';
@@ -298,15 +307,116 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when move on spreadsheet cells
* @example
* ```ts
- * univerAPI.getActiveWorkbook().addEvent('CellPointerMove', (p)=> console.log(p));
+ * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.CellPointerMove, (params)=> {
+ * const { worksheet, workbook, row, column } = params;
+ * });
* ```
*/
readonly CellPointerMove: 'CellPointerMove';
+
+ /**
+ * Triggered when a row header is clicked
+ * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.RowHeaderClick, (params) => {
+ * console.log(`Row ${params.row} header clicked in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly RowHeaderClick: 'RowHeaderClick';
+
+ /**
+ * Triggered when pointer is pressed down on a row header
+ * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.RowHeaderPointerDown, (params) => {
+ * console.log(`Pointer down on row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly RowHeaderPointerDown: 'RowHeaderPointerDown';
+
+ /**
+ * Triggered when pointer is released on a row header
+ * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.RowHeaderPointerUp, (params) => {
+ * console.log(`Pointer up on row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly RowHeaderPointerUp: 'RowHeaderPointerUp';
+
+ /**
+ * Triggered when pointer hovers over a row header
+ * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.RowHeaderHover, (params) => {
+ * console.log(`Hovering over row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly RowHeaderHover: 'RowHeaderHover';
+
+ /**
+ * Triggered when a column header is clicked
+ * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.ColumnHeaderClick, (params) => {
+ * console.log(`Column ${params.column} header clicked in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly ColumnHeaderClick: 'ColumnHeaderClick';
+
+ /**
+ * Triggered when pointer is pressed down on a column header
+ * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.ColumnHeaderPointerDown, (params) => {
+ * console.log(`Pointer down on column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly ColumnHeaderPointerDown: 'ColumnHeaderPointerDown';
+
+ /**
+ * Triggered when pointer is released on a column header
+ * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.ColumnHeaderPointerUp, (params) => {
+ * console.log(`Pointer up on column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly ColumnHeaderPointerUp: 'ColumnHeaderPointerUp';
+
+ /**
+ * Triggered when pointer hovers over a column header
+ * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+ * @example
+ * ```typescript
+ * univerAPI.onSheetEvent(Event.ColumnHeaderHover, (params) => {
+ * console.log(`Hovering over column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);
+ * });
+ * ```
+ */
+ readonly ColumnHeaderHover: 'ColumnHeaderHover';
+
/**
* Event fired when drag over spreadsheet cells
* @example
* ```ts
- * univerAPI.getActiveWorkbook().addEvent('DragOver', (p)=> console.log(p));
+ * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.DragOver, (params)=> {
+ * const { worksheet, workbook, row, column } = params;
+ * });
* ```
*/
readonly DragOver: 'DragOver';
@@ -315,7 +425,9 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when drop on spreadsheet cells
* @example
* ```ts
- * univerAPI.addEvent('Drop', (p)=> console.log(p));
+ * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.Drop, (params)=> {
+ * const { worksheet, workbook, row, column } = params;
+ * });
* ```
*/
readonly Drop: 'Drop';
@@ -324,7 +436,9 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when scroll spreadsheet.
* @example
* ```ts
- * univerAPI.addEvent('Scroll', (p)=> console.log(p));
+ * univerAPI.addEvent(univerAPI.Event.Scroll, (params)=> {
+ * const { worksheet, workbook, scrollX, scrollY } = params;
+ * });
* ```
*/
readonly Scroll: 'Scroll';
@@ -333,16 +447,20 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when selection changed.
* @example
* ```ts
- * univerAPI.addEvent('SelectionChanged', (p)=> console.log(p));
+ * univerAPI.addEvent(univerAPI.Event.SelectionChanged, (p)=> {
+ * const { worksheet, workbook, selections } = p;
+ * });
* ```
*/
readonly SelectionChanged: 'SelectionChanged';
/**
- * Event fired when selection move end
+ * Event fired when selection move start
* @example
* ```ts
- * univerAPI.addEvent('SelectionMoveStart', (p)=> console.log(p));
+ * univerAPI.addEvent(univerAPI.Event.SelectionMoveStart, (p)=> {
+ * const { worksheet, workbook, selections } = p;
+ * });
* ```
*/
readonly SelectionMoveStart: 'SelectionMoveStart';
@@ -351,7 +469,9 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when selection move end
* @example
* ```ts
- * univerAPI.addEvent('SelectionMoving', (p)=> console.log(p));
+ * univerAPI.addEvent(univerAPI.Event.SelectionMoving, (p)=> {
+ * const { worksheet, workbook, selections } = p;
+ * });
* ```
*/
readonly SelectionMoving: 'SelectionMoving';
@@ -360,11 +480,57 @@ export interface IFSheetsUIEventNameMixin {
* Event fired when selection move end
* @example
* ```ts
- * univerAPI.addEvent('SelectionMoveEnd', (p)=> console.log(p));
+ * univerAPI.addEvent(univerAPI.Event.SelectionMoveEnd, (p)=> {
+ * const { worksheet, workbook, selections } = p;
+ * });
* ```
*/
readonly SelectionMoveEnd: 'SelectionMoveEnd';
+ /**
+ * Event fired when zoom changed
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.SheetZoomChanged, (p)=> {
+ * const { worksheet, workbook, zoom } = p;
+ * });
+ * ```
+ */
+ readonly SheetZoomChanged: 'SheetZoomChanged';
+
+ /**
+ * Event fired before zoom changed
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeSheetZoomChange, (p)=> {
+ * const { worksheet, workbook, zoom } = p;
+ * });
+ * ```
+ */
+ readonly BeforeSheetZoomChange: 'BeforeSheetZoomChange';
+
+ /**
+ * Event fired when sheet skeleton changed
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.SheetSkeletonChanged, (p)=> {
+ * const { worksheet, workbook } = p;
+ * });
+ * ```
+ */
+ readonly SheetSkeletonChanged: 'SheetSkeletonChanged';
+
+ /**
+ * Event fired when sheet value changed
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (p)=> {
+ * const { workbook, effectedRanges, payload } = p;
+ * });
+ * ```
+ */
+ readonly SheetValueChanged: 'SheetValueChanged';
+
}
export class FSheetsUIEventName extends FEventName implements IFSheetsUIEventNameMixin {
@@ -451,6 +617,46 @@ export class FSheetsUIEventName extends FEventName implements IFSheetsUIEventNam
override get SelectionMoveEnd(): 'SelectionMoveEnd' {
return 'SelectionMoveEnd' as const;
}
+
+ override get RowHeaderClick(): 'RowHeaderClick' {
+ return 'RowHeaderClick' as const;
+ }
+
+ override get RowHeaderPointerDown(): 'RowHeaderPointerDown' {
+ return 'RowHeaderPointerDown' as const;
+ }
+
+ override get RowHeaderPointerUp(): 'RowHeaderPointerUp' {
+ return 'RowHeaderPointerUp' as const;
+ }
+
+ override get RowHeaderHover(): 'RowHeaderHover' {
+ return 'RowHeaderHover' as const;
+ }
+
+ override get ColumnHeaderClick(): 'ColumnHeaderClick' {
+ return 'ColumnHeaderClick' as const;
+ }
+
+ override get ColumnHeaderPointerDown(): 'ColumnHeaderPointerDown' {
+ return 'ColumnHeaderPointerDown' as const;
+ }
+
+ override get ColumnHeaderPointerUp(): 'ColumnHeaderPointerUp' {
+ return 'ColumnHeaderPointerUp' as const;
+ }
+
+ override get ColumnHeaderHover(): 'ColumnHeaderHover' {
+ return 'ColumnHeaderHover' as const;
+ }
+
+ override get SheetSkeletonChanged(): 'SheetSkeletonChanged' {
+ return 'SheetSkeletonChanged' as const;
+ }
+
+ override get SheetValueChanged(): 'SheetValueChanged' {
+ return 'SheetValueChanged' as const;
+ }
}
export interface ISheetUIEventBase extends IEventBase {
@@ -513,6 +719,21 @@ export interface IBeforeClipboardPasteParam extends IEventBase {
export type IClipboardPastedParam = IBeforeClipboardPasteParam;
+export interface ISheetZoomEvent extends IEventBase {
+ /**
+ * Zoom ratio
+ */
+ zoom: number;
+ /**
+ * The workbook instance currently being operated on. {@link FWorkbook}
+ */
+ workbook: FWorkbook;
+ /**
+ * The worksheet instance currently being operated on. {@link FWorkbook}
+ */
+ worksheet: FWorksheet;
+}
+
export interface ICellEventParam extends ISheetUIEventBase {
row: number;
column: number;
@@ -527,6 +748,24 @@ export interface ISelectionEventParam extends ISheetUIEventBase {
selections: IRange[];
}
+export interface ISheetRowHeaderEvent extends ISheetUIEventBase {
+ row: number;
+}
+
+export interface ISheetColumnHeaderEvent extends ISheetUIEventBase {
+ column: number;
+}
+
+export interface ISheetSkeletonChangedEvent extends ISheetUIEventBase {
+ skeleton: SpreadsheetSkeleton;
+ payload: CommandListenerSkeletonChange;
+}
+
+export interface ISheetValueChangedEvent extends IEventBase {
+ effectedRanges: FRange[];
+ payload: CommandListenerValueChange;
+}
+
export interface IFSheetsUIEventParamConfig {
BeforeClipboardChange: IBeforeClipboardChangeParam;
ClipboardChanged: IClipboardChangedParam;
@@ -547,12 +786,30 @@ export interface IFSheetsUIEventParamConfig {
Drop: ICellEventParam;
DragOver: ICellEventParam;
+ RowHeaderClick: ISheetRowHeaderEvent;
+ RowHeaderDbClick: ISheetRowHeaderEvent;
+ RowHeaderHover: ISheetRowHeaderEvent;
+ RowHeaderPointerDown: ISheetRowHeaderEvent;
+ RowHeaderPointerUp: ISheetRowHeaderEvent;
+
+ ColumnHeaderClick: ISheetColumnHeaderEvent;
+ ColumnHeaderDbClick: ISheetColumnHeaderEvent;
+ ColumnHeaderHover: ISheetColumnHeaderEvent;
+ ColumnHeaderPointerDown: ISheetColumnHeaderEvent;
+ ColumnHeaderPointerUp: ISheetColumnHeaderEvent;
+
Scroll: IScrollEventParam;
SelectionChanging: ISelectionEventParam;
SelectionMoveStart: ISelectionEventParam;
SelectionMoving: ISelectionEventParam;
SelectionMoveEnd: ISelectionEventParam;
SelectionChanged: ISelectionEventParam;
+
+ SheetZoomChanged: ISheetZoomEvent;
+ BeforeSheetZoomChange: ISheetZoomEvent;
+
+ SheetSkeletonChanged: ISheetSkeletonChangedEvent;
+ SheetValueChanged: ISheetValueChangedEvent;
}
FEventName.extend(FSheetsUIEventName);
diff --git a/packages/sheets-ui/src/facade/f-univer.ts b/packages/sheets-ui/src/facade/f-univer.ts
index 83f5b52859..d9ccd11f21 100644
--- a/packages/sheets-ui/src/facade/f-univer.ts
+++ b/packages/sheets-ui/src/facade/f-univer.ts
@@ -25,13 +25,15 @@ import type {
SpreadsheetColumnHeader,
SpreadsheetRowHeader,
} from '@univerjs/engine-render';
-import type { IEditorBridgeServiceVisibleParam, ISheetPasteByShortKeyParams, IViewportScrollState } from '@univerjs/sheets-ui';
+import type { CommandListenerSkeletonChange, CommandListenerValueChange } from '@univerjs/sheets';
+import type { IEditorBridgeServiceVisibleParam, ISetZoomRatioCommandParams, ISheetPasteByShortKeyParams, IViewportScrollState } from '@univerjs/sheets-ui';
+import type { FRange } from '@univerjs/sheets/facade';
import type { IBeforeClipboardChangeParam, IBeforeClipboardPasteParam, IBeforeSheetEditEndEventParams, IBeforeSheetEditStartEventParams, ISheetEditChangingEventParams, ISheetEditEndedEventParams, ISheetEditStartedEventParams } from './f-event';
import { CanceledError, DisposableCollection, DOCS_NORMAL_EDITOR_UNIT_ID_KEY, FUniver, ICommandService, ILogService, IUniverInstanceService, LifecycleService, LifecycleStages, RichTextValue, toDisposable, UniverInstanceType } from '@univerjs/core';
import { RichTextEditingMutation } from '@univerjs/docs';
import { IRenderManagerService } from '@univerjs/engine-render';
-import { SheetsSelectionsService } from '@univerjs/sheets';
-import { DragManagerService, HoverManagerService, IEditorBridgeService, ISheetClipboardService, SetCellEditVisibleOperation, SHEET_VIEW_KEY, SheetPasteShortKeyCommand, SheetScrollManagerService } from '@univerjs/sheets-ui';
+import { COMMAND_LISTENER_SKELETON_CHANGE, COMMAND_LISTENER_VALUE_CHANGE, getValueChangedEffectedRange, SheetsSelectionsService } from '@univerjs/sheets';
+import { DragManagerService, HoverManagerService, IEditorBridgeService, ISheetClipboardService, SetCellEditVisibleOperation, SetZoomRatioCommand, SHEET_VIEW_KEY, SheetPasteShortKeyCommand, SheetScrollManagerService } from '@univerjs/sheets-ui';
import { FSheetHooks } from '@univerjs/sheets/facade';
import { CopyCommand, CutCommand, HTML_CLIPBOARD_MIME_TYPE, IClipboardInterfaceService, KeyCode, PasteCommand, PLAIN_TEXT_CLIPBOARD_MIME_TYPE, supportClipboardAPI } from '@univerjs/ui';
import { combineLatest, filter } from 'rxjs';
@@ -134,8 +136,25 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix
}
}
}
+
+ if (commandInfo.id === SetZoomRatioCommand.id) {
+ if (!this._eventListend(this.Event.BeforeSheetZoomChange)) {
+ return;
+ }
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) {
+ return;
+ }
+ const { workbook, worksheet } = target;
+ this.fireEvent(this.Event.BeforeSheetZoomChange, {
+ zoom: (commandInfo.params as ISetZoomRatioCommandParams).zoomRatio,
+ workbook,
+ worksheet,
+ });
+ }
}));
+ // eslint-disable-next-line max-lines-per-function
this.disposeWithMe(commandService.onCommandExecuted((commandInfo) => {
if (commandInfo.id === SetCellEditVisibleOperation.id) {
if (!this._eventListend(this.Event.SheetEditStarted) && !this._eventListend(this.Event.SheetEditEnded)) {
@@ -204,6 +223,22 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix
this.fireEvent(this.Event.SheetEditChanging, eventParams);
}
}
+
+ if (commandInfo.id === SetZoomRatioCommand.id) {
+ if (!this._eventListend(this.Event.SheetZoomChanged)) {
+ return;
+ }
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) {
+ return;
+ }
+ const { workbook, worksheet } = target;
+ this.fireEvent(this.Event.SheetZoomChanged, {
+ zoom: worksheet.getZoom(),
+ workbook,
+ worksheet,
+ });
+ }
}));
this._initObserverListener(injector);
@@ -233,7 +268,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix
if (!hoverManagerService) return;
disposable.add(
hoverManagerService.currentClickedCell$
- .pipe(filter((cell) => !!cell))
+ ?.pipe(filter((cell) => !!cell))
.subscribe((cell) => {
if (!this._eventListend(this.Event.CellClicked)) return;
const baseParams = this.getSheetTarget(cell.location.unitId, cell.location.subUnitId);
@@ -309,7 +344,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix
disposable.add(
dragManagerService.currentCell$
- .pipe(filter((cell) => !!cell))
+ ?.pipe(filter((cell) => !!cell))
.subscribe((cell) => {
if (!this._eventListend(this.Event.DragOver)) return;
const baseParams = this.getSheetTarget(cell.location.unitId, cell.location.subUnitId);
@@ -325,7 +360,7 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix
disposable.add(
dragManagerService.endCell$
- .pipe(filter((cell) => !!cell))
+ ?.pipe(filter((cell) => !!cell))
.subscribe((cell) => {
if (!this._eventListend(this.Event.Drop)) return;
const baseParams = this.getSheetTarget(cell.location.unitId, cell.location.subUnitId);
@@ -338,6 +373,120 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix
});
})
);
+
+ // Row Header Events
+ disposable.add(
+ hoverManagerService.currentRowHeaderClick$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.RowHeaderClick)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.RowHeaderClick, {
+ ...baseParams,
+ row: header.index,
+ });
+ })
+ );
+
+ disposable.add(
+ hoverManagerService.currentRowHeaderPointerDown$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.RowHeaderPointerDown)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.RowHeaderPointerDown, {
+ ...baseParams,
+ row: header.index,
+ });
+ })
+ );
+
+ disposable.add(
+ hoverManagerService.currentRowHeaderPointerUp$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.RowHeaderPointerUp)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.RowHeaderPointerUp, {
+ ...baseParams,
+ row: header.index,
+ });
+ })
+ );
+
+ disposable.add(
+ hoverManagerService.currentHoveredRowHeader$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.RowHeaderHover)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.RowHeaderHover, {
+ ...baseParams,
+ row: header.index,
+ });
+ })
+ );
+
+ // Column Header Events
+ disposable.add(
+ hoverManagerService.currentColHeaderClick$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.ColumnHeaderClick)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.ColumnHeaderClick, {
+ ...baseParams,
+ column: header.index,
+ });
+ })
+ );
+
+ disposable.add(
+ hoverManagerService.currentColHeaderPointerDown$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.ColumnHeaderPointerDown)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.ColumnHeaderPointerDown, {
+ ...baseParams,
+ column: header.index,
+ });
+ })
+ );
+
+ disposable.add(
+ hoverManagerService.currentColHeaderPointerUp$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.ColumnHeaderPointerUp)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.ColumnHeaderPointerUp, {
+ ...baseParams,
+ column: header.index,
+ });
+ })
+ );
+
+ disposable.add(
+ hoverManagerService.currentHoveredColHeader$
+ ?.pipe(filter((header) => !!header))
+ .subscribe((header) => {
+ if (!this._eventListend(this.Event.ColumnHeaderHover)) return;
+ const baseParams = this.getSheetTarget(header.unitId, header.subUnitId);
+ if (!baseParams) return;
+ this.fireEvent(this.Event.ColumnHeaderHover, {
+ ...baseParams,
+ column: header.index,
+ });
+ })
+ );
}));
this.disposeWithMe(disposable);
@@ -429,6 +578,31 @@ export class FUniverSheetsUIMixin extends FUniver implements IFUniverSheetsUIMix
}
}));
this.disposeWithMe(commandService.onCommandExecuted((commandInfo) => {
+ if (COMMAND_LISTENER_SKELETON_CHANGE.indexOf(commandInfo.id) > -1) {
+ if (!this._eventListend(this.Event.SheetSkeletonChanged)) return;
+ const sheet = this.getActiveSheet();
+ if (!sheet) return;
+ this.fireEvent(this.Event.SheetSkeletonChanged, {
+ workbook: sheet.workbook,
+ worksheet: sheet.worksheet,
+ payload: commandInfo as CommandListenerSkeletonChange,
+ skeleton: sheet.worksheet.getSkeleton()!,
+ });
+ return;
+ }
+
+ if (COMMAND_LISTENER_VALUE_CHANGE.indexOf(commandInfo.id) > -1) {
+ if (!this._eventListend(this.Event.SheetValueChanged)) return;
+ const sheet = this.getActiveSheet();
+ if (!sheet) return;
+ this.fireEvent(this.Event.SheetValueChanged, {
+ payload: commandInfo as CommandListenerValueChange,
+ effectedRanges: getValueChangedEffectedRange(commandInfo).map(
+ (range) => this.getWorkbook(range.unitId)?.getSheetBySheetId(range.subUnitId)?.getRange(range.range)
+ ).filter(Boolean) as FRange[],
+ });
+ return;
+ }
switch (commandInfo.id) {
case CopyCommand.id:
case CutCommand.id:
diff --git a/packages/sheets-ui/src/facade/f-worksheet.ts b/packages/sheets-ui/src/facade/f-worksheet.ts
index 6dd572d0f6..e6e6d0b0b4 100644
--- a/packages/sheets-ui/src/facade/f-worksheet.ts
+++ b/packages/sheets-ui/src/facade/f-worksheet.ts
@@ -14,9 +14,10 @@
* limitations under the License.
*/
-import type { IRange } from '@univerjs/core';
-import type { IScrollState } from '@univerjs/sheets-ui';
+import type { IRange, Nullable } from '@univerjs/core';
+import type { SpreadsheetSkeleton } from '@univerjs/engine-render';
+import type { IScrollState } from '@univerjs/sheets-ui';
import { ICommandService } from '@univerjs/core';
import { IRenderManagerService, SHEET_VIEWPORT_KEY, sheetContentViewportKeys } from '@univerjs/engine-render';
import { ChangeZoomRatioCommand, SheetScrollManagerService, SheetSkeletonManagerService, SheetsScrollRenderController } from '@univerjs/sheets-ui';
@@ -89,6 +90,19 @@ export interface IFWorksheetSkeletonMixin {
*/
getScrollState(): IScrollState;
+ /**
+ * Get the skeleton service of the worksheet.
+ * @returns {Nullable<SpreadsheetSkeleton>} The skeleton of the worksheet.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const skeleton = fWorksheet.getSkeleton();
+ * console.log(skeleton);
+ * ```
+ */
+ getSkeleton(): Nullable<SpreadsheetSkeleton>;
+
}
export class FWorksheetSkeletonMixin extends FWorksheet implements IFWorksheetSkeletonMixin {
@@ -184,6 +198,11 @@ export class FWorksheetSkeletonMixin extends FWorksheet implements IFWorksheetSk
const scrollState = sheetScrollManagerService.getScrollStateByParam({ unitId, sheetId });
return scrollState || emptyScrollState;
}
+
+ override getSkeleton(): Nullable<SpreadsheetSkeleton> {
+ const service = this._injector.get(IRenderManagerService).getRenderById(this._workbook.getUnitId())?.with(SheetSkeletonManagerService);
+ return service?.getWorksheetSkeleton(this._worksheet.getSheetId())?.skeleton;
+ }
}
FWorksheet.extend(FWorksheetSkeletonMixin);
diff --git a/packages/sheets-ui/src/index.ts b/packages/sheets-ui/src/index.ts
index 07d1186c13..f6df7231cc 100644
--- a/packages/sheets-ui/src/index.ts
+++ b/packages/sheets-ui/src/index.ts
@@ -163,7 +163,7 @@ export {
SetScrollRelativeCommand,
} from './commands/commands/set-scroll.command';
export { ExpandSelectionCommand, JumpOver, MoveSelectionCommand, MoveSelectionEnterAndTabCommand, SelectAllCommand } from './commands/commands/set-selection.command';
-export { ChangeZoomRatioCommand, SetZoomRatioCommand } from './commands/commands/set-zoom-ratio.command';
+export { ChangeZoomRatioCommand, type ISetZoomRatioCommandParams, SetZoomRatioCommand } from './commands/commands/set-zoom-ratio.command';
export { ShowMenuListCommand } from './commands/commands/unhide.command';
export {
ChangeSheetProtectionFromSheetBarCommand,
diff --git a/packages/sheets-ui/src/services/hover-manager.service.ts b/packages/sheets-ui/src/services/hover-manager.service.ts
index a62d081d50..175b355e5c 100644
--- a/packages/sheets-ui/src/services/hover-manager.service.ts
+++ b/packages/sheets-ui/src/services/hover-manager.service.ts
@@ -14,11 +14,12 @@
* limitations under the License.
*/
-import type { ICustomRange, IParagraph, IPosition, Nullable, Workbook } from '@univerjs/core';
-import type { IBoundRectNoAngle, IMouseEvent, IPointerEvent, SpreadsheetSkeleton } from '@univerjs/engine-render';
+import type { ICustomRange, IParagraph, IPosition, Nullable, Workbook, Worksheet } from '@univerjs/core';
+import type { IBoundRectNoAngle, IMouseEvent, IPointerEvent, IRender } from '@univerjs/engine-render';
import type { ISheetLocation, ISheetLocationBase } from '@univerjs/sheets';
+import type { ISheetSkeletonManagerParam } from './sheet-skeleton-manager.service';
import { Disposable, IUniverInstanceService, UniverInstanceType } from '@univerjs/core';
-import { IRenderManagerService } from '@univerjs/engine-render';
+import { IRenderManagerService, SHEET_VIEWPORT_KEY, Vector2 } from '@univerjs/engine-render';
import { BehaviorSubject, distinctUntilChanged, map, Subject } from 'rxjs';
import { getHoverCellPosition } from '../common/utils';
import { SheetScrollManagerService } from './scroll-manager.service';
@@ -77,6 +78,12 @@ export interface IHoverRichTextPosition extends ISheetLocationBase {
event?: IMouseEvent | IPointerEvent;
}
+export interface IHoverHeaderPosition {
+ unitId: string;
+ subUnitId: string;
+ index: number;
+}
+
export function getLocationBase(location: ISheetLocation) {
const { workbook, worksheet, ...locBase } = location;
return locBase;
@@ -86,11 +93,23 @@ export class HoverManagerService extends Disposable {
private _currentCell$ = new BehaviorSubject<Nullable<IHoverCellPosition>>(null);
private _currentRichText$ = new BehaviorSubject<Nullable<IHoverRichTextInfo>>(null);
private _currentClickedCell$ = new Subject<IHoverRichTextInfo>();
+ private _currentDbClickedCell$ = new Subject<IHoverRichTextInfo>();
private _currentCellWithEvent$ = new Subject<Nullable<ICellWithEvent>>();
private _currentPointerDownCell$ = new Subject<ICellPosWithEvent>();
private _currentPointerUpCell$ = new Subject<ICellPosWithEvent>();
+ private _currentHoveredRowHeader$ = new BehaviorSubject<Nullable<IHoverHeaderPosition>>(null);
+ private _currentHoveredColHeader$ = new BehaviorSubject<Nullable<IHoverHeaderPosition>>(null);
+ private _currentRowHeaderClick$ = new Subject<IHoverHeaderPosition>();
+ private _currentColHeaderClick$ = new Subject<IHoverHeaderPosition>();
+ private _currentRowHeaderDbClick$ = new Subject<IHoverHeaderPosition>();
+ private _currentColHeaderDbClick$ = new Subject<IHoverHeaderPosition>();
+ private _currentRowHeaderPointerDown$ = new Subject<IHoverHeaderPosition>();
+ private _currentColHeaderPointerDown$ = new Subject<IHoverHeaderPosition>();
+ private _currentRowHeaderPointerUp$ = new Subject<IHoverHeaderPosition>();
+ private _currentColHeaderPointerUp$ = new Subject<IHoverHeaderPosition>();
+
// Notify when hovering over different cells
currentCell$ = this._currentCell$.asObservable().pipe(
distinctUntilChanged(
@@ -156,16 +175,27 @@ export class HoverManagerService extends Disposable {
// Notify when mouse position changes
currentPosition$ = this._currentCell$.asObservable();
currentClickedCell$ = this._currentClickedCell$.asObservable();
+ currentDbClickedCell$ = this._currentDbClickedCell$.asObservable();
currentPointerDownCell$ = this._currentPointerDownCell$.asObservable();
currentPointerUpCell$ = this._currentPointerUpCell$.asObservable();
+ currentHoveredRowHeader$ = this._currentHoveredRowHeader$.asObservable();
+ currentHoveredColHeader$ = this._currentHoveredColHeader$.asObservable();
+ currentRowHeaderClick$ = this._currentRowHeaderClick$.asObservable();
+ currentColHeaderClick$ = this._currentColHeaderClick$.asObservable();
+ currentRowHeaderDbClick$ = this._currentRowHeaderDbClick$.asObservable();
+ currentColHeaderDbClick$ = this._currentColHeaderDbClick$.asObservable();
+ currentRowHeaderPointerDown$ = this._currentRowHeaderPointerDown$.asObservable();
+ currentColHeaderPointerDown$ = this._currentColHeaderPointerDown$.asObservable();
+ currentRowHeaderPointerUp$ = this._currentRowHeaderPointerUp$.asObservable();
+ currentColHeaderPointerUp$ = this._currentColHeaderPointerUp$.asObservable();
+
constructor(
@IUniverInstanceService private readonly _univerInstanceService: IUniverInstanceService,
@IRenderManagerService private readonly _renderManagerService: IRenderManagerService
) {
super();
- // TODO@weird94: any better solution here?
this._initCellDisposableListener();
}
@@ -194,8 +224,7 @@ export class HoverManagerService extends Disposable {
}));
}
- // eslint-disable-next-line complexity
- private _calcActiveCell(unitId: string, offsetX: number, offsetY: number) {
+ private _getCalcDeps(unitId: string) {
const workbook = this._univerInstanceService.getUnit<Workbook>(unitId, UniverInstanceType.UNIVER_SHEET);
if (!workbook) {
return null;
@@ -213,12 +242,15 @@ export class HoverManagerService extends Disposable {
const scrollManagerService = currentRender.with(SheetScrollManagerService);
const scrollInfo = scrollManagerService?.getCurrentScrollState();
- const skeleton = skeletonParam?.skeleton as SpreadsheetSkeleton;
- if (!skeleton || !scrollInfo || !currentRender) return;
+ if (!scrollInfo || !currentRender) return;
- const hoverPosition = getHoverCellPosition(currentRender, workbook, worksheet, skeletonParam, offsetX, offsetY);
+ return { currentRender, workbook, worksheet, skeletonParam };
+ }
+ private _calcActiveCell(currentRender: IRender, workbook: Workbook, worksheet: Worksheet, skeletonParam: ISheetSkeletonManagerParam, offsetX: number, offsetY: number) {
+ const hoverPosition = getHoverCellPosition(currentRender, workbook, worksheet, skeletonParam, offsetX, offsetY);
+ const skeleton = skeletonParam.skeleton;
if (!hoverPosition) {
return null;
}
@@ -270,8 +302,53 @@ export class HoverManagerService extends Disposable {
};
}
+ private _calcActiveRowHeader(unitId: string, offsetX: number, offsetY: number) {
+ const deps = this._getCalcDeps(unitId);
+ if (!deps) {
+ return;
+ }
+ const { currentRender, worksheet, skeletonParam } = deps;
+ const { scaleY } = currentRender.scene.getAncestorScale();
+ const activeViewport = currentRender.scene.getViewports().find((v) => v.isHit(new Vector2(offsetX, offsetY)));
+ if (!activeViewport || (activeViewport.viewportKey !== SHEET_VIEWPORT_KEY.VIEW_ROW_TOP && activeViewport.viewportKey !== SHEET_VIEWPORT_KEY.VIEW_ROW_BOTTOM)) {
+ return;
+ }
+ const scrollXY = {
+ x: activeViewport.viewportScrollX,
+ y: activeViewport.viewportScrollY,
+ };
+
+ const index = skeletonParam.skeleton.getRowIndexByOffsetY(offsetY, scaleY, scrollXY);
+ return { unitId, index, subUnitId: worksheet.getSheetId() };
+ }
+
+ private _calcActiveColHeader(unitId: string, offsetX: number, offsetY: number) {
+ const deps = this._getCalcDeps(unitId);
+ if (!deps) {
+ return;
+ }
+ const { currentRender, worksheet, skeletonParam } = deps;
+ const { scaleX } = currentRender.scene.getAncestorScale();
+ const activeViewport = currentRender.scene.getViewports().find((v) => v.isHit(new Vector2(offsetX, offsetY)));
+ if (!activeViewport || (activeViewport.viewportKey !== SHEET_VIEWPORT_KEY.VIEW_COLUMN_LEFT && activeViewport.viewportKey !== SHEET_VIEWPORT_KEY.VIEW_COLUMN_RIGHT)) {
+ return;
+ }
+ const scrollXY = {
+ x: activeViewport.viewportScrollX,
+ y: activeViewport.viewportScrollY,
+ };
+
+ const index = skeletonParam.skeleton.getColumnIndexByOffsetX(offsetX, scaleX, scrollXY);
+ return { unitId, index, subUnitId: worksheet.getSheetId() };
+ }
+
triggerPointerDown(unitId: string, event: IPointerEvent | IMouseEvent) {
- const activeCell = this._calcActiveCell(unitId, event.offsetX, event.offsetY);
+ const deps = this._getCalcDeps(unitId);
+ if (!deps) {
+ return;
+ }
+ const { currentRender, workbook, worksheet, skeletonParam } = deps;
+ const activeCell = this._calcActiveCell(currentRender, workbook, worksheet, skeletonParam, event.offsetX, event.offsetY);
if (activeCell && activeCell.location) {
const { unitId, subUnitId, row, col } = getLocationBase(activeCell.location);
this._currentPointerDownCell$.next({
@@ -282,7 +359,13 @@ export class HoverManagerService extends Disposable {
}
triggerPointerUp(unitId: string, event: IPointerEvent | IMouseEvent) {
- const activeCell = this._calcActiveCell(unitId, event.offsetX, event.offsetY);
+ const deps = this._getCalcDeps(unitId);
+ if (!deps) {
+ return;
+ }
+ const { currentRender, workbook, worksheet, skeletonParam } = deps;
+ const activeCell = this._calcActiveCell(currentRender, workbook, worksheet, skeletonParam, event.offsetX, event.offsetY);
+
if (activeCell) {
const location = getLocationBase(activeCell.location);
this._currentPointerUpCell$.next({
@@ -293,7 +376,13 @@ export class HoverManagerService extends Disposable {
}
triggerMouseMove(unitId: string, event: IPointerEvent | IMouseEvent) {
- const activeCell = this._calcActiveCell(unitId, event.offsetX, event.offsetY);
+ const deps = this._getCalcDeps(unitId);
+ if (!deps) {
+ return;
+ }
+ const { currentRender, workbook, worksheet, skeletonParam } = deps;
+ const activeCell = this._calcActiveCell(currentRender, workbook, worksheet, skeletonParam, event.offsetX, event.offsetY);
+
this._currentCell$.next(activeCell && {
location: getLocationBase(activeCell.location),
position: activeCell.position,
@@ -318,7 +407,12 @@ export class HoverManagerService extends Disposable {
* @param offsetY
*/
triggerClick(unitId: string, offsetX: number, offsetY: number) {
- const activeCell = this._calcActiveCell(unitId, offsetX, offsetY);
+ const deps = this._getCalcDeps(unitId);
+ if (!deps) {
+ return;
+ }
+ const { currentRender, workbook, worksheet, skeletonParam } = deps;
+ const activeCell = this._calcActiveCell(currentRender, workbook, worksheet, skeletonParam, offsetX, offsetY);
if (activeCell) {
this._currentClickedCell$.next({
...activeCell,
@@ -327,7 +421,70 @@ export class HoverManagerService extends Disposable {
}
}
+ triggerDbClick(unitId: string, offsetX: number, offsetY: number) {
+ const deps = this._getCalcDeps(unitId);
+ if (!deps) {
+ return;
+ }
+ const { currentRender, workbook, worksheet, skeletonParam } = deps;
+ const activeCell = this._calcActiveCell(currentRender, workbook, worksheet, skeletonParam, offsetX, offsetY);
+ if (activeCell) {
+ this._currentDbClickedCell$.next({
+ ...activeCell,
+ location: getLocationBase(activeCell.location),
+ });
+ }
+ }
+
triggerScroll() {
this._currentCell$.next(null);
}
+
+ triggerRowHeaderClick(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveRowHeader(unitId, offsetX, offsetY);
+ pos && this._currentRowHeaderClick$.next(pos);
+ }
+
+ triggerColHeaderClick(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveColHeader(unitId, offsetX, offsetY);
+ pos && this._currentColHeaderClick$.next(pos);
+ }
+
+ triggerRowHeaderDbClick(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveRowHeader(unitId, offsetX, offsetY);
+ pos && this._currentRowHeaderDbClick$.next(pos);
+ }
+
+ triggerColHeaderDbClick(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveColHeader(unitId, offsetX, offsetY);
+ pos && this._currentColHeaderDbClick$.next(pos);
+ }
+
+ triggerRowHeaderMouseMove(unitId: string, offsetX: number, offsetY: number) {
+ this._currentHoveredRowHeader$.next(this._calcActiveRowHeader(unitId, offsetX, offsetY));
+ }
+
+ triggerColHeaderMouseMove(unitId: string, offsetX: number, offsetY: number) {
+ this._currentHoveredColHeader$.next(this._calcActiveColHeader(unitId, offsetX, offsetY));
+ }
+
+ triggerRowHeaderPoniterDown(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveRowHeader(unitId, offsetX, offsetY);
+ pos && this._currentRowHeaderPointerDown$.next(pos);
+ }
+
+ triggerColHeaderPoniterDown(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveColHeader(unitId, offsetX, offsetY);
+ pos && this._currentColHeaderPointerDown$.next(pos);
+ }
+
+ triggerRowHeaderPoniterUp(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveRowHeader(unitId, offsetX, offsetY);
+ pos && this._currentRowHeaderPointerUp$.next(pos);
+ }
+
+ triggerColHeaderPoniterUp(unitId: string, offsetX: number, offsetY: number) {
+ const pos = this._calcActiveColHeader(unitId, offsetX, offsetY);
+ pos && this._currentColHeaderPointerUp$.next(pos);
+ }
}
diff --git a/packages/sheets-ui/src/services/selection/selection-render.service.ts b/packages/sheets-ui/src/services/selection/selection-render.service.ts
index d480fba5a0..544790f8f9 100644
--- a/packages/sheets-ui/src/services/selection/selection-render.service.ts
+++ b/packages/sheets-ui/src/services/selection/selection-render.service.ts
@@ -322,7 +322,7 @@ export class SheetSelectionRenderService extends BaseSelectionRenderService impl
* @param viewport
* @param scrollTimerType
*/
- // eslint-disable-next-line complexity
+ // eslint-disable-next-line complexity, max-lines-per-function
protected _onPointerDown(
evt: IPointerEvent | IMouseEvent,
_zIndex = 0,
diff --git a/packages/sheets/src/basics/const/command-listener-const.ts b/packages/sheets/src/basics/const/command-listener-const.ts
index b0acb6a2dc..f5cff271b7 100644
--- a/packages/sheets/src/basics/const/command-listener-const.ts
+++ b/packages/sheets/src/basics/const/command-listener-const.ts
@@ -14,6 +14,25 @@
* limitations under the License.
*/
+import type { IMoveRangeMutationParams } from '../../commands/mutations/move-range.mutation';
+import type { IMoveColumnsMutationParams, IMoveRowsMutationParams } from '../../commands/mutations/move-rows-cols.mutation';
+import type { IReorderRangeMutationParams } from '../../commands/mutations/reorder-range.mutation';
+import type { ISetColDataMutationParams } from '../../commands/mutations/set-col-data.mutation';
+import type { ISetColHiddenMutationParams, ISetColVisibleMutationParams } from '../../commands/mutations/set-col-visible.mutation';
+import type { ISetGridlinesColorMutationParams } from '../../commands/mutations/set-gridlines-color.mutation';
+import type { ISetRangeValuesMutationParams } from '../../commands/mutations/set-range-values.mutation';
+import type { ISetRowDataMutationParams } from '../../commands/mutations/set-row-data.mutation';
+import type { ISetRowHiddenMutationParams, ISetRowVisibleMutationParams } from '../../commands/mutations/set-row-visible.mutation';
+import type { ISetWorksheetColWidthMutationParams } from '../../commands/mutations/set-worksheet-col-width.mutation';
+import type { ISetWorksheetDefaultStyleMutationParams } from '../../commands/mutations/set-worksheet-default-style.mutation';
+import type {
+ ISetWorksheetRowAutoHeightMutationParams,
+ ISetWorksheetRowHeightMutationParams,
+ ISetWorksheetRowIsAutoHeightMutationParams } from '../../commands/mutations/set-worksheet-row-height.mutation';
+import type { IToggleGridlinesMutationParams } from '../../commands/mutations/toggle-gridlines.mutation';
+import type { ISetWorksheetActiveOperationParams } from '../../commands/operations/set-worksheet-active.operation';
+import type { IAddWorksheetMergeMutationParams, IInsertColMutationParams, IInsertRowMutationParams, IRemoveColMutationParams, IRemoveRowsMutationParams, IRemoveWorksheetMergeMutationParams, IWorksheetRangeThemeStyleMutationParams } from '../interfaces';
+import { type ICommandInfo, type IRange, ObjectMatrix } from '@univerjs/core';
import { AddWorksheetMergeMutation } from '../../commands/mutations/add-worksheet-merge.mutation';
import { SetWorksheetRangeThemeStyleMutation } from '../../commands/mutations/add-worksheet-range-theme.mutation';
import { DeleteWorksheetRangeThemeStyleMutation } from '../../commands/mutations/delete-worksheet-range-theme.mutation';
@@ -24,6 +43,7 @@ import { RemoveColMutation, RemoveRowMutation } from '../../commands/mutations/r
import { RemoveWorksheetMergeMutation } from '../../commands/mutations/remove-worksheet-merge.mutation';
import { ReorderRangeMutation } from '../../commands/mutations/reorder-range.mutation';
import { SetColDataMutation } from '../../commands/mutations/set-col-data.mutation';
+
import { SetColHiddenMutation, SetColVisibleMutation } from '../../commands/mutations/set-col-visible.mutation';
import { SetGridlinesColorMutation } from '../../commands/mutations/set-gridlines-color.mutation';
import { SetRangeValuesMutation } from '../../commands/mutations/set-range-values.mutation';
@@ -62,6 +82,76 @@ export const COMMAND_LISTENER_SKELETON_CHANGE = [
SetGridlinesColorMutation.id,
];
+export type CommandListenerSkeletonChange =
+ | {
+ id: 'sheet.mutation.set-worksheet-row-height';
+ params: ISetWorksheetRowHeightMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-worksheet-row-is-auto-height';
+ params: ISetWorksheetRowIsAutoHeightMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-worksheet-row-auto-height';
+ params: ISetWorksheetRowAutoHeightMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-worksheet-col-width';
+ params: ISetWorksheetColWidthMutationParams;
+ }
+ | {
+ id: 'sheet.operation.set-worksheet-active';
+ params: ISetWorksheetActiveOperationParams;
+ }
+ | {
+ id: 'sheet.mutation.move-rows';
+ params: IMoveRowsMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.move-cols';
+ params: IMoveColumnsMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-col-hidden';
+ params: ISetColHiddenMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-col-visible';
+ params: ISetColVisibleMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-row-hidden';
+ params: ISetRowHiddenMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-row-visible';
+ params: ISetRowVisibleMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.insert-col';
+ params: IInsertColMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.insert-row';
+ params: IInsertRowMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.remove-col';
+ params: IRemoveColMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.remove-row';
+ params: IRemoveRowsMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.toggle-gridlines';
+ params: IToggleGridlinesMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-gridlines-color';
+ params: ISetGridlinesColorMutationParams;
+ };
+
export const COMMAND_LISTENER_VALUE_CHANGE = [
SetRangeValuesMutation.id,
MoveRangeMutation.id,
@@ -74,3 +164,163 @@ export const COMMAND_LISTENER_VALUE_CHANGE = [
SetWorksheetRangeThemeStyleMutation.id,
DeleteWorksheetRangeThemeStyleMutation.id,
];
+
+export type CommandListenerValueChange =
+ | {
+ id: 'sheet.mutation.set-range-values';
+ params: ISetRangeValuesMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.move-range';
+ params: IMoveRangeMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.remove-worksheet-merge';
+ params: IRemoveWorksheetMergeMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.add-worksheet-merge';
+ params: IAddWorksheetMergeMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.reorder-range';
+ params: IReorderRangeMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-worksheet-default-style';
+ params: ISetWorksheetDefaultStyleMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-row-data';
+ params: ISetRowDataMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-col-data';
+ params: ISetColDataMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.set-worksheet-range-theme-style';
+ params: IWorksheetRangeThemeStyleMutationParams;
+ }
+ | {
+ id: 'sheet.mutation.delete-worksheet-range-theme-style';
+ params: IWorksheetRangeThemeStyleMutationParams;
+ };
+
+// eslint-disable-next-line max-lines-per-function
+export function getValueChangedEffectedRange(commandInfo: ICommandInfo): { unitId: string;subUnitId: string; range: IRange }[] {
+ switch (commandInfo.id) {
+ case SetRangeValuesMutation.id: {
+ const params = commandInfo.params as ISetRangeValuesMutationParams;
+ return params.cellValue
+ ? [{
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range: new ObjectMatrix(params.cellValue).getDataRange(),
+ }]
+ : [];
+ }
+
+ case MoveRangeMutation.id: {
+ const params = commandInfo.params as IMoveRangeMutationParams;
+ return [{
+ unitId: params.unitId,
+ subUnitId: params.from.subUnitId,
+ range: new ObjectMatrix(params.from.value).getRange(),
+ }, {
+ unitId: params.unitId,
+ subUnitId: params.to.subUnitId,
+ range: new ObjectMatrix(params.to.value).getRange(),
+ }];
+ }
+
+ case RemoveWorksheetMergeMutation.id: {
+ const params = commandInfo.params as IRemoveWorksheetMergeMutationParams;
+ return params.ranges.map((range) => ({
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range,
+ }));
+ }
+
+ case AddWorksheetMergeMutation.id: {
+ const params = commandInfo.params as IAddWorksheetMergeMutationParams;
+ return params.ranges.map((range) => ({
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range,
+ }));
+ }
+
+ case ReorderRangeMutation.id: {
+ const params = commandInfo.params as IReorderRangeMutationParams;
+ return [{
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range: params.range,
+ }];
+ }
+
+ case SetWorksheetDefaultStyleMutation.id: {
+ const params = commandInfo.params as ISetWorksheetDefaultStyleMutationParams;
+ return [{
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range: { startRow: 0, endRow: Number.MAX_SAFE_INTEGER, startColumn: 0, endColumn: Number.MAX_SAFE_INTEGER },
+ }];
+ }
+
+ case SetRowDataMutation.id: {
+ const params = commandInfo.params as ISetRowDataMutationParams;
+ const rowIndices = Object.keys(params.rowData).map(Number);
+ if (rowIndices.length === 0) return [];
+ return [{
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range: {
+ startRow: Math.min(...rowIndices),
+ endRow: Math.max(...rowIndices),
+ startColumn: 0,
+ endColumn: Number.MAX_SAFE_INTEGER,
+ },
+ }];
+ }
+
+ case SetColDataMutation.id: {
+ const params = commandInfo.params as ISetColDataMutationParams;
+ const colIndices = Object.keys(params.columnData).map(Number);
+ if (colIndices.length === 0) return [];
+ return [{
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range: {
+ startRow: 0,
+ endRow: Number.MAX_SAFE_INTEGER,
+ startColumn: Math.min(...colIndices),
+ endColumn: Math.max(...colIndices),
+ },
+ }];
+ }
+
+ case SetWorksheetRangeThemeStyleMutation.id: {
+ const params = commandInfo.params as IWorksheetRangeThemeStyleMutationParams;
+ return [{
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range: params.range,
+ }];
+ }
+
+ case DeleteWorksheetRangeThemeStyleMutation.id: {
+ const params = commandInfo.params as IWorksheetRangeThemeStyleMutationParams;
+ return [{
+ unitId: params.unitId,
+ subUnitId: params.subUnitId,
+ range: params.range,
+ }];
+ }
+
+ default:
+ return [];
+ }
+}
diff --git a/packages/sheets/src/commands/commands/remove-sheet.command.ts b/packages/sheets/src/commands/commands/remove-sheet.command.ts
index 147e2f98af..68aa5b2462 100644
--- a/packages/sheets/src/commands/commands/remove-sheet.command.ts
+++ b/packages/sheets/src/commands/commands/remove-sheet.command.ts
@@ -34,7 +34,7 @@ import { getSheetCommandTarget } from './utils/target-util';
export interface IRemoveSheetCommandParams {
unitId?: string;
- subUnitId?: string;
+ subUnitId: string;
}
/**
diff --git a/packages/sheets/src/facade/f-event.ts b/packages/sheets/src/facade/f-event.ts
index 8c7541eb1f..3539d53ed1 100644
--- a/packages/sheets/src/facade/f-event.ts
+++ b/packages/sheets/src/facade/f-event.ts
@@ -19,6 +19,10 @@ import type { FWorkbook } from './f-workbook';
import type { FWorksheet } from './f-worksheet';
import { FEventName } from '@univerjs/core';
+/**
+ * Interface for sheet-related events
+ * Provides event names for sheet creation, workbook creation, and gridline changes
+ */
export interface IFSheetEventMixin {
/**
* Event fired after a sheet is created
@@ -27,7 +31,7 @@ export interface IFSheetEventMixin {
* ```ts
univerAPI.addEvent(univerAPI.Event.SheetCreated, (params) => {
const { workbook, worksheet } = params;
- console.log('unit created', params);
+ console.log('sheet created', params);
});
* ```
*/
@@ -39,11 +43,155 @@ export interface IFSheetEventMixin {
* ```ts
* univerAPI.addEvent(univerAPI.Event.BeforeSheetCreate, (params) => {
* const { workbook, index, sheet } = params;
- * console.log('unit created', params);
+ * console.log('before sheet create', params);
* });
* ```
*/
get BeforeSheetCreate(): 'BeforeSheetCreate';
+ /**
+ * Event fired before the active sheet changes
+ * @see {@link IActiveSheetChangedEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.ActiveSheetChanged, (params) => {
+ * const { workbook, activeSheet, oldActiveSheet } = params;
+ * console.log('before active sheet changed', params);
+ * });
+ * ```
+ */
+ get BeforeActiveSheetChange(): 'BeforeActiveSheetChange';
+ /**
+ * Event fired after the active sheet changes
+ * @see {@link IActiveSheetChangedEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.ActiveSheetChanged, (params) => {
+ * const { workbook, activeSheet } = params;
+ * console.log('after active sheet changed', params);
+ * });
+ * ```
+ */
+ get ActiveSheetChanged(): 'ActiveSheetChanged';
+ /**
+ * Event fired before a sheet is deleted
+ * @see {@link IBeforeSheetDeleteEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeSheetDelete, (params) => {
+ * const { workbook, worksheetId } = params;
+ * console.log('before sheet delete', params);
+ * });
+ * ```
+ */
+ get SheetDeleted(): 'SheetDeleted';
+ /**
+ * Event fired before a sheet is deleted
+ * @see {@link IBeforeSheetDeleteEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeSheetDelete, (params) => {
+ * const { workbook, worksheet } = params;
+ * console.log('before sheet delete', params);
+ * });
+ * ```
+ */
+ get BeforeSheetDelete(): 'BeforeSheetDelete';
+ /**
+ * Event fired after a sheet is moved
+ * @see {@link ISheetMovedEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.SheetMoved, (params) => {
+ * const { workbook, worksheet, newIndex } = params;
+ * console.log('sheet moved', params);
+ * });
+ * ```
+ */
+ get SheetMoved(): 'SheetMoved';
+ /**
+ * Event fired before a sheet is moved
+ * @see {@link IBeforeSheetMoveEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeSheetMove, (params) => {
+ * const { workbook, worksheet, newIndex, oldIndex } = params;
+ * console.log('before sheet move', params);
+ * });
+ * ```
+ */
+ get BeforeSheetMove(): 'BeforeSheetMove';
+ /**
+ * Event fired after a sheet name is changed
+ * @see {@link ISheetNameChangedEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.SheetNameChanged, (params) => {
+ * const { workbook, worksheet, newName } = params;
+ * console.log('sheet name changed', params);
+ * });
+ * ```
+ */
+ get SheetNameChanged(): 'SheetNameChanged';
+ /**
+ * Event fired before a sheet name is changed
+ * @see {@link IBeforeSheetNameChange}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeSheetNameChange, (params) => {
+ * const { workbook, worksheet, newName, oldName } = params;
+ * console.log('before sheet name changed', params);
+ * });
+ * ```
+ */
+ get BeforeSheetNameChange(): 'BeforeSheetNameChange';
+ /**
+ * Event fired after a sheet tab color is changed
+ * @see {@link ISheetTabColorChangedEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.SheetTabColorChanged, (params) => {
+ * const { workbook, worksheet, color } = params;
+ * console.log('sheet tab color changed', params);
+ * });
+ * ```
+ */
+ get SheetTabColorChanged(): 'SheetTabColorChanged';
+ /**
+ * Event fired before a sheet tab color is changed
+ * @see {@link IBeforeSheetTabColorChange}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeSheetTabColorChange, (params) => {
+ * const { workbook, worksheet, color, oldColor } = params;
+ * console.log('before sheet tab color changed', params);
+ * });
+ * ```
+ */
+ get BeforeSheetTabColorChange(): 'BeforeSheetTabColorChange';
+ /**
+ * Event fired after a sheet is hidden
+ * @see {@link ISheetHideChangedEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.SheetHideChanged, (params) => {
+ * const { workbook, worksheet } = params;
+ * console.log('sheet hide changed', params);
+ * });
+ * ```
+ */
+ get SheetHideChanged(): 'SheetHideChanged';
+ /**
+ * Event fired before a sheet is hidden
+ * @see {@link IBeforeSheetHideChange}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeSheetHideChange, (params) => {
+ * const { workbook, worksheet, hide } = params;
+ * console.log('before sheet hide changed', params);
+ * });
+ * ```
+ */
+ get BeforeSheetHideChange(): 'BeforeSheetHideChange';
/**
* Event fired after a workbook is created
* @see {@link IWorkbookCreateParam}
@@ -51,7 +199,7 @@ export interface IFSheetEventMixin {
* ```ts
* univerAPI.addEvent(univerAPI.Event.WorkbookCreated, (params) => {
* const { unitId, type, workbook, unit } = params;
- * console.log('unit created', params);
+ * console.log('workbook created', params);
* });
* ```
*/
@@ -68,43 +216,119 @@ export interface IFSheetEventMixin {
* ```
*/
get WorkbookDisposed(): 'WorkbookDisposed';
+
+ /**
+ * Event fired when gridline changed
+ * @see {@link IGridlineChangedEvent}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.GridlineChanged, (params) => {
+ * const { workbook, worksheet, enabled, color } = params;
+ * console.log('gridline changed', params);
+ * });
+ * ```
+ */
+ get GridlineChanged(): 'GridlineChanged';
+
+ /**
+ * Event fired before gridline enable changed
+ * @see {@link IBeforeGridlineEnableChange}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeGridlineEnableChange, (params) => {
+ * const { workbook, worksheet, enabled } = params;
+ * console.log('gridline changed', params);
+ * });
+ * ```
+ */
+ get BeforeGridlineEnableChange(): 'BeforeGridlineEnableChange';
+
+ /**
+ * Event fired before gridline color changed
+ * @see {@link IBeforeGridlineColorChanged}
+ * @example
+ * ```ts
+ * univerAPI.addEvent(univerAPI.Event.BeforeGridlineColorChange, (params) => {
+ * const { workbook, worksheet, color } = params;
+ * console.log('gridline changed', params);
+ * });
+ * ```
+ */
+ get BeforeGridlineColorChange(): 'BeforeGridlineColorChange';
}
+/**
+ * Interface for workbook creation parameters
+ * Extends the base event interface and includes workbook initialization details
+ */
export interface IWorkbookCreateParam extends IEventBase {
+ /** Unique identifier for the workbook unit */
unitId: string;
+ /** Type identifier specifying this is a sheet instance */
type: UniverInstanceType.UNIVER_SHEET;
+ /** The workbook instance being created */
workbook: FWorkbook;
+ /** The workbook unit reference */
unit: FWorkbook;
}
+/**
+ * Interface for workbook disposal event
+ * Contains information about the disposed workbook including its snapshot data
+ */
export interface IWorkbookDisposedEvent extends IEventBase {
+ /** Unique identifier of the disposed workbook unit */
unitId: string;
+ /** Type identifier specifying this was a sheet instance */
unitType: UniverInstanceType.UNIVER_SHEET;
+ /** Snapshot data of the workbook at the time of disposal */
snapshot: IWorkbookData;
}
-export class FSheetEventName extends FEventName implements IFSheetEventMixin {
- override get SheetCreated(): 'SheetCreated' {
- return 'SheetCreated' as const;
- }
-
- override get BeforeSheetCreate(): 'BeforeSheetCreate' {
- return 'BeforeSheetCreate' as const;
- }
+/**
+ * Interface for gridline change event
+ * Triggered when gridline visibility or color changes in a worksheet
+ */
+export interface IGridlineChangedEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet where gridline changes occurred */
+ worksheet: FWorksheet;
+ /** Flag indicating whether gridlines are enabled or disabled */
+ enabled: boolean;
+ /** The color of the gridlines, undefined if using default color */
+ color: string | undefined;
+}
- override get WorkbookCreated(): 'WorkbookCreated' {
- return 'WorkbookCreated' as const;
- }
+/**
+ * Interface for event before gridline enable/disable
+ * Triggered before changing the gridline visibility state
+ */
+export interface IBeforeGridlineEnableChange extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet where gridline state will change */
+ worksheet: FWorksheet;
+ /** The new enabled state to be applied */
+ enabled: boolean;
+}
- override get WorkbookDisposed(): 'WorkbookDisposed' {
- return 'WorkbookDisposed' as const;
- }
+/**
+ * Interface for event before gridline color change
+ * Triggered before changing the gridline color
+ */
+export interface IBeforeGridlineColorChanged extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet where gridline color will change */
+ worksheet: FWorksheet;
+ /** The new color to be applied, undefined to use default color */
+ color: string | undefined;
}
/**
- * Event interface triggered before creating a new worksheet
- * @interface IBeforeSheetCreateEventParams
- * @augments {IEventBase}
+ * Interface for event parameters triggered before creating a new worksheet
+ * Extends the base event interface and includes workbook and worksheet details
*/
export interface IBeforeSheetCreateEventParams extends IEventBase {
/** The workbook instance */
@@ -116,9 +340,8 @@ export interface IBeforeSheetCreateEventParams extends IEventBase {
}
/**
- * Event interface triggered after a worksheet is created
- * @interface ISheetCreatedEventParams
- * @augments {IEventBase}
+ * Interface for event parameters triggered after a worksheet is created
+ * Extends the base event interface and includes workbook and worksheet details
*/
export interface ISheetCreatedEventParams extends IEventBase {
/** The workbook instance */
@@ -127,9 +350,165 @@ export interface ISheetCreatedEventParams extends IEventBase {
worksheet: FWorksheet;
}
+/**
+ * Interface for sheet active change event
+ * Contains information about the sheet that will become active
+ */
+export interface IBeforeActiveSheetChangeEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet that will become active */
+ activeSheet: FWorksheet;
+ /** The currently active worksheet */
+ oldActiveSheet: FWorksheet;
+}
+
+/**
+ * Interface for sheet active changed event
+ * Contains information about the newly activated sheet
+ */
+export interface IActiveSheetChangedEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet that has become active */
+ activeSheet: FWorksheet;
+}
+
+/**
+ * Interface for sheet deletion event
+ * Contains information about the sheet that was deleted
+ */
+export interface ISheetDeletedEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet that was deleted */
+ sheetId: string;
+}
+
+/**
+ * Interface for before sheet deletion event
+ * Contains information about the sheet that will be deleted
+ */
+export interface IBeforeSheetDeleteEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet that will be deleted */
+ worksheet: FWorksheet;
+}
+
+/**
+ * Interface for sheet moved event
+ * Contains information about the sheet movement
+ */
+export interface ISheetMovedEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet that was moved */
+ worksheet: FWorksheet;
+ /** The new position index of the sheet */
+ newIndex: number;
+}
+
+/**
+ * Interface for before sheet move event
+ * Contains information about the planned sheet movement
+ */
+export interface IBeforeSheetMoveEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet that will be moved */
+ worksheet: FWorksheet;
+ /** The target position index for the sheet */
+ newIndex: number;
+ /** The current position index of the sheet */
+ oldIndex: number;
+}
+
+/**
+ * Interface for sheet name change event
+ * Contains information about the sheet name change
+ */
+export interface ISheetNameChangedEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet whose name was changed */
+ worksheet: FWorksheet;
+ /** The new name of the sheet */
+ newName: string;
+}
+
+/**
+ * Interface for before sheet name change event
+ * Contains information about the planned sheet name change
+ */
+export interface IBeforeSheetNameChangeEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet whose name will be changed */
+ worksheet: FWorksheet;
+ /** The new name to be applied */
+ newName: string;
+ /** The current name of the sheet */
+ oldName: string;
+}
+
+/**
+ * Interface for sheet tab color change event
+ * Contains information about the sheet tab color change
+ */
+export interface ISheetTabColorChangedEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet whose tab color was changed */
+ worksheet: FWorksheet;
+ /** The new color of the sheet tab */
+ newColor: string | undefined;
+}
+
+/**
+ * Interface for before sheet tab color change event
+ * Contains information about the planned sheet tab color change
+ */
+export interface IBeforeSheetTabColorChangeEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet whose tab color will be changed */
+ worksheet: FWorksheet;
+ /** The new color to be applied */
+ newColor: string | undefined;
+ /** The current color of the sheet tab */
+ oldColor: string | undefined;
+}
+
+/**
+ * Interface for sheet hide state change event
+ * Contains information about the sheet visibility change
+ */
+export interface ISheetHideChangedEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet whose visibility was changed */
+ worksheet: FWorksheet;
+ /** The new visibility state */
+ hidden: boolean;
+}
+
+/**
+ * Interface for before sheet hide state change event
+ * Contains information about the planned sheet visibility change
+ */
+export interface IBeforeSheetHideChangeEvent extends IEventBase {
+ /** The workbook instance containing the worksheet */
+ workbook: FWorkbook;
+ /** The worksheet whose visibility will be changed */
+ worksheet: FWorksheet;
+ /** The new visibility state to be applied */
+ hidden: boolean;
+}
+
/**
* Configuration interface for sheet-related events
- * @interface ISheetEventParamConfig
+ * Provides event names and their corresponding event parameter interfaces
*/
export interface ISheetEventParamConfig {
/** Event fired after a worksheet is created */
@@ -140,6 +519,114 @@ export interface ISheetEventParamConfig {
WorkbookCreated: IWorkbookCreateParam;
/** Event fired when a workbook is disposed */
WorkbookDisposed: IWorkbookDisposedEvent;
+ /** Event fired when gridline changed */
+ GridlineChanged: IGridlineChangedEvent;
+ /** Event fired before gridline enable changed */
+ BeforeGridlineEnableChange: IBeforeGridlineEnableChange;
+ /** Event fired before gridline color changed */
+ BeforeGridlineColorChange: IBeforeGridlineColorChanged;
+ /** Event fired before active sheet changes */
+ BeforeActiveSheetChange: IBeforeActiveSheetChangeEvent;
+ /** Event fired after active sheet changed */
+ ActiveSheetChanged: IActiveSheetChangedEvent;
+ /** Event fired after a sheet is deleted */
+ SheetDeleted: ISheetDeletedEvent;
+ /** Event fired before a sheet is deleted */
+ BeforeSheetDelete: IBeforeSheetDeleteEvent;
+ /** Event fired after a sheet is moved */
+ SheetMoved: ISheetMovedEvent;
+ /** Event fired before a sheet is moved */
+ BeforeSheetMove: IBeforeSheetMoveEvent;
+ /** Event fired after a sheet name is changed */
+ SheetNameChanged: ISheetNameChangedEvent;
+ /** Event fired before a sheet name is changed */
+ BeforeSheetNameChange: IBeforeSheetNameChangeEvent;
+ /** Event fired after a sheet tab color is changed */
+ SheetTabColorChanged: ISheetTabColorChangedEvent;
+ /** Event fired before a sheet tab color is changed */
+ BeforeSheetTabColorChange: IBeforeSheetTabColorChangeEvent;
+ /** Event fired after a sheet visibility is changed */
+ SheetHideChanged: ISheetHideChangedEvent;
+ /** Event fired before a sheet visibility is changed */
+ BeforeSheetHideChange: IBeforeSheetHideChangeEvent;
+}
+
+export class FSheetEventName extends FEventName implements IFSheetEventMixin {
+ override get SheetCreated(): 'SheetCreated' {
+ return 'SheetCreated' as const;
+ }
+
+ override get BeforeSheetCreate(): 'BeforeSheetCreate' {
+ return 'BeforeSheetCreate' as const;
+ }
+
+ override get WorkbookCreated(): 'WorkbookCreated' {
+ return 'WorkbookCreated' as const;
+ }
+
+ override get WorkbookDisposed(): 'WorkbookDisposed' {
+ return 'WorkbookDisposed' as const;
+ }
+
+ override get GridlineChanged(): 'GridlineChanged' {
+ return 'GridlineChanged' as const;
+ }
+
+ override get BeforeGridlineEnableChange(): 'BeforeGridlineEnableChange' {
+ return 'BeforeGridlineEnableChange' as const;
+ }
+
+ override get BeforeGridlineColorChange(): 'BeforeGridlineColorChange' {
+ return 'BeforeGridlineColorChange' as const;
+ }
+
+ override get BeforeActiveSheetChange(): 'BeforeActiveSheetChange' {
+ return 'BeforeActiveSheetChange' as const;
+ }
+
+ override get ActiveSheetChanged(): 'ActiveSheetChanged' {
+ return 'ActiveSheetChanged' as const;
+ }
+
+ override get SheetDeleted(): 'SheetDeleted' {
+ return 'SheetDeleted' as const;
+ }
+
+ override get BeforeSheetDelete(): 'BeforeSheetDelete' {
+ return 'BeforeSheetDelete' as const;
+ }
+
+ override get SheetMoved(): 'SheetMoved' {
+ return 'SheetMoved' as const;
+ }
+
+ override get BeforeSheetMove(): 'BeforeSheetMove' {
+ return 'BeforeSheetMove' as const;
+ }
+
+ override get SheetNameChanged(): 'SheetNameChanged' {
+ return 'SheetNameChanged' as const;
+ }
+
+ override get BeforeSheetNameChange(): 'BeforeSheetNameChange' {
+ return 'BeforeSheetNameChange' as const;
+ }
+
+ override get SheetTabColorChanged(): 'SheetTabColorChanged' {
+ return 'SheetTabColorChanged' as const;
+ }
+
+ override get BeforeSheetTabColorChange(): 'BeforeSheetTabColorChange' {
+ return 'BeforeSheetTabColorChange' as const;
+ }
+
+ override get SheetHideChanged(): 'SheetHideChanged' {
+ return 'SheetHideChanged' as const;
+ }
+
+ override get BeforeSheetHideChange(): 'BeforeSheetHideChange' {
+ return 'BeforeSheetHideChange' as const;
+ }
}
FEventName.extend(FSheetEventName);
diff --git a/packages/sheets/src/facade/f-selection.ts b/packages/sheets/src/facade/f-selection.ts
index 9810b7e9b9..2dfc71ba74 100644
--- a/packages/sheets/src/facade/f-selection.ts
+++ b/packages/sheets/src/facade/f-selection.ts
@@ -47,6 +47,14 @@ export class FSelection {
/**
* Represents the active selection in the sheet. Which means the selection contains the active cell.
* @returns {FRange | null} The active selection.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fSelection = fWorksheet.getSelection();
+ * const activeRange = fSelection.getActiveRange();
+ * console.log(activeRange);
+ * ```
*/
getActiveRange(): FRange | null {
const active = this._selections.find((selection) => !!selection.primary);
@@ -60,6 +68,14 @@ export class FSelection {
/**
* Represents the active selection list in the sheet.
* @returns {FRange[]} The active selection list.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fSelection = fWorksheet.getSelection();
+ * const activeRangeList = fSelection.getActiveRangeList();
+ * console.log(activeRangeList);
+ * ```
*/
getActiveRangeList(): FRange[] {
return this._selections.map((selection) => {
@@ -70,6 +86,14 @@ export class FSelection {
/**
* Represents the current select cell in the sheet.
* @returns {ISelectionCell} The current select cell info.Pay attention to the type of the return value.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fSelection = fWorksheet.getSelection();
+ * const currentCell = fSelection.getCurrentCell();
+ * console.log(currentCell);
+ * ```
*/
getCurrentCell(): Nullable<ISelectionCell> {
const current = this._selections.find((selection) => !!selection.primary);
diff --git a/packages/sheets/src/facade/f-univer.ts b/packages/sheets/src/facade/f-univer.ts
index a724d1f1b2..033775e11c 100644
--- a/packages/sheets/src/facade/f-univer.ts
+++ b/packages/sheets/src/facade/f-univer.ts
@@ -15,11 +15,11 @@
*/
import type { ICommandInfo, IDisposable, Injector, IWorkbookData, Nullable, Workbook } from '@univerjs/core';
-import type { IInsertSheetCommandParams } from '@univerjs/sheets';
+import type { IInsertSheetCommandParams, IRemoveSheetCommandParams, ISetGridlinesColorCommandParams, ISetTabColorMutationParams, ISetWorksheetActivateCommandParams, ISetWorksheetHideMutationParams, ISetWorksheetNameCommandParams, ISetWorksheetOrderMutationParams, IToggleGridlinesCommandParams } from '@univerjs/sheets';
import type { IBeforeSheetCreateEventParams, ISheetCreatedEventParams } from './f-event';
import type { FWorksheet } from './f-worksheet';
import { CanceledError, FUniver, ICommandService, IUniverInstanceService, toDisposable, UniverInstanceType } from '@univerjs/core';
-import { InsertSheetCommand } from '@univerjs/sheets';
+import { InsertSheetCommand, RemoveSheetCommand, SetGridlinesColorCommand, SetTabColorCommand, SetWorksheetActivateCommand, SetWorksheetHideCommand, SetWorksheetNameCommand, SetWorksheetOrderCommand, ToggleGridlinesCommand } from '@univerjs/sheets';
import { FDefinedNameBuilder } from './f-defined-name';
import { FPermission } from './f-permission';
import { FWorkbook } from './f-workbook';
@@ -111,6 +111,18 @@ export interface IFUniverSheetsMixin {
* ```
*/
getCommandSheetTarget(commandInfo: ICommandInfo<object>): Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>;
+
+ /**
+ * Get the active sheet.
+ * @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} The active sheet.
+ * @example
+ * ```ts
+ * const target = univerAPI.getActiveSheet();
+ * if (!target) return;
+ * const { workbook, worksheet } = target;
+ * ```
+ */
+ getActiveSheet(): Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>;
}
export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
@@ -183,9 +195,11 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
);
}
+ // eslint-disable-next-line max-lines-per-function
override _initialize(injector: Injector): void {
const commandService = injector.get(ICommandService);
this.disposeWithMe(
+ // eslint-disable-next-line max-lines-per-function, complexity
commandService.beforeCommandExecuted((commandInfo) => {
switch (commandInfo.id) {
case InsertSheetCommand.id: {
@@ -210,7 +224,77 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
}
break;
}
-
+ case SetWorksheetActivateCommand.id: {
+ if (!this._eventListend(this.Event.BeforeActiveSheetChange)) return;
+ const { subUnitId: sheetId, unitId } = commandInfo.params as ISetWorksheetActivateCommandParams;
+ const workbook = unitId ? this.getUniverSheet(unitId) : this.getActiveWorkbook?.();
+ if (!workbook || !sheetId) return;
+ const activeSheet = workbook.getSheetBySheetId(sheetId);
+ const oldActiveSheet = workbook.getActiveSheet();
+ if (!activeSheet || !oldActiveSheet) return;
+ this._fireBeforeActiveSheetChange(workbook, activeSheet, oldActiveSheet);
+ break;
+ }
+ case RemoveSheetCommand.id: {
+ if (!this._eventListend(this.Event.BeforeSheetDelete)) return;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ const { workbook, worksheet } = target;
+ this._fireBeforeSheetDelete(workbook, worksheet);
+ break;
+ }
+ case SetWorksheetOrderCommand.id: {
+ if (!this._eventListend(this.Event.BeforeSheetMove)) return;
+ const { fromOrder, toOrder } = commandInfo.params as ISetWorksheetOrderMutationParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireBeforeSheetMove(target.workbook, target.worksheet, toOrder, fromOrder);
+ break;
+ }
+ case SetWorksheetNameCommand.id: {
+ if (!this._eventListend(this.Event.BeforeSheetNameChange)) return;
+ const { name } = commandInfo.params as ISetWorksheetNameCommandParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireBeforeSheetNameChange(target.workbook, target.worksheet, name, target.worksheet.getSheetName());
+ break;
+ }
+ case SetTabColorCommand.id: {
+ if (!this._eventListend(this.Event.BeforeSheetTabColorChange)) return;
+ const { color } = commandInfo.params as ISetTabColorMutationParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireBeforeSheetTabColorChange(target.workbook, target.worksheet, color, target.worksheet.getTabColor());
+ break;
+ }
+ case SetWorksheetHideCommand.id: {
+ if (!this._eventListend(this.Event.BeforeSheetHideChange)) return;
+ const { hidden } = commandInfo.params as ISetWorksheetHideMutationParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireBeforeSheetHideChange(target.workbook, target.worksheet, Boolean(hidden));
+ break;
+ }
+ case SetGridlinesColorCommand.id: {
+ if (!this._eventListend(this.Event.BeforeGridlineColorChange)) return;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this.fireEvent(this.Event.BeforeGridlineColorChange, {
+ ...target,
+ color: (commandInfo.params as ISetGridlinesColorCommandParams)?.color,
+ });
+ break;
+ }
+ case ToggleGridlinesCommand.id: {
+ if (!this._eventListend(this.Event.BeforeGridlineEnableChange)) return;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this.fireEvent(this.Event.BeforeGridlineEnableChange, {
+ ...target,
+ enabled: Boolean((commandInfo.params as IToggleGridlinesCommandParams)?.showGridlines) ?? !target.worksheet.hasHiddenGridLines(),
+ });
+ break;
+ }
default:
break;
}
@@ -218,6 +302,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
);
this.disposeWithMe(
+ // eslint-disable-next-line max-lines-per-function, complexity
commandService.onCommandExecuted((commandInfo) => {
switch (commandInfo.id) {
case InsertSheetCommand.id: {
@@ -241,7 +326,66 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
);
break;
}
-
+ case SetWorksheetActivateCommand.id: {
+ if (!this._eventListend(this.Event.ActiveSheetChanged)) return;
+ const target = this.getActiveSheet();
+ if (!target) return;
+ const { workbook, worksheet: activeSheet } = target;
+ this._fireActiveSheetChanged(workbook, activeSheet);
+ break;
+ }
+ case RemoveSheetCommand.id: {
+ if (!this._eventListend(this.Event.SheetDeleted)) return;
+ const { subUnitId: sheetId, unitId } = commandInfo.params as IRemoveSheetCommandParams;
+ const workbook = unitId ? this.getUniverSheet(unitId) : this.getActiveWorkbook?.();
+ if (!workbook || !sheetId) return;
+ this._fireSheetDeleted(workbook, sheetId);
+ break;
+ }
+ case SetWorksheetOrderCommand.id: {
+ if (!this._eventListend(this.Event.SheetMoved)) return;
+ const { toOrder: toIndex } = commandInfo.params as ISetWorksheetOrderMutationParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireSheetMoved(target.workbook, target.worksheet, toIndex);
+ break;
+ }
+ case SetWorksheetNameCommand.id: {
+ if (!this._eventListend(this.Event.SheetNameChanged)) return;
+ const { name } = commandInfo.params as ISetWorksheetNameCommandParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireSheetNameChanged(target.workbook, target.worksheet, name);
+ break;
+ }
+ case SetTabColorCommand.id: {
+ if (!this._eventListend(this.Event.SheetTabColorChanged)) return;
+ const { color } = commandInfo.params as ISetTabColorMutationParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireSheetTabColorChanged(target.workbook, target.worksheet, color);
+ break;
+ }
+ case SetWorksheetHideCommand.id: {
+ if (!this._eventListend(this.Event.SheetHideChanged)) return;
+ const { hidden } = commandInfo.params as ISetWorksheetHideMutationParams;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this._fireSheetHideChanged(target.workbook, target.worksheet, !!hidden);
+ break;
+ }
+ case SetGridlinesColorCommand.id:
+ case ToggleGridlinesCommand.id: {
+ if (!this._eventListend(this.Event.GridlineChanged)) return;
+ const target = this.getCommandSheetTarget(commandInfo);
+ if (!target) return;
+ this.fireEvent(this.Event.GridlineChanged, {
+ ...target,
+ enabled: !target.worksheet.hasHiddenGridLines(),
+ color: target.worksheet.getGridLinesColor(),
+ });
+ break;
+ }
default:
break;
}
@@ -303,6 +447,114 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
override newDefinedName(): FDefinedNameBuilder {
return this._injector.createInstance(FDefinedNameBuilder);
}
+
+ override getActiveSheet(): Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }> {
+ const workbook = this.getActiveWorkbook();
+ if (!workbook) {
+ return null;
+ }
+ const worksheet = workbook.getActiveSheet();
+ if (!worksheet) {
+ return null;
+ }
+ return { workbook, worksheet };
+ }
+
+ private _fireBeforeActiveSheetChange(workbook: FWorkbook, newActiveSheet: FWorksheet, oldActiveSheet: FWorksheet): void {
+ this.fireEvent(this.Event.BeforeActiveSheetChange, {
+ workbook,
+ activeSheet: newActiveSheet,
+ oldActiveSheet,
+ });
+ }
+
+ private _fireActiveSheetChanged(workbook: FWorkbook, newActiveSheet: FWorksheet): void {
+ this.fireEvent(this.Event.ActiveSheetChanged, {
+ workbook,
+ activeSheet: newActiveSheet,
+ });
+ }
+
+ private _fireBeforeSheetDelete(workbook: FWorkbook, worksheet: FWorksheet): void {
+ this.fireEvent(this.Event.BeforeSheetDelete, {
+ workbook,
+ worksheet,
+ });
+ }
+
+ private _fireSheetDeleted(workbook: FWorkbook, sheetId: string): void {
+ this.fireEvent(this.Event.SheetDeleted, {
+ workbook,
+ sheetId,
+ });
+ }
+
+ private _fireBeforeSheetMove(workbook: FWorkbook, worksheet: FWorksheet, toIndex: number, fromIndex: number): void {
+ this.fireEvent(this.Event.BeforeSheetMove, {
+ workbook,
+ worksheet,
+ newIndex: toIndex,
+ oldIndex: fromIndex,
+ });
+ }
+
+ private _fireSheetMoved(workbook: FWorkbook, worksheet: FWorksheet, toIndex: number): void {
+ this.fireEvent(this.Event.SheetMoved, {
+ workbook,
+ worksheet,
+ newIndex: toIndex,
+ });
+ }
+
+ private _fireBeforeSheetNameChange(workbook: FWorkbook, worksheet: FWorksheet, newName: string, oldName: string): void {
+ this.fireEvent(this.Event.BeforeSheetNameChange, {
+ workbook,
+ worksheet,
+ newName,
+ oldName,
+ });
+ }
+
+ private _fireSheetNameChanged(workbook: FWorkbook, worksheet: FWorksheet, newName: string): void {
+ this.fireEvent(this.Event.SheetNameChanged, {
+ workbook,
+ worksheet,
+ newName,
+ });
+ }
+
+ private _fireBeforeSheetTabColorChange(workbook: FWorkbook, worksheet: FWorksheet, newColor: string, oldColor: string | undefined): void {
+ this.fireEvent(this.Event.BeforeSheetTabColorChange, {
+ workbook,
+ worksheet,
+ newColor,
+ oldColor,
+ });
+ }
+
+ private _fireSheetTabColorChanged(workbook: FWorkbook, worksheet: FWorksheet, newColor: string): void {
+ this.fireEvent(this.Event.SheetTabColorChanged, {
+ workbook,
+ worksheet,
+ newColor,
+ });
+ }
+
+ private _fireBeforeSheetHideChange(workbook: FWorkbook, worksheet: FWorksheet, hidden: boolean): void {
+ this.fireEvent(this.Event.BeforeSheetHideChange, {
+ workbook,
+ worksheet,
+ hidden,
+ });
+ }
+
+ private _fireSheetHideChanged(workbook: FWorkbook, worksheet: FWorksheet, hidden: boolean): void {
+ this.fireEvent(this.Event.SheetHideChanged, {
+ workbook,
+ worksheet,
+ hidden,
+ });
+ }
}
FUniver.extend(FUniverSheetsMixin);
diff --git a/packages/sheets/src/facade/f-workbook.ts b/packages/sheets/src/facade/f-workbook.ts
index 9d1d3bf3cf..4db338666c 100644
--- a/packages/sheets/src/facade/f-workbook.ts
+++ b/packages/sheets/src/facade/f-workbook.ts
@@ -46,6 +46,16 @@ export class FWorkbook extends FBaseInitialable {
this.id = this._workbook.getUnitId();
}
+ /**
+ * Get the Workbook instance.
+ * @returns {Workbook} The Workbook instance.
+ * @example
+ * ```ts
+ * // The code below gets the Workbook instance
+ * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+ * const workbook = activeSpreadsheet.getWorkbook();
+ * ```
+ */
getWorkbook(): Workbook {
return this._workbook;
}
@@ -131,6 +141,12 @@ export class FWorkbook extends FBaseInitialable {
* @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 {
this._logService.warn('use \'save\' instead of \'getSnapshot\'');
diff --git a/packages/sheets/src/facade/f-worksheet.ts b/packages/sheets/src/facade/f-worksheet.ts
index 6775f42651..26d90d37b7 100644
--- a/packages/sheets/src/facade/f-worksheet.ts
+++ b/packages/sheets/src/facade/f-worksheet.ts
@@ -47,6 +47,14 @@ export class FWorksheet extends FBaseInitialable {
super(_injector);
}
+ /**
+ * Returns the worksheet
+ * @returns {Worksheet} The worksheet instance.
+ * @example
+ * ```typescript
+ * const sheet = univerAPI.getActiveWorkbook().getActiveSheet().getSheet();
+ * ```
+ */
getSheet(): Worksheet {
return this._worksheet;
}
@@ -54,6 +62,10 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns the injector
* @returns The injector
+ * @example
+ * ```typescript
+ * const injector = univerAPI.getActiveWorkbook().getActiveSheet().getInject();
+ * ```
*/
getInject(): Injector {
return this._injector;
@@ -62,6 +74,10 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns the workbook
* @returns {Workbook} The workbook instance.
+ * @example
+ * ```typescript
+ * const workbook = univerAPI.getActiveWorkbook().getWorkbook();
+ * ```
*/
getWorkbook(): Workbook {
return this._workbook;
@@ -70,6 +86,11 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns the worksheet id.
* @returns {string} The id of the worksheet.
+ * @example
+ * ```typescript
+ * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const id = sheet.getSheetId();
+ * ```
*/
getSheetId(): string {
return this._worksheet.getSheetId();
@@ -78,6 +99,11 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns the worksheet name.
* @returns {string} The name of the worksheet.
+ * @example
+ * ```typescript
+ * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const name = sheet.getSheetName();
+ * ```
*/
getSheetName(): string {
return this._worksheet.getName();
@@ -86,6 +112,11 @@ export class FWorksheet extends FBaseInitialable {
/**
* Represents the selection ranges info of the worksheet.
* @returns {FSelection} return the current selections of the worksheet or null if there is no selection.
+ * @example
+ * ```typescript
+ * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const selections = sheet.getSelection();
+ * ```
*/
getSelection(): FSelection | null {
const selections = this._selectionManagerService.getCurrentSelections();
@@ -103,6 +134,11 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the default style of the worksheet
* @returns {IStyleData} Default style of the worksheet.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * const defaultStyle = sheet.getDefaultStyle();
+ * ```
*/
getDefaultStyle(): Nullable<IStyleData> | string {
return this._worksheet.getDefaultCellStyle();
@@ -113,6 +149,14 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} index The row index
* @param {boolean} [keepRaw] If true, return the raw style data maybe the style name or style data, otherwise return the data from row manager
* @returns {Nullable<IStyleData> | string} The default style of the worksheet row name or style data
+ * @example
+ * ```typescript
+ * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Get default style for row 0 (1)
+ * const rowStyle = sheet.getRowDefaultStyle(0);
+ * // Get raw style data for row 0
+ * const rawRowStyle = sheet.getRowDefaultStyle(0, true);
+ * ```
*/
getRowDefaultStyle(index: number, keepRaw: boolean = false): Nullable<IStyleData> | string {
return this._worksheet.getRowStyle(index, keepRaw);
@@ -123,6 +167,14 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} index The column index
* @param {boolean} [keepRaw] If true, return the raw style data maybe the style name or style data, otherwise return the data from col manager
* @returns {Nullable<IStyleData> | string} The default style of the worksheet column name or style data
+ * @example
+ * ```typescript
+ * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Get default style for column 0 (A)
+ * const colStyle = sheet.getColumnDefaultStyle(0);
+ * // Get raw style data for column 0
+ * const rawColStyle = sheet.getColumnDefaultStyle(0, true);
+ * ```
*/
getColumnDefaultStyle(index: number, keepRaw: boolean = false): Nullable<IStyleData> | string {
return this._worksheet.getColumnStyle(index, keepRaw);
@@ -132,6 +184,12 @@ export class FWorksheet extends FBaseInitialable {
* Set the default style of the worksheet
* @param {StyleDataInfo} style default style
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * fWorksheet.setDefaultStyle('default');
+ * ```
*/
setDefaultStyle(style: string): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -150,6 +208,12 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} index The row index
* @param {string | Nullable<IStyleData>} style The style name or style data
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * fWorksheet.setRowDefaultStyle(0, 'default');
+ * ```
*/
setColumnDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -174,6 +238,12 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} index The column index
* @param {string | Nullable<IStyleData>} style The style name or style data
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * fWorksheet.setColumnDefaultStyle(0, 'default');
+ * ```
*/
setRowDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -200,6 +270,12 @@ export class FWorksheet extends FBaseInitialable {
* @param row The row index of the cell.
* @param column The column index of the cell.
* @returns A Range object representing the specified cell.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Get range for cell at row 0, column 0 (A1)
+ * const range = sheet.getRange(0, 0);
+ * ```
*/
getRange(row: number, column: number): FRange;
/**
@@ -223,13 +299,27 @@ export class FWorksheet extends FBaseInitialable {
* Returns a Range object specified by A1 notation.
* @param a1Notation A string representing a range in A1 notation.
* @returns A Range object representing the specified range.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Get range for cells A1:C3
+ * const range = sheet.getRange("A1:C3");
+ * // Get range for a single cell
+ * const cell = sheet.getRange("B2");
+ * // Get range with sheet name
+ * const rangeWithSheet = sheet.getRange("Sheet1!A1:C3");
+ * ```
*/
getRange(a1Notation: string): FRange;
- getRange(rowOrA1Notation: number | string, column?: number, numRows?: number, numColumns?: number): FRange {
+ getRange(range: IRange): FRange;
+ getRange(rowOrA1Notation: IRange | number | string, column?: number, numRows?: number, numColumns?: number): FRange {
let range: IRange;
let sheet: Worksheet;
- if (typeof rowOrA1Notation === 'string') {
+ if (typeof rowOrA1Notation === 'object') {
+ range = rowOrA1Notation;
+ sheet = this._worksheet;
+ } else if (typeof rowOrA1Notation === 'string') {
// A1 notation
const { range: parsedRange, sheetName } = deserializeRangeWithSheet(rowOrA1Notation);
@@ -272,6 +362,12 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns the current number of columns in the sheet, regardless of content.
* @returns {number} The maximum columns count of the sheet
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * const totalColumns = sheet.getMaxColumns();
+ * console.log(`Sheet has ${totalColumns} columns`);
+ * ```
*/
getMaxColumns(): number {
return this._worksheet.getMaxColumns();
@@ -280,6 +376,12 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns the current number of rows in the sheet, regardless of content.
* @returns {number}The maximum rows count of the sheet
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * const totalRows = sheet.getMaxRows();
+ * console.log(`Sheet has ${totalRows} rows`);
+ * ```
*/
getMaxRows(): number {
return this._worksheet.getMaxRows();
@@ -289,6 +391,14 @@ export class FWorksheet extends FBaseInitialable {
* Inserts a row after the given row position.
* @param {number} afterPosition The row after which the new row should be added, starting at 0 for the first row.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 rows at row index 2 (before the third row)
+ * sheet.insertRowAfter(2);
+ * // Insert 1 row at row index 0 (before the first row)
+ * sheet.insertRowAfter(0);
+ * ```
*/
insertRowAfter(afterPosition: number): FWorksheet {
return this.insertRowsAfter(afterPosition, 1);
@@ -298,6 +408,14 @@ export class FWorksheet extends FBaseInitialable {
* Inserts a row before the given row position.
* @param {number} beforePosition The row before which the new row should be added, starting at 0 for the first row.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 rows at row index 2 (before the third row)
+ * sheet.insertRowBefore(2);
+ * // Insert 1 row at row index 0 (before the first row)
+ * sheet.insertRowBefore(0);
+ * ```
*/
insertRowBefore(beforePosition: number): FWorksheet {
return this.insertRowsBefore(beforePosition, 1);
@@ -308,6 +426,14 @@ export class FWorksheet extends FBaseInitialable {
* @param rowIndex The index indicating where to insert a row, starting at 0 for the first row.
* @param numRows The number of rows to insert.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 rows at row index 2 (before the third row)
+ * sheet.insertRows(2, 3);
+ * // Insert 1 row at row index 0 (before the first row)
+ * sheet.insertRows(0);
+ * ```
*/
insertRows(rowIndex: number, numRows: number = 1): FWorksheet {
return this.insertRowsBefore(rowIndex, numRows);
@@ -318,6 +444,14 @@ export class FWorksheet extends FBaseInitialable {
* @param afterPosition The row after which the new rows should be added, starting at 0 for the first row.
* @param howMany The number of rows to insert.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 rows at row index 2 (before the third row)
+ * sheet.insertRowsAfter(2, 3);
+ * // Insert 1 row at row index 0 (before the first row)
+ * sheet.insertRowsAfter(0);
+ * ```
*/
insertRowsAfter(afterPosition: number, howMany: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -353,6 +487,14 @@ export class FWorksheet extends FBaseInitialable {
* @param beforePosition The row before which the new rows should be added, starting at 0 for the first row.
* @param howMany The number of rows to insert.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 rows at row index 2 (before the third row)
+ * sheet.insertRowsBefore(2, 3);
+ * // Insert 1 row at row index 0 (before the first row)
+ * sheet.insertRowsBefore(0);
+ * ```
*/
insertRowsBefore(beforePosition: number, howMany: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -387,6 +529,14 @@ export class FWorksheet extends FBaseInitialable {
* Deletes the row at the given row position.
* @param rowPosition The position of the row, starting at 0 for the first row.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Delete 3 rows at row index 2 (rows 3-5)
+ * sheet.deleteRow(2);
+ * // Delete 1 row at row index 0 (first row)
+ * sheet.deleteRow(0);
+ * ```
*/
deleteRow(rowPosition: number): FWorksheet {
return this.deleteRows(rowPosition, 1);
@@ -397,6 +547,14 @@ export class FWorksheet extends FBaseInitialable {
* @param rowPosition The position of the first row to delete, starting at 0 for the first row.
* @param howMany The number of rows to delete.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Delete 3 rows at row index 2 (rows 3-5)
+ * sheet.deleteRows(2, 3);
+ * // Delete 1 row at row index 0 (first row)
+ * sheet.deleteRows(0);
+ * ```
*/
deleteRows(rowPosition: number, howMany: number): FWorksheet {
const range = {
@@ -420,6 +578,14 @@ export class FWorksheet extends FBaseInitialable {
* @param rowSpec A range spanning the rows that should be moved.
* @param destinationIndex The index that the rows should be moved to. Note that this index is based on the coordinates before the rows are moved. Existing data is shifted down to make room for the moved rows while the source rows are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Move 3 rows at row index 2 (rows 3-5) to row index 0
+ * sheet.moveRows(rowSpec, 0);
+ * // Move 1 row at row index 0 (first row) to row index 2
+ * sheet.moveRows(rowSpec, 2);
+ * ```
*/
moveRows(rowSpec: FRange, destinationIndex: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -446,8 +612,16 @@ export class FWorksheet extends FBaseInitialable {
/**
* Hides the rows in the given range.
- * @param row The row range to hide.
- * @returns This sheet, for chaining.
+ * @param {number} row The row range to hide.
+ * @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Hide 3 rows starting from row index 1 (rows 2-4)
+ * sheet.hideRow(1);
+ * // Hide single row at index 0 (first row)
+ * sheet.hideRow(0);
+ * ```
*/
hideRow(row: FRange): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -468,6 +642,14 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} rowIndex The starting index of the rows to hide.
* @param {number} numRows The number of rows to hide.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Hide 3 rows starting from row index 1 (rows 2-4)
+ * sheet.hideRows(1, 3);
+ * // Hide single row at index 0 (first row)
+ * sheet.hideRows(0);
+ * ```
*/
hideRows(rowIndex: number, numRows: number = 1): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -492,6 +674,14 @@ export class FWorksheet extends FBaseInitialable {
* Make the row in the given range visible.
* @param {FRange} row The range to unhide, if hidden.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Unhide 3 rows starting from row index 1 (rows 2-4)
+ * sheet.unhideRow(1);
+ * // Unhide single row at index 0 (first row)
+ * sheet.unhideRow(0);
+ * ```
*/
unhideRow(row: FRange): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -512,6 +702,14 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} rowIndex The starting index of the rows
* @param {number} numRows The number of rows
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Show 3 rows starting from row index 1 (rows 2-4)
+ * sheet.showRows(1);
+ * // Show single row at index 0 (first row)
+ * sheet.showRows(0);
+ * ```
*/
showRows(rowIndex: number, numRows: number = 1): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -538,6 +736,14 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} rowPosition The row position to change.
* @param {number} height The height in pixels to set it to.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Set the height of the second row to 30 pixels
+ * sheet.setRowHeight(1, 30);
+ * // Set the height of the first row to 20 pixels
+ * sheet.setRowHeight(0, 20);
+ * ```
*/
setRowHeight(rowPosition: number, height: number): FWorksheet {
return this.setRowHeights(rowPosition, 1, height);
@@ -550,6 +756,11 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} numRows The number of rows to change.
* @param {number} height The height in pixels to set it to.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * sheet.setRowHeights(1, 10, 30);
+ * ```
*/
setRowHeights(startRow: number, numRows: number, height: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -602,6 +813,11 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} numRows The number of rows to change.
* @param {number} height The height in pixels to set it to.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * sheet.setRowHeightsForced(1, 10, 30);
+ * ```
*/
setRowHeightsForced(startRow: number, numRows: number, height: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -631,6 +847,12 @@ export class FWorksheet extends FBaseInitialable {
* Set custom properties for given rows.
* @param custom The custom properties to set.
* @returns This sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * fWorkSheet.setRowCustom({ key: 'value' });
+ * ```
*/
setRowCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -660,6 +882,14 @@ export class FWorksheet extends FBaseInitialable {
* Inserts a column after the given column position.
* @param afterPosition The column after which the new column should be added, starting at 0 for the first column.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 columns at column index 2 (before column C)
+ * sheet.insertColumnAfter(2);
+ * // Insert 1 column at column index 0 (before column A)
+ * sheet.insertColumnAfter(0);
+ * ```
*/
insertColumnAfter(afterPosition: number): FWorksheet {
return this.insertColumnsAfter(afterPosition, 1);
@@ -669,6 +899,14 @@ export class FWorksheet extends FBaseInitialable {
* Inserts a column before the given column position.
* @param beforePosition The column before which the new column should be added, starting at 0 for the first column.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 columns at column index 2 (before column C)
+ * sheet.insertColumnBefore(2);
+ * // Insert 1 column at column index 0 (before column A)
+ * sheet.insertColumnBefore(0);
+ * ```
*/
insertColumnBefore(beforePosition: number): FWorksheet {
return this.insertColumnsBefore(beforePosition, 1);
@@ -679,6 +917,14 @@ export class FWorksheet extends FBaseInitialable {
* @param columnIndex The index indicating where to insert a column, starting at 0 for the first column.
* @param numColumns The number of columns to insert.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 columns at column index 2 (before column C)
+ * sheet.insertColumns(2, 3);
+ * // Insert 1 column at column index 0 (before column A)
+ * sheet.insertColumns(0);
+ * ```
*/
insertColumns(columnIndex: number, numColumns: number = 1): FWorksheet {
return this.insertColumnsBefore(columnIndex, numColumns);
@@ -689,6 +935,14 @@ export class FWorksheet extends FBaseInitialable {
* @param afterPosition The column after which the new column should be added, starting at 0 for the first column.
* @param howMany The number of columns to insert.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 columns at column index 2 (before column C)
+ * sheet.insertColumnsAfter(2, 3);
+ * // Insert 1 column at column index 0 (before column A)
+ * sheet.insertColumnsAfter(0, 1);
+ * ```
*/
insertColumnsAfter(afterPosition: number, howMany: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -724,6 +978,14 @@ export class FWorksheet extends FBaseInitialable {
* @param beforePosition The column before which the new column should be added, starting at 0 for the first column.
* @param howMany The number of columns to insert.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Insert 3 columns at column index 2 (before column C)
+ * sheet.insertColumnsBefore(2, 3);
+ * // Insert 1 column at column index 0 (before column A)
+ * sheet.insertColumnsBefore(0, 1);
+ * ```
*/
insertColumnsBefore(beforePosition: number, howMany: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -758,6 +1020,14 @@ export class FWorksheet extends FBaseInitialable {
* Deletes the column at the given column position.
* @param columnPosition The position of the column, starting at 0 for the first column.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Delete column C
+ * sheet.deleteColumn(2);
+ * // Delete column A
+ * sheet.deleteColumn(0);
+ * ```
*/
deleteColumn(columnPosition: number): FWorksheet {
return this.deleteColumns(columnPosition, 1);
@@ -768,6 +1038,14 @@ export class FWorksheet extends FBaseInitialable {
* @param columnPosition The position of the first column to delete, starting at 0 for the first column.
* @param howMany The number of columns to delete.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Delete 3 columns at column index 2 (columns C, D, E)
+ * sheet.deleteColumns(2, 3);
+ * // Delete 1 column at column index 0 (column A)
+ * sheet.deleteColumns(0, 1);
+ * ```
*/
deleteColumns(columnPosition: number, howMany: number): FWorksheet {
const range = {
@@ -791,6 +1069,14 @@ export class FWorksheet extends FBaseInitialable {
* @param columnSpec A range spanning the columns that should be moved.
* @param destinationIndex The index that the columns should be moved to. Note that this index is based on the coordinates before the columns are moved. Existing data is shifted right to make room for the moved columns while the source columns are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Move columns C, D, E to column index 2 (columns B, C, D)
+ * sheet.moveColumns({ startColumn: 2, endColumn: 4 }, 1);
+ * // Move column A to column index 0 (column A)
+ * sheet.moveColumns({ startColumn: 0, endColumn: 0 }, 0);
+ * ```
*/
moveColumns(columnSpec: FRange, destinationIndex: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -819,6 +1105,14 @@ export class FWorksheet extends FBaseInitialable {
* Hides the column or columns in the given range.
* @param column The column range to hide.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Hide columns C, D, E
+ * sheet.hideColumn({ startColumn: 2, endColumn: 4 });
+ * // Hide column A
+ * sheet.hideColumn({ startColumn: 0, endColumn: 0 });
+ * ```
*/
hideColumn(column: FRange): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -839,6 +1133,14 @@ export class FWorksheet extends FBaseInitialable {
* @param columnIndex The starting index of the columns to hide.
* @param numColumns The number of columns to hide.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Hide columns C, D, E
+ * sheet.hideColumns(2, 3);
+ * // Hide column A
+ * sheet.hideColumns(0, 1);
+ * ```
*/
hideColumns(columnIndex: number, numColumns: number = 1): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -864,6 +1166,14 @@ export class FWorksheet extends FBaseInitialable {
* Show the column in the given range.
* @param column The range to unhide, if hidden.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Unhide columns C, D, E
+ * sheet.unhideColumn({ startColumn: 2, endColumn: 4 });
+ * // Unhide column A
+ * sheet.unhideColumn({ startColumn: 0, endColumn: 0 });
+ * ```
*/
unhideColumn(column: FRange): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -884,6 +1194,14 @@ export class FWorksheet extends FBaseInitialable {
* @param columnIndex The starting index of the columns to unhide.
* @param numColumns The number of columns to unhide.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Unhide columns C, D, E
+ * sheet.unhideColumns(2, 3);
+ * // Unhide column A
+ * sheet.unhideColumns(0, 1);
+ * ```
*/
showColumns(columnIndex: number, numColumns: number = 1): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -910,6 +1228,12 @@ export class FWorksheet extends FBaseInitialable {
* @param columnPosition The position of the given column to set.
* @param width The width in pixels to set it to.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Set width of column B to 100 pixels
+ * sheet.setColumnWidth(1, 100);
+ * ```
*/
setColumnWidth(columnPosition: number, width: number): FWorksheet {
return this.setColumnWidths(columnPosition, 1, width);
@@ -921,6 +1245,12 @@ export class FWorksheet extends FBaseInitialable {
* @param numColumns The number of columns to change.
* @param width The width in pixels to set it to.
* @returns This sheet, for chaining.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Set width of columns B-D (index 1-3) to 100 pixels
+ * sheet.setColumnWidths(1, 3, 100);
+ * ```
*/
setColumnWidths(startColumn: number, numColumns: number, width: number): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -950,6 +1280,12 @@ export class FWorksheet extends FBaseInitialable {
* Set custom properties for given columns.
* @param custom The custom properties to set.
* @returns This sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * fWorkSheet.setColumnCustom({ 0: { key: 'value' } });
+ * ```
*/
setColumnCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet {
const unitId = this._workbook.getUnitId();
@@ -978,6 +1314,16 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get all merged cells in the current sheet
* @returns all merged cells
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Get all merged ranges in the sheet
+ * const mergedRanges = sheet.getMergedRanges();
+ * // Process each merged range
+ * mergedRanges.forEach(range => {
+ * console.log(range.getA1Notation());
+ * });
+ * ```
*/
getMergedRanges(): FRange[] {
const snapshot = this._worksheet.getSnapshot();
@@ -989,6 +1335,15 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} row The row index.
* @param {number} column The column index.
* @returns {FRange|undefined} The merged cell data, or undefined if the cell is not merged.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const merge = fWorkSheet.getCellMergeData(0, 0);
+ * if (merge) {
+ * console.log('Merged range:', merge.getA1Notation());
+ * }
+ * ```
*/
getCellMergeData(row: number, column: number): FRange | undefined {
const worksheet = this._worksheet;
@@ -1003,6 +1358,15 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns the selected range in the active sheet, or null if there is no active range.
* @returns the active range
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Get the currently active range
+ * const activeRange = sheet.getActiveRange();
+ * if (activeRange) {
+ * console.log('Active range:', activeRange.getA1Notation());
+ * }
+ * ```
*/
getActiveRange(): FRange | null {
return this._fWorkbook.getActiveRange();
@@ -1012,6 +1376,12 @@ export class FWorksheet extends FBaseInitialable {
* Sets the active selection region for this sheet.
* @param {FRange} range The range to set as the active selection.
* @returns {FWorksheet} This sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * fWorkSheet.setActiveRange(fWorkSheet.getRange('A1'));
+ * ```
*/
setActiveRange(range: FRange): FWorksheet {
const { unitId, sheetId } = range.getRange();
@@ -1027,6 +1397,13 @@ export class FWorksheet extends FBaseInitialable {
/**
* Sets the active selection region for this sheet.
* @param range The range to set as the active selection.
+ * @returns This sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * fWorkSheet.setActiveRange(fWorkSheet.getRange('A1'));
+ * ```
*/
setActiveSelection = this.setActiveRange;
@@ -1036,6 +1413,17 @@ export class FWorksheet extends FBaseInitialable {
* that means if you want to freeze the first 3 rows and 2 columns, you should set freeze as { startRow: 3, startColumn: 2, xSplit: 2, ySplit: 3 }
* @deprecated use `setFrozenRows` and `setFrozenColumns` instead.
* @returns True if the command was successful, false otherwise.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Freeze first 3 rows and 2 columns
+ * sheet.setFreeze({
+ * startRow: 3,
+ * startColumn: 2,
+ * xSplit: 2,
+ * ySplit: 3
+ * });
+ * ```
*/
setFreeze(freeze: IFreeze): FWorksheet {
this._logService.warn('setFreeze is deprecated, use setFrozenRows and setFrozenColumns instead');
@@ -1051,6 +1439,12 @@ export class FWorksheet extends FBaseInitialable {
/**
* Cancels the frozen state of the current sheet.
* @returns True if the command was successful, false otherwise.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Cancel freeze
+ * sheet.cancelFreeze();
+ * ```
*/
cancelFreeze(): FWorksheet {
this._commandService.syncExecuteCommand(CancelFrozenCommand.id, {
@@ -1064,7 +1458,13 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the freeze state of the current sheet.
* @returns The freeze state of the current sheet.
- * @deprecated use `getRowFreezeStatus` and `getColumnFreezeStatus` instead.
+ * @example
+ * ```typescript
+ * const sheet = workbook.getActiveSheet();
+ * // Get the freeze state of the current sheet
+ * const freeze = sheet.getFreeze();
+ * console.log(freeze);
+ * ```
*/
getFreeze(): IFreeze {
return this._worksheet.getFreeze();
@@ -1074,6 +1474,14 @@ export class FWorksheet extends FBaseInitialable {
* Set the number of frozen columns.
* @param columns The number of columns to freeze.
* To unfreeze all columns, set this value to 0.
+ * @returns {FWorksheet} This FWorksheet instance.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * // freeze the first 3 columns.
+ * fWorkSheet.setFrozenColumns(3);
+ * ```
*/
setFrozenColumns(columns: number): FWorksheet;
@@ -1123,6 +1531,14 @@ export class FWorksheet extends FBaseInitialable {
* Set the number of frozen rows.
* @param rows The number of rows to freeze.
* To unfreeze all rows, set this value to 0.
+ * @returns {FWorksheet} This FWorksheet instance.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * // freeze the first 3 rows.
+ * fWorkSheet.setFrozenRows(3);
+ * ```
*/
setFrozenRows(rows: number): FWorksheet;
@@ -1170,6 +1586,14 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the number of frozen columns.
* @returns The number of frozen columns, returns 0 if no columns are frozen.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * // Get the number of frozen columns
+ * const frozenColumns = fWorkSheet.getFrozenColumns();
+ * console.log(frozenColumns);
+ * ```
*/
getFrozenColumns(): number {
const freeze = this.getFreeze();
@@ -1182,6 +1606,14 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the number of frozen rows.
* @returns The number of frozen rows. returns 0 if no rows are frozen.
+ * @example
+ * ```typescript
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * // Get the number of frozen rows
+ * const frozenRows = fWorkSheet.getFrozenRows();
+ * console.log(frozenRows);
+ * ```
*/
getFrozenRows(): number {
const freeze = this.getFreeze();
@@ -1194,6 +1626,14 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get freezed rows.
* @returns {IRowRange} The range of the frozen rows.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * // Get the range of the frozen rows
+ * const frozenRows = fWorkSheet.getFrozenRowRange();
+ * console.log(frozenRows);
+ * ```
*/
getFrozenRowRange(): IRowRange {
const cfg = this._worksheet.getFreeze();
@@ -1206,6 +1646,14 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get freezed columns
* @returns {IColumnRange} The range of the frozen columns.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * // Get the range of the frozen columns
+ * const frozenColumns = fWorkSheet.getFrozenColumnRange();
+ * console.log(frozenColumns);
+ * ```
*/
getFrozenColumnRange(): IColumnRange {
const cfg = this._worksheet.getFreeze();
@@ -1277,6 +1725,13 @@ export class FWorksheet extends FBaseInitialable {
/**
* Get the color of the gridlines in the sheet.
* @returns {string | undefined} The color of the gridlines in the sheet or undefined. The default color is 'rgb(214, 216, 219)'.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheet = fWorkbook.getActiveSheet();
+ * // get the gridlines color of the sheet
+ * console.log(fWorkSheet.getGridLinesColor());
+ * ```
*/
getGridLinesColor(): string | undefined {
return this._worksheet.getGridlinesColor() as string | undefined;
@@ -1729,6 +2184,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Set custom metadata of worksheet
* @param {CustomData | undefined} custom custom metadata
+ * @returns {FWorksheet}
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1745,6 +2201,7 @@ export class FWorksheet extends FBaseInitialable {
* Set custom metadata of row
* @param {number} index row index
* @param {CustomData | undefined} custom custom metadata
+ * @returns {FWorksheet}
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -1761,6 +2218,7 @@ export class FWorksheet extends FBaseInitialable {
* Set custom metadata of column
* @param {number} index column index
* @param {CustomData | undefined} custom custom metadata
+ * @returns {FWorksheet}
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
diff --git a/packages/sheets/src/index.ts b/packages/sheets/src/index.ts
index 4b517076ac..563c6263e7 100644
--- a/packages/sheets/src/index.ts
+++ b/packages/sheets/src/index.ts
@@ -17,7 +17,13 @@
export { UniverSheetsPlugin } from './sheets-plugin';
// #region services
-export { COMMAND_LISTENER_SKELETON_CHANGE, COMMAND_LISTENER_VALUE_CHANGE } from './basics/const/command-listener-const';
+export {
+ COMMAND_LISTENER_SKELETON_CHANGE,
+ COMMAND_LISTENER_VALUE_CHANGE,
+ type CommandListenerSkeletonChange,
+ type CommandListenerValueChange,
+ getValueChangedEffectedRange,
+} from './basics/const/command-listener-const';
export {
type IAddWorksheetMergeMutationParams,
type IDeleteRangeMutationParams,