@univerjs/sheets-ui 0.6.1 → 0.6.2-nightly.202503031606

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

@@ -136,12 +136,15 @@ export interface IFSheetsUIEventNameMixin {
      * Type of the event parameter is {@link IBeforeClipboardChangeParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (param) => {
-     *   const {text, html} = param;
-     *   console.log('debugger', text, html); // {text: '...', html: '...'}
-     *   // if want to cancel the clipboard change
-     *   param.cancel = true;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (params) => {
+     *   const { workbook, worksheet, text, html, fromSheet, fromRange } = params;
+     *   console.log(params);
+     *
+     *   // Cancel the clipboard change operation
+     *   params.cancel = true;
      * })
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly BeforeClipboardChange: 'BeforeClipboardChange';
@@ -150,10 +153,12 @@ export interface IFSheetsUIEventNameMixin {
      * Type of the event parameter is {@link IClipboardChangedParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (param) => {
-     *  const {text, html} = param;
-     *  console.log('debugger', text, html); // {text: '...', html: '...'}
+     * const disposable = univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (params) => {
+     *   const { workbook, worksheet, text, html, fromSheet, fromRange } = params;
+     *   console.log(params);
      * })
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly ClipboardChanged: 'ClipboardChanged';
@@ -162,12 +167,15 @@ export interface IFSheetsUIEventNameMixin {
      * Type of the event parameter is {@link IBeforeClipboardPasteParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (param) => {
-     *   const {text, html} = param;
-     *   console.log('debugger', text, html);
-     *   // if want to cancel the clipboard paste
-     *   param.cancel = true;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => {
+     *   const { workbook, worksheet, text, html } = params;
+     *   console.log(params);
+     *
+     *   // Cancel the clipboard paste operation
+     *   params.cancel = true;
      * })
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly BeforeClipboardPaste: 'BeforeClipboardPaste';
@@ -176,10 +184,12 @@ export interface IFSheetsUIEventNameMixin {
      * Type of the event parameter is {@link IClipboardPastedParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (param) => {
-     *   const {text, html} = param;
-     *   console.log('debugger', text, html); // {text: '...', html: '...'}
+     * const disposable = univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (params) => {
+     *   const { workbook, worksheet, text, html } = params;
+     *   console.log(params);
      * })
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly ClipboardPasted: 'ClipboardPasted';
@@ -188,20 +198,29 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link IBeforeSheetEditStartEventParams}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => {
      *   const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params;
+     *   console.log(params);
+     *
+     *   // Cancel the cell edit start operation
+     *   params.cancel = true;
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly BeforeSheetEditStart: 'BeforeSheetEditStart';
     /**
      * Event fired after a cell is edited
-     * @see {@link ISheetEditEndedEventParams}
+     * @see {@link ISheetEditStartedEventParams}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SheetEditStarted, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditStarted, (params) => {
      *   const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SheetEditStarted: 'SheetEditStarted';
@@ -210,9 +229,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISheetEditChangingEventParams}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SheetEditChanging, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditChanging, (params) => {
      *   const { worksheet, workbook, row, column, value, isZenEditor } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SheetEditChanging: 'SheetEditChanging';
@@ -221,9 +243,15 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link IBeforeSheetEditEndEventParams}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => {
-     *   const { worksheet, workbook, row, column, value, eventType, keycode, isZenEditor } = params;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => {
+     *   const { worksheet, workbook, row, column, value, eventType, keycode, isZenEditor, isConfirm } = params;
+     *   console.log(params);
+     *
+     *   // Cancel the cell edit end operation
+     *   params.cancel = true;
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly BeforeSheetEditEnd: 'BeforeSheetEditEnd';
@@ -232,9 +260,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISheetEditEndedEventParams}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => {
-     *   const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => {
+     *   const { worksheet, workbook, row, column, eventType, keycode, isZenEditor, isConfirm } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SheetEditEnded: 'SheetEditEnded';
@@ -243,9 +274,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ICellEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {
-     *      const { worksheet, workbook, row, column, value, isZenEditor } = params;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {
+     *   const { worksheet, workbook, row, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly CellClicked: 'CellClicked';
@@ -254,9 +288,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ICellEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {
      *   const { worksheet, workbook, row, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly CellPointerDown: 'CellPointerDown';
@@ -265,9 +302,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ICellEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {
      *   const { worksheet, workbook, row, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly CellPointerUp: 'CellPointerUp';
@@ -276,9 +316,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ICellEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {
      *   const { worksheet, workbook, row, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly CellHover: 'CellHover';
@@ -287,119 +330,152 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ICellEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {
      *   const { worksheet, workbook, row, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly CellPointerMove: 'CellPointerMove';
     /**
      * Triggered when a row header is clicked
-     * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+     * @see {@link ISheetRowHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.RowHeaderClick, (params) => {
-     *   console.log(`Row ${params.row} header clicked in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderClick, (params) => {
+     *   const { worksheet, workbook, row } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly RowHeaderClick: 'RowHeaderClick';
     /**
      * Triggered when pointer is pressed down on a row header
-     * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+     * @see {@link ISheetRowHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.RowHeaderPointerDown, (params) => {
-     *   console.log(`Pointer down on row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderPointerDown, (params) => {
+     *   const { worksheet, workbook, row } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly RowHeaderPointerDown: 'RowHeaderPointerDown';
     /**
      * Triggered when pointer is released on a row header
-     * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+     * @see {@link ISheetRowHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.RowHeaderPointerUp, (params) => {
-     *   console.log(`Pointer up on row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderPointerUp, (params) => {
+     *   const { worksheet, workbook, row } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly RowHeaderPointerUp: 'RowHeaderPointerUp';
     /**
      * Triggered when pointer hovers over a row header
-     * @param {ISheetRowHeaderEvent} params - Event parameters containing unitId, subUnitId, and row index
+     * @see {@link ISheetRowHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.RowHeaderHover, (params) => {
-     *   console.log(`Hovering over row ${params.row} header in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.RowHeaderHover, (params) => {
+     *   const { worksheet, workbook, row } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly RowHeaderHover: 'RowHeaderHover';
     /**
      * Triggered when a column header is clicked
-     * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+     * @see {@link ISheetColumnHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.ColumnHeaderClick, (params) => {
-     *   console.log(`Column ${params.column} header clicked in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderClick, (params) => {
+     *   const { worksheet, workbook, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly ColumnHeaderClick: 'ColumnHeaderClick';
     /**
      * Triggered when pointer is pressed down on a column header
-     * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+     * @see {@link ISheetColumnHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.ColumnHeaderPointerDown, (params) => {
-     *   console.log(`Pointer down on column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderPointerDown, (params) => {
+     *   const { worksheet, workbook, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly ColumnHeaderPointerDown: 'ColumnHeaderPointerDown';
     /**
      * Triggered when pointer is released on a column header
-     * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+     * @see {@link ISheetColumnHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.ColumnHeaderPointerUp, (params) => {
-     *   console.log(`Pointer up on column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderPointerUp, (params) => {
+     *   const { worksheet, workbook, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly ColumnHeaderPointerUp: 'ColumnHeaderPointerUp';
     /**
      * Triggered when pointer hovers over a column header
-     * @param {ISheetColumnHeaderEvent} params - Event parameters containing unitId, subUnitId, and column index
+     * @see {@link ISheetColumnHeaderEvent}
      * @example
      * ```typescript
-     * univerAPI.onSheetEvent(Event.ColumnHeaderHover, (params) => {
-     *   console.log(`Hovering over column ${params.column} header in sheet ${params.worksheet.getSheetId()}`);
+     * const disposable = univerAPI.addEvent(univerAPI.Event.ColumnHeaderHover, (params) => {
+     *   const { worksheet, workbook, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly ColumnHeaderHover: 'ColumnHeaderHover';
     /**
-     * Event fired when drag over spreadsheet cells
+     * Event fired when the drag element passes over the spreadsheet cells
      * @see {@link ICellEventParam}
      * @example
      * ```ts
-     * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.DragOver, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {
      *   const { worksheet, workbook, row, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly DragOver: 'DragOver';
     /**
-     * Event fired when drop on spreadsheet cells
+     * Event fired when the drag element is dropped on the spreadsheet cells
      * @see {@link ICellEventParam}
      * @example
      * ```ts
-     * univerAPI.getActiveWorkbook().addEvent(univerAPI.Event.Drop, (params) => {
-     *      const { worksheet, workbook, row, column } = params;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.Drop, (params) => {
+     *   const { worksheet, workbook, row, column } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly Drop: 'Drop';
@@ -408,9 +484,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link IScrollEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.Scroll, (params) => {
+     * const disposable = univerAPI.addEvent(univerAPI.Event.Scroll, (params) => {
      *   const { worksheet, workbook, scrollX, scrollY } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly Scroll: 'Scroll';
@@ -419,9 +498,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISelectionEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SelectionChanged, (p)=> {
-     *   const { worksheet, workbook, selections } = p;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionChanged, (params)=> {
+     *   const { worksheet, workbook, selections } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SelectionChanged: 'SelectionChanged';
@@ -430,9 +512,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISelectionEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SelectionMoveStart, (p)=> {
-     *   const { worksheet, workbook, selections } = p;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionMoveStart, (params)=> {
+     *   const { worksheet, workbook, selections } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SelectionMoveStart: 'SelectionMoveStart';
@@ -441,9 +526,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISelectionEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SelectionMoving, (p)=> {
-     *   const { worksheet, workbook, selections } = p;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionMoving, (params)=> {
+     *   const { worksheet, workbook, selections } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SelectionMoving: 'SelectionMoving';
@@ -452,9 +540,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISelectionEventParam}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SelectionMoveEnd, (p)=> {
-     *   const { worksheet, workbook, selections } = p;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SelectionMoveEnd, (params)=> {
+     *   const { worksheet, workbook, selections } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SelectionMoveEnd: 'SelectionMoveEnd';
@@ -463,9 +554,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISheetZoomEvent}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SheetZoomChanged, (p)=> {
-     *   const { worksheet, workbook, zoom } = p;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SheetZoomChanged, (params)=> {
+     *   const { worksheet, workbook, zoom } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SheetZoomChanged: 'SheetZoomChanged';
@@ -474,9 +568,15 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISheetZoomEvent}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.BeforeSheetZoomChange, (p)=> {
-     *   const { worksheet, workbook, zoom } = p;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetZoomChange, (params)=> {
+     *   const { worksheet, workbook, zoom } = params;
+     *   console.log(params);
+     *
+     *   // Cancel the zoom change operation
+     *   params.cancel = true;
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly BeforeSheetZoomChange: 'BeforeSheetZoomChange';
@@ -485,9 +585,12 @@ export interface IFSheetsUIEventNameMixin {
      * @see {@link ISheetSkeletonChangedEvent}
      * @example
      * ```ts
-     * univerAPI.addEvent(univerAPI.Event.SheetSkeletonChanged, (p)=> {
-     *   const { worksheet, workbook } = p;
+     * const disposable = univerAPI.addEvent(univerAPI.Event.SheetSkeletonChanged, (params)=> {
+     *   const { worksheet, workbook, skeleton, payload, effectedRanges } = params;
+     *   console.log(params);
      * });
+     *
+     * // Remove the event listener, use `disposable.dispose()`
      * ```
      */
     readonly SheetSkeletonChanged: 'SheetSkeletonChanged';

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

@@ -5,10 +5,12 @@ import { FPermission } from '@univerjs/sheets/facade';
 export interface IFPermissionSheetsUIMixin {
     /**
      * Set visibility of unauthorized pop-up window
-     * @param {boolean} visible
+     * @param {boolean} visible - visibility of unauthorized pop-up window
      * @example
      * ```ts
-     * univerAPI.getPermission().setPermissionDialogVisible(false);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const permission = fWorkbook.getPermission();
+     * permission.setPermissionDialogVisible(false);
      * ```
      */
     setPermissionDialogVisible(visible: boolean): void;