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.
TypeScript boardcollaborationdocdocxexceloffce365officepdfpptpptxpresentationsdksheetslidesspreadsheetuniverwordwordprocessorworkspacexlsx
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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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';