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(facade): add FWorksheet.getRange(a1Notation) (#3504)
#FF0000a697a49175e0
diff --git a/packages/facade/src/apis/sheets/__tests__/f-range.spec.ts b/packages/facade/src/apis/sheets/__tests__/f-range.spec.tsindex dd17783668..6cf24ff859 100644--- a/packages/facade/src/apis/sheets/__tests__/f-range.spec.ts+++ b/packages/facade/src/apis/sheets/__tests__/f-range.spec.ts@@ -16,16 +16,16 @@/* eslint-disable ts/no-non-null-asserted-optional-chain */-import type { ICellData, Injector, IRange, IStyleData, Nullable } from '@univerjs/core';import { DataValidationType, HorizontalAlign, ICommandService, IUniverInstanceService, VerticalAlign, WrapStrategy } from '@univerjs/core';-import { AddWorksheetMergeCommand, SetHorizontalTextAlignCommand, SetRangeValuesCommand, SetRangeValuesMutation, SetStyleCommand, SetTextWrapCommand, SetVerticalTextAlignCommand } from '@univerjs/sheets';-import { beforeEach, describe, expect, it } from 'vitest';-import { FormulaDataModel } from '@univerjs/engine-formula';+import { AddWorksheetMergeCommand, SetHorizontalTextAlignCommand, SetRangeValuesCommand, SetRangeValuesMutation, SetStyleCommand, SetTextWrapCommand, SetVerticalTextAlignCommand } from '@univerjs/sheets';import { AddSheetDataValidationCommand } from '@univerjs/sheets-data-validation';+import { ClearSheetsFilterCriteriaCommand, RemoveSheetFilterCommand, SetSheetFilterRangeCommand, SetSheetsFilterCriteriaCommand } from '@univerjs/sheets-filter-ui';-import { FUniver } from '../../facade';+import { beforeEach, describe, expect, it } from 'vitest';+import type { ICellData, Injector, IRange, IStyleData, Nullable } from '@univerjs/core';import { createFacadeTestBed } from '../../__tests__/create-test-bed';+import { FUniver } from '../../facade';describe('Test FRange', () => {let get: Injector['get'];@@ -715,4 +715,103 @@ describe('Test FRange', () => {expect(hasError).toBeTruthy();});//#endregion++ // Add these new test cases+ it('Range getRow, getColumn, getWidth, getHeight with A1 notation', () => {+ const activeSheet = univerAPI.getActiveWorkbook()?.getActiveSheet();++ // Test range with A1 notation+ const rangeA1D5 = activeSheet?.getRange('A1:D5');+ expect(rangeA1D5?.getRow()).toBe(0);+ expect(rangeA1D5?.getColumn()).toBe(0);+ expect(rangeA1D5?.getWidth()).toBe(4);+ expect(rangeA1D5?.getHeight()).toBe(5);++ // Test single cell with A1 notation+ const rangeB3 = activeSheet?.getRange('B3');+ expect(rangeB3?.getRow()).toBe(2);+ expect(rangeB3?.getColumn()).toBe(1);+ expect(rangeB3?.getWidth()).toBe(1);+ expect(rangeB3?.getHeight()).toBe(1);++ // Test range with only column letters+ const rangeAD = activeSheet?.getRange('A:D');+ expect(rangeAD?.getRow()).toBe(0);+ expect(rangeAD?.getColumn()).toBe(0);+ expect(rangeAD?.getWidth()).toBe(4);+ expect(rangeAD?.getHeight()).toBe(100);++ // Test range with only row numbers+ const range15 = activeSheet?.getRange('1:5');+ expect(range15?.getRow()).toBe(0);+ expect(range15?.getColumn()).toBe(0);+ // Width should be the maximum number of columns in the sheet+ expect(range15?.getWidth()).toBeGreaterThan(0);+ expect(range15?.getHeight()).toBe(5);++ // Test with sheet name+ const rangeWithSheet = activeSheet?.getRange('sheet1!E6:G8');+ expect(rangeWithSheet?.getRow()).toBe(5);+ expect(rangeWithSheet?.getColumn()).toBe(4);+ expect(rangeWithSheet?.getWidth()).toBe(3);+ expect(rangeWithSheet?.getHeight()).toBe(3);++ // Test case insensitivity+ const rangeCaseInsensitive = activeSheet?.getRange('h10:J12');+ expect(rangeCaseInsensitive?.getRow()).toBe(9);+ expect(rangeCaseInsensitive?.getColumn()).toBe(7);+ expect(rangeCaseInsensitive?.getWidth()).toBe(3);+ expect(rangeCaseInsensitive?.getHeight()).toBe(3);++ // Test invalid range+ expect(() => activeSheet?.getRange('sheet_not_exist!A1:D5').getValues()).toThrow();+ });++ it('Range getValues with A1 notation', () => {+ const activeSheet = univerAPI.getActiveWorkbook()?.getActiveSheet();++ // Set up some test data+ activeSheet?.getRange(0, 0, 5, 4)?.setValues([+ [1, 2, 3, 4],+ [5, 6, 7, 8],+ [9, 10, 11, 12],+ [13, 14, 15, 16],+ [17, 18, 19, 20],+ ]);++ // Test single cell+ expect(activeSheet?.getRange('A1').getValues()).toEqual([[1]]);++ // Test range+ expect(activeSheet?.getRange('A1:D5').getValues()).toEqual([+ [1, 2, 3, 4],+ [5, 6, 7, 8],+ [9, 10, 11, 12],+ [13, 14, 15, 16],+ [17, 18, 19, 20],+ ]);++ // Test case insensitivity+ expect(activeSheet?.getRange('a1:d5').getValues()).toEqual([+ [1, 2, 3, 4],+ [5, 6, 7, 8],+ [9, 10, 11, 12],+ [13, 14, 15, 16],+ [17, 18, 19, 20],+ ]);++ // Test with sheet name+ expect(activeSheet?.getRange('sheet1!A1:D5').getValues()).toEqual([+ [1, 2, 3, 4],+ [5, 6, 7, 8],+ [9, 10, 11, 12],+ [13, 14, 15, 16],+ [17, 18, 19, 20],+ ]);++ // Test out of bounds range+ expect(activeSheet?.getRange('A1:Z100').getValues()).toEqual(expect.arrayContaining([+ expect.arrayContaining([1, 2, 3, 4, null, null, null, null, null, null]),+ ]));+ });});diff --git a/packages/facade/src/apis/sheets/f-worksheet.ts b/packages/facade/src/apis/sheets/f-worksheet.tsindex a70c904365..2759b60b44 100644--- a/packages/facade/src/apis/sheets/f-worksheet.ts+++ b/packages/facade/src/apis/sheets/f-worksheet.ts@@ -15,9 +15,10 @@*/import { Direction, ICommandService, Inject, Injector, RANGE_TYPE } from '@univerjs/core';+import { deserializeRangeWithSheet } from '@univerjs/engine-formula';import { copyRangeStyles, InsertColCommand, InsertRowCommand, MoveColsCommand, MoveRowsCommand, RemoveColCommand, RemoveRowCommand, SetColHiddenCommand, SetColWidthCommand, SetRowHeightCommand, SetRowHiddenCommand, SetSpecificColsVisibleCommand, SetSpecificRowsVisibleCommand, SetWorksheetRowIsAutoHeightCommand, SheetsSelectionsService } from '@univerjs/sheets';-import { DataValidationModel, SheetsDataValidationValidatorService } from '@univerjs/sheets-data-validation';+import { DataValidationModel, SheetsDataValidationValidatorService } from '@univerjs/sheets-data-validation';import { SheetCanvasFloatDomManagerService } from '@univerjs/sheets-drawing-ui';import { SheetsFilterService } from '@univerjs/sheets-filter';import { SheetsThreadCommentModel } from '@univerjs/sheets-thread-comment';@@ -86,17 +87,82 @@ export class FWorksheet {return this._injector.createInstance(FSelection, this._workbook, this._worksheet, selections);}- getRange(row: number, col: number, height?: number, width?: number): FRange {- const range: IRange = {- startRow: row,- endRow: row + (height ?? 1) - 1,- startColumn: col,- endColumn: col + (width ?? 1) - 1,- unitId: this._workbook.getUnitId(),- sheetId: this._worksheet.getSheetId(),- };+ /**+ * Returns a Range object representing a single cell at the specified row and column.+ * @param row The row index of the cell.+ * @param column The column index of the cell.+ * @returns A Range object representing the specified cell.+ */+ getRange(row: number, column: number): FRange;++ /**+ * Returns a Range object representing a range starting at the specified row and column, with the specified number of rows.+ * @param row The starting row index of the range.+ * @param column The starting column index of the range.+ * @param numRows The number of rows in the range.+ * @returns A Range object representing the specified range.+ */+ getRange(row: number, column: number, numRows: number): FRange;++ /**+ * Returns a Range object representing a range starting at the specified row and column, with the specified number of rows and columns.+ * @param row The starting row index of the range.+ * @param column The starting column index of the range.+ * @param numRows The number of rows in the range.+ * @param numColumns The number of columns in the range.+ * @returns A Range object representing the specified range.+ */+ getRange(row: number, column: number, numRows: number, numColumns: number): FRange;++ /**+ * 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.+ */+ getRange(a1Notation: string): FRange;++ getRange(rowOrA1Notation: number | string, column?: number, numRows?: number, numColumns?: number): FRange {+ let range: IRange;+ let sheet: Worksheet;++ if (typeof rowOrA1Notation === 'string') {+ // A1 notation+ const { range: parsedRange, sheetName } = deserializeRangeWithSheet(rowOrA1Notation);++ const rangeSheet = sheetName ? this._workbook.getSheetBySheetName(sheetName) : this._worksheet;+ if (!rangeSheet) {+ throw new Error('Range not found');+ }+ sheet = rangeSheet;++ range = {+ ...parsedRange,+ unitId: this._workbook.getUnitId(),+ sheetId: sheet.getSheetId(),+ // Use the current range instead of the future actual range to match Apps Script behavior.+ // Users can create the latest range in real time when needed.+ rangeType: RANGE_TYPE.NORMAL,+ startRow: parsedRange.rangeType === RANGE_TYPE.COLUMN ? 0 : parsedRange.startRow,+ endRow: parsedRange.rangeType === RANGE_TYPE.COLUMN ? sheet.getMaxRows() - 1 : parsedRange.endRow,+ startColumn: parsedRange.rangeType === RANGE_TYPE.ROW ? 0 : parsedRange.startColumn,+ endColumn: parsedRange.rangeType === RANGE_TYPE.ROW ? sheet.getMaxColumns() - 1 : parsedRange.endColumn,+ };+ } else if (typeof rowOrA1Notation === 'number' && column !== undefined) {+ sheet = this._worksheet;+ // Range+ range = {+ startRow: rowOrA1Notation,+ endRow: rowOrA1Notation + (numRows ?? 1) - 1,+ startColumn: column,+ endColumn: column + (numColumns ?? 1) - 1,+ unitId: this._workbook.getUnitId(),+ sheetId: this._worksheet.getSheetId(),+ };+ } else {+ throw new Error('Invalid range specification');+ }- return this._injector.createInstance(FRange, this._workbook, this._worksheet, range);+ return this._injector.createInstance(FRange, this._workbook, sheet, range);}/**