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(sort)!: optimize sort facade api (#4412)

YuHongf6df44dc53c8
diff --git a/packages/sheets-sort/src/facade/f-event.ts b/packages/sheets-sort/src/facade/f-event.ts
new file mode 100644
index 0000000000..e66c61eb43
--- /dev/null
+++ b/packages/sheets-sort/src/facade/f-event.ts
@@ -0,0 +1,151 @@
+/**
+ * Copyright 2023-present DreamNum Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { ICommandInfo, IEventBase, Injector } from '@univerjs/core';
+import type { FRange, FWorkbook, FWorksheet } from '@univerjs/sheets/facade';
+import { FEventName, FUniver, ICommandService } from '@univerjs/core';
+import { type ISortRangeCommandParams, SortRangeCommand, SortType } from '@univerjs/sheets-sort';
+import { FSheetEventName } from '@univerjs/sheets/facade';
+
+export interface IFSheetSortEventMixin {
+ /**
+ * This event will be emitted when a range on a worksheet is sorted.
+ * Type of the event is {@link ISheetRangeSortedParams}.
+ *
+ * @example
+ * ```typescript
+ * const callbackDisposable = univerAPI.addEvent(univerAPI.Event.SheetRangeSorted, (params) => {
+ * const { workbook, worksheet, sortColumn } = params;
+ * sortColumn.forEach((col) => {
+ * console.log(col.column, col.ascending);
+ * });
+ * });
+ * ```
+ */
+ SheetRangeSorted: 'SheetRangeSorted';
+ /**
+ * This event will be emitted before sorting a range on a worksheet.
+ * Type of the event is {@link ISheetRangeSortParams}.
+ *
+ * @example
+ * ```typescript
+ * const callbackDisposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeSort, (params) => {
+ * const { workbook, worksheet, sortColumn } = params;
+ * sortColumn.forEach((col) => {
+ * console.log(col.column, col.ascending);
+ * });
+ * });
+ * ```
+ */
+ SheetBeforeRangeSort: 'SheetBeforeRangeSort';
+}
+
+export class FSheetSortEventName extends FEventName implements IFSheetSortEventMixin {
+ override readonly SheetRangeSorted = 'SheetRangeSorted' as const;
+ override readonly SheetBeforeRangeSort = 'SheetBeforeRangeSort' as const;
+}
+
+interface ISortColumn {
+ column: number;
+ ascending: boolean;
+}
+
+export interface ISheetRangeSortParams extends IEventBase {
+ workbook: FWorkbook;
+ worksheet: FWorksheet;
+ range: FRange;
+ sortColumn: ISortColumn[];
+}
+
+export interface ISheetRangeSortEventParamConfig {
+ SheetBeforeRangeSort: ISheetRangeSortParams;
+ SheetRangeSorted: ISheetRangeSortParams;
+}
+
+FEventName.extend(FSheetEventName);
+declare module '@univerjs/core' {
+ // eslint-disable-next-line ts/naming-convention
+ interface FEventName extends IFSheetSortEventMixin { }
+ interface IEventParamConfig extends ISheetRangeSortEventParamConfig { }
+}
+
+class FUniverSheetsSortEventMixin extends FUniver {
+ override _initialize(injector: Injector): void {
+ const commandService = injector.get(ICommandService);
+
+ this.disposeWithMe(commandService.beforeCommandExecuted((commandInfo) => {
+ switch (commandInfo.id) {
+ case SortRangeCommand.id:
+ this._beforeRangeSort(commandInfo as Readonly<ICommandInfo<ISortRangeCommandParams>>);
+ break;
+ }
+ }));
+
+ this.disposeWithMe(commandService.onCommandExecuted((commandInfo) => {
+ switch (commandInfo.id) {
+ case SortRangeCommand.id:
+ this._onRangeSorted(commandInfo as Readonly<ICommandInfo<ISortRangeCommandParams>>);
+ break;
+ }
+ }));
+ }
+
+ private _beforeRangeSort(commandInfo: Readonly<ICommandInfo<ISortRangeCommandParams>>): void {
+ const params = commandInfo.params!;
+ const fWorkbook = this.getUniverSheet(params.unitId)!;
+ const fWorksheet = fWorkbook.getSheetBySheetId(params.subUnitId)!;
+ const { startColumn, endColumn, startRow, endRow } = params.range;
+ const fRange = fWorksheet.getRange(startRow, startColumn, endRow - startRow + 1, endColumn - startColumn + 1);
+ const eventParams: ISheetRangeSortParams = {
+ workbook: fWorkbook,
+ worksheet: fWorksheet,
+ range: fRange,
+ sortColumn: params.orderRules.map((rule) => ({
+ column: rule.colIndex - startColumn,
+ ascending: rule.type === SortType.ASC,
+ })),
+ };
+
+ this.fireEvent(this.Event.SheetBeforeRangeSort, eventParams);
+ if (eventParams.cancel) {
+ throw new Error('SortRangeCommand canceled.');
+ }
+ }
+
+ private _onRangeSorted(commandInfo: Readonly<ICommandInfo<ISortRangeCommandParams>>): void {
+ const params = commandInfo.params!;
+ const fWorkbook = this.getUniverSheet(params.unitId)!;
+ const fWorksheet = fWorkbook.getSheetBySheetId(params.subUnitId)!;
+ const { startColumn, endColumn, startRow, endRow } = params.range;
+ const fRange = fWorksheet.getRange(startRow, startColumn, endRow - startRow + 1, endColumn - startColumn + 1);
+ const eventParams: ISheetRangeSortParams = {
+ workbook: fWorkbook,
+ worksheet: fWorksheet,
+ range: fRange,
+ sortColumn: params.orderRules.map((rule) => ({
+ column: rule.colIndex - startColumn,
+ ascending: rule.type === SortType.ASC,
+ })),
+ };
+
+ this.fireEvent(this.Event.SheetRangeSorted, eventParams);
+ if (eventParams.cancel) {
+ throw new Error('SortRangeCommand canceled.');
+ }
+ }
+}
+
+FUniver.extend(FUniverSheetsSortEventMixin);
diff --git a/packages/sheets-sort/src/facade/f-range.ts b/packages/sheets-sort/src/facade/f-range.ts
index c144748bb3..d3905d0677 100644
--- a/packages/sheets-sort/src/facade/f-range.ts
+++ b/packages/sheets-sort/src/facade/f-range.ts
@@ -22,28 +22,40 @@ export type SortColumnSpec = { column: number; ascending: boolean } | number;
export interface IFRangeSort {
/**
- * Sort the range by the specified column(s) with specified order.
+ * Sorts the cells in the given range, by column(s) and order specified.
*
- * @async
+ * @param {SortColumnSpec | SortColumnSpec[]} column The column index with order or an array of column indexes with order. The column index starts from 1.
*
- * @return The range itself to chain other operations.
+ * @returns The range itself for chaining.
+ *
+ * @example
+ * ```typescript
+ * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+ * const activeSheet = activeSpreadsheet.getActiveSheet();
+ * const range = activeSheet.getRange(0, 0, 10, 10);
+ * range.sort(1); // Sorts the range by the first column in ascending order.
+ * range.sort({ column: 1, ascending: false }); // Sorts the range by the first column in descending order.
+ * range.sort([{ column: 1, ascending: false }, 2]); // Sorts the range by the first column in descending order and the second column in ascending order.
+ * ```
*/
- sort(column: SortColumnSpec | SortColumnSpec[]): Promise<FRange>;
+ sort(column: SortColumnSpec | SortColumnSpec[]): FRange;
}
export class FRangeSort extends FRange implements IFRangeSort {
- override async sort(column: SortColumnSpec | SortColumnSpec[]): Promise<FRange> {
+ override sort(column: SortColumnSpec | SortColumnSpec[]): FRange {
+ const columnBase = this._range.startColumn;
const columns = Array.isArray(column) ? column : [column];
+
const orderRules: IOrderRule[] = columns.map((c) => {
if (typeof c === 'number') {
- return { colIndex: c, type: SortType.ASC };
+ return { colIndex: c + columnBase, type: SortType.ASC };
}
return {
- colIndex: c.column,
+ colIndex: c.column + columnBase,
type: c.ascending ? SortType.ASC : SortType.DESC,
};
});
- await this._commandService.executeCommand(SortRangeCommand.id, {
+ this._commandService.syncExecuteCommand(SortRangeCommand.id, {
orderRules,
range: this._range,
hasTitle: false,
diff --git a/packages/sheets-sort/src/facade/f-worksheet.ts b/packages/sheets-sort/src/facade/f-worksheet.ts
index 746fb52d8e..d8bba9d6a6 100644
--- a/packages/sheets-sort/src/facade/f-worksheet.ts
+++ b/packages/sheets-sort/src/facade/f-worksheet.ts
@@ -24,18 +24,25 @@ export interface IFWorksheetSort {
/**
* Sort the worksheet by the specified column.
*
- * @async
+ * @param {number} colIndex The column index to sort by. which starts from 1.
+ * @param {boolean} [asc=true] The sort order. `true` for ascending, `false` for descending.
+ * @returns The worksheet itself for chaining.
*
- * @param colIndex The column index to sort by.
- * @param asc Whether to sort in ascending order. Default is `true`.
- * @returns The worksheet itself to chain calls.
+ * @example
+ * ```typescript
+ * const activeSpreadsheet = univerAPI.getActiveWorkbook();
+ * const activeSheet = activeSpreadsheet.getActiveSheet();
+ * activeSheet.sort(1); // Sorts the worksheet by the first column in ascending order.
+ * activeSheet.sort(1, false); // Sorts the worksheet by the first column in descending order.
+ * ```
*/
- sort(colIndex: number, asc?: boolean): Promise<FWorksheet>;
+ sort(colIndex: number, asc?: boolean): FWorksheet;
}
export class FWorksheetSort extends FWorksheet implements IFWorksheetSort {
- override async sort(colIndex: number, asc = true): Promise<FWorksheet> {
+ override sort(colIndex: number, asc = true): FWorksheet {
const orderRules: IOrderRule[] = [{
+ // real column index should be colIndex - 1.
colIndex,
type: asc ? SortType.ASC : SortType.DESC,
}];
@@ -47,7 +54,7 @@ export class FWorksheetSort extends FWorksheet implements IFWorksheetSort {
endColumn: this._worksheet.getColumnCount() - 1,
rangeType: RANGE_TYPE.ALL,
};
- await this._commandService.executeCommand(SortRangeCommand.id, {
+ this._commandService.syncExecuteCommand(SortRangeCommand.id, {
orderRules,
range,
hasTitle: false,
diff --git a/packages/sheets-sort/src/facade/index.ts b/packages/sheets-sort/src/facade/index.ts
index 30ebc808e8..e87f02c989 100644
--- a/packages/sheets-sort/src/facade/index.ts
+++ b/packages/sheets-sort/src/facade/index.ts
@@ -16,6 +16,8 @@
import './f-range';
import './f-worksheet';
+import './f-event';
+export type * from './f-event';
export type * from './f-range';
export type * from './f-worksheet';