@univerjs/sheets 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/es/facade.js CHANGED
@@ -2,7 +2,7 @@ import { BooleanNumber, CanceledError, DEFAULT_STYLES, Dimension, Direction, Hor
2
2
  import { FBase, FBaseInitialable, FEnum, FEventName, FUniver } from "@univerjs/core/facade";
3
3
  import { AddRangeProtectionMutation, AddWorksheetProtectionMutation, AppendRowCommand, AutoFillCommand, COMMAND_LISTENER_VALUE_CHANGE, CancelFrozenCommand, ClearSelectionAllCommand, ClearSelectionContentCommand, ClearSelectionFormatCommand, CopySheetCommand, DeleteRangeMoveLeftCommand, DeleteRangeMoveUpCommand, DeleteRangeProtectionMutation, DeleteWorksheetProtectionMutation, DeleteWorksheetRangeThemeStyleCommand, EditStateEnum, InsertColByRangeCommand, InsertRangeMoveDownCommand, InsertRangeMoveRightCommand, InsertRowByRangeCommand, InsertSheetCommand, MoveColsCommand, MoveRowsCommand, RangeProtectionPermissionDeleteProtectionPoint, RangeProtectionPermissionEditPoint, RangeProtectionPermissionManageCollaPoint, RangeProtectionPermissionViewPoint, RangeProtectionRuleModel, RangeThemeStyle, RegisterWorksheetRangeThemeStyleCommand, RemoveColByRangeCommand, RemoveDefinedNameCommand, RemoveRowByRangeCommand, RemoveSheetCommand, RemoveWorksheetMergeCommand, SCOPE_WORKBOOK_VALUE_DEFINED_NAME, SetBorderBasicCommand, SetColDataCommand, SetColHiddenCommand, SetColWidthCommand, SetDefinedNameCommand, SetFrozenCommand, SetGridlinesColorCommand, SetHorizontalTextAlignCommand, SetRangeCustomMetadataCommand, SetRangeProtectionMutation, SetRangeValuesCommand, SetRowDataCommand, SetRowHeightCommand, SetRowHiddenCommand, SetSelectionsOperation, SetShrinkToFitCommand, SetSpecificColsVisibleCommand, SetSpecificRowsVisibleCommand, SetStyleCommand, SetTabColorCommand, SetTabColorMutation, SetTextRotationCommand, SetTextWrapCommand, SetVerticalTextAlignCommand, SetWorkbookCalculationSettingsCommand, SetWorkbookNameCommand, SetWorksheetActiveOperation, SetWorksheetColumnCountCommand, SetWorksheetDefaultStyleMutation, SetWorksheetHideCommand, SetWorksheetHideMutation, SetWorksheetNameCommand, SetWorksheetOrderCommand, SetWorksheetOrderMutation, SetWorksheetRangeThemeStyleCommand, SetWorksheetRowCountCommand, SetWorksheetRowIsAutoHeightCommand, SetWorksheetRowIsAutoHeightMutation, SetWorksheetShowCommand, SheetRangeThemeService, SheetSkeletonChangeType, SheetValueChangeType, SheetsFreezeSyncController, SheetsSelectionsService, SplitDelimiterEnum, SplitTextToColumnsCommand, ToggleGridlinesCommand, UnregisterWorksheetRangeThemeStyleCommand, ViewStateEnum, WorkbookCommentPermission, WorkbookCopyPermission, WorkbookCopySheetPermission, WorkbookCreateProtectPermission, WorkbookCreateSheetPermission, WorkbookDeleteColumnPermission, WorkbookDeleteRowPermission, WorkbookDeleteSheetPermission, WorkbookDuplicatePermission, WorkbookEditablePermission, WorkbookExportPermission, WorkbookHideSheetPermission, WorkbookInsertColumnPermission, WorkbookInsertRowPermission, WorkbookManageCollaboratorPermission, WorkbookMoveSheetPermission, WorkbookPrintPermission, WorkbookRecoverHistoryPermission, WorkbookRenameSheetPermission, WorkbookSharePermission, WorkbookViewHistoryPermission, WorkbookViewPermission, WorksheetCopyPermission, WorksheetDeleteColumnPermission, WorksheetDeleteProtectionPermission, WorksheetDeleteRowPermission, WorksheetEditExtraObjectPermission, WorksheetEditPermission, WorksheetFilterPermission, WorksheetInsertColumnPermission, WorksheetInsertHyperlinkPermission, WorksheetInsertRowPermission, WorksheetManageCollaboratorPermission, WorksheetPivotTablePermission, WorksheetProtectionPointModel, WorksheetProtectionRuleModel, WorksheetSelectProtectedCellsPermission, WorksheetSelectUnProtectedCellsPermission, WorksheetSetCellStylePermission, WorksheetSetCellValuePermission, WorksheetSetColumnStylePermission, WorksheetSetRowStylePermission, WorksheetSortPermission, WorksheetViewPermission, addMergeCellsUtil, copyRangeStyles, getAddMergeMutationRangeByType, getAllWorksheetPermissionPoint, getAllWorksheetPermissionPointByPointPanel, getNextPrimaryCell, getPrimaryForRange, getValueChangedEffectedRange, validateDefinedName } from "@univerjs/sheets";
4
4
  import { FormulaDataModel, IDefinedNamesService, IFunctionService, ISuperTableService, deserializeRangeWithSheet, serializeRange, serializeRangeWithSheet } from "@univerjs/engine-formula";
5
- import { ObjectScope, UnitAction, UnitObject, UnitRole } from "@univerjs/protocol";
5
+ import { ObjectScope, UnitAction, UnitObject, UnitRole as UnitRole$1 } from "@univerjs/protocol";
6
6
 
7
7
  // src/facade/const.ts
8
8
  /**
@@ -22,7 +22,7 @@ import { ObjectScope, UnitAction, UnitObject, UnitRole } from "@univerjs/protoco
22
22
  */
23
23
  const SHEETS_CUSTOM_FIELD_WARNING_MESSAGE = "[Facade]: The sheets custom field is not recommended for external use. Use it at your own risk.";
24
24
 
25
- // \0@oxc-project+runtime@0.156.0/helpers/esm/typeof.js
25
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/typeof.js
26
26
  function _typeof(o) {
27
27
  "@babel/helpers - typeof";
28
28
  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -32,25 +32,25 @@ function _typeof(o) {
32
32
  }, _typeof(o);
33
33
  }
34
34
 
35
- // \0@oxc-project+runtime@0.156.0/helpers/esm/toPrimitive.js
36
- function toPrimitive(t, r) {
35
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/toPrimitive.js
36
+ function toPrimitive(t, e) {
37
37
  if ("object" != _typeof(t) || !t) return t;
38
- var e = t[Symbol.toPrimitive];
39
- if (void 0 !== e) {
40
- var i = e.call(t, r || "default");
38
+ var r;
39
+ if ("undefined" != typeof Symbol && void 0 !== (r = t[Symbol.toPrimitive])) {
40
+ var i = r.call(t, e || "default");
41
41
  if ("object" != _typeof(i)) return i;
42
42
  throw new TypeError("@@toPrimitive must return a primitive value.");
43
43
  }
44
- return ("string" === r ? String : Number)(t);
44
+ return ("string" === e ? String : Number)(t);
45
45
  }
46
46
 
47
- // \0@oxc-project+runtime@0.156.0/helpers/esm/toPropertyKey.js
47
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/toPropertyKey.js
48
48
  function toPropertyKey(t) {
49
49
  var i = toPrimitive(t, "string");
50
50
  return "symbol" == _typeof(i) ? i : i + "";
51
51
  }
52
52
 
53
- // \0@oxc-project+runtime@0.156.0/helpers/esm/defineProperty.js
53
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/defineProperty.js
54
54
  function _defineProperty(e, r, t) {
55
55
  return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
56
56
  value: t,
@@ -60,14 +60,14 @@ function _defineProperty(e, r, t) {
60
60
  }) : e[r] = t, e;
61
61
  }
62
62
 
63
- // \0@oxc-project+runtime@0.156.0/helpers/esm/decorateParam.js
63
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/decorateParam.js
64
64
  function __decorateParam(paramIndex, decorator) {
65
65
  return function(target, key) {
66
66
  decorator(target, key, paramIndex);
67
67
  };
68
68
  }
69
69
 
70
- // \0@oxc-project+runtime@0.156.0/helpers/esm/decorate.js
70
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/decorate.js
71
71
  function __decorate(decorators, target, key, desc) {
72
72
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
73
73
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -771,7 +771,7 @@ FSelection = _FSelection = __decorate([__decorateParam(3, Inject(Injector))], FS
771
771
  /**
772
772
  * User role in a unit (Workbook)
773
773
  */
774
- let UnitRole$1 = /* @__PURE__ */ function(UnitRole) {
774
+ let UnitRole = /* @__PURE__ */ function(UnitRole) {
775
775
  UnitRole[UnitRole["Reader"] = 0] = "Reader";
776
776
  UnitRole[UnitRole["Editor"] = 1] = "Editor";
777
777
  UnitRole[UnitRole["Owner"] = 2] = "Owner";
@@ -1176,7 +1176,7 @@ let FRangeProtectionRule = class FRangeProtectionRule {
1176
1176
  name: this._options.name || "",
1177
1177
  strategies: [{
1178
1178
  action: instance.subType,
1179
- role: value ? UnitRole.Editor : UnitRole.Owner
1179
+ role: value ? UnitRole$1.Editor : UnitRole$1.Owner
1180
1180
  }],
1181
1181
  scope: void 0,
1182
1182
  collaborators: void 0
@@ -1398,7 +1398,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1398
1398
  }
1399
1399
  collaborators.push({
1400
1400
  id: existingCollaborator.id,
1401
- role: UnitRole.Editor,
1401
+ role: UnitRole$1.Editor,
1402
1402
  subject: existingCollaborator.subject
1403
1403
  });
1404
1404
  });
@@ -1409,10 +1409,10 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1409
1409
  collaborators,
1410
1410
  unitID: this._unitId,
1411
1411
  strategies: [{
1412
- role: UnitRole.Editor,
1412
+ role: UnitRole$1.Editor,
1413
1413
  action: UnitAction.Edit
1414
1414
  }, {
1415
- role: UnitRole.Reader,
1415
+ role: UnitRole$1.Reader,
1416
1416
  action: UnitAction.View
1417
1417
  }],
1418
1418
  name: (options === null || options === void 0 ? void 0 : options.name) || "",
@@ -1561,7 +1561,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1561
1561
  name: worksheetProtectionRule.description || "",
1562
1562
  strategies: [{
1563
1563
  action: instance.subType,
1564
- role: value ? UnitRole.Editor : UnitRole.Owner
1564
+ role: value ? UnitRole$1.Editor : UnitRole$1.Owner
1565
1565
  }],
1566
1566
  scope: void 0,
1567
1567
  collaborators: void 0
@@ -1778,7 +1778,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1778
1778
  }
1779
1779
  collaborators.push({
1780
1780
  id: existingCollaborator.id,
1781
- role: UnitRole.Editor,
1781
+ role: UnitRole$1.Editor,
1782
1782
  subject: existingCollaborator.subject
1783
1783
  });
1784
1784
  });
@@ -2277,7 +2277,6 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2277
2277
  ...parsedRange,
2278
2278
  unitId: this._workbook.getUnitId(),
2279
2279
  sheetId: sheet.getSheetId(),
2280
- rangeType: RANGE_TYPE.NORMAL,
2281
2280
  startRow: parsedRange.rangeType === RANGE_TYPE.COLUMN ? 0 : parsedRange.startRow,
2282
2281
  endRow: parsedRange.rangeType === RANGE_TYPE.COLUMN ? sheet.getMaxRows() - 1 : parsedRange.endRow,
2283
2282
  startColumn: parsedRange.rangeType === RANGE_TYPE.ROW ? 0 : parsedRange.startColumn,
@@ -2326,6 +2325,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2326
2325
  }
2327
2326
  /**
2328
2327
  * Inserts a row after the given row position.
2328
+ *
2329
+ * To insert multiple rows, prefer {@link FWorksheet.insertRowsAfter} with the full count
2330
+ * instead of repeatedly calling this method.
2331
+ *
2329
2332
  * @param {number} afterPosition - The existing row after which the new row should be added. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
2330
2333
  * @returns {FWorksheet} This sheet, for chaining.
2331
2334
  * @example
@@ -2343,6 +2346,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2343
2346
  }
2344
2347
  /**
2345
2348
  * Inserts a row before the given row position.
2349
+ *
2350
+ * To insert multiple rows, prefer {@link FWorksheet.insertRowsBefore} with the full count
2351
+ * instead of repeatedly calling this method.
2352
+ *
2346
2353
  * @param {number} beforePosition - The existing row before which the new row should be added. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
2347
2354
  * @returns {FWorksheet} This sheet, for chaining.
2348
2355
  * @example
@@ -2360,6 +2367,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2360
2367
  }
2361
2368
  /**
2362
2369
  * Inserts one or more consecutive blank rows in a sheet starting at the specified location.
2370
+ *
2371
+ * For multiple consecutive rows, pass the full `numRows` in one call instead of looping
2372
+ * with the default count of one.
2373
+ *
2363
2374
  * @param {number} rowIndex - The existing row before which rows are inserted. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
2364
2375
  * @param {number} [numRows] - The positive number of rows to insert.
2365
2376
  * @returns {FWorksheet} This sheet, for chaining.
@@ -2457,6 +2468,11 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2457
2468
  }
2458
2469
  /**
2459
2470
  * Deletes the row at the given row position.
2471
+ *
2472
+ * For consecutive rows, prefer {@link FWorksheet.deleteRows} with the full count. For
2473
+ * non-contiguous rows, use {@link FWorksheet.deleteRowsByPoints} so shifting indices are handled
2474
+ * without a manual loop over this method.
2475
+ *
2460
2476
  * @param {number} rowPosition - The position of the row, starting at 0 for the first row.
2461
2477
  * @returns {FWorksheet} This sheet, for chaining.
2462
2478
  * @example
@@ -2558,6 +2574,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2558
2574
  }
2559
2575
  /**
2560
2576
  * Hides the rows in the given range.
2577
+ *
2578
+ * For multiple rows, pass an FRange spanning all target rows in one call. If you already have
2579
+ * a starting index and count, use {@link FWorksheet.hideRows} instead of calling this method for each row.
2580
+ *
2561
2581
  * @param {FRange} row - The row range to hide.
2562
2582
  * @returns {FWorksheet} This sheet, for chaining.
2563
2583
  * @example
@@ -2585,6 +2605,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2585
2605
  }
2586
2606
  /**
2587
2607
  * Hides one or more consecutive rows starting at the given index. Use 0-index for this method
2608
+ *
2609
+ * For multiple consecutive rows, pass the full `numRow` in one call instead of looping
2610
+ * with the default count of one.
2611
+ *
2588
2612
  * @param {number} rowIndex - The starting index of the rows to hide
2589
2613
  * @param {number} [numRow] - The number of rows to hide
2590
2614
  * @returns {FWorksheet} This sheet, for chaining.
@@ -2617,6 +2641,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2617
2641
  }
2618
2642
  /**
2619
2643
  * Make the row in the given range visible.
2644
+ *
2645
+ * For multiple rows, pass an FRange spanning all target rows in one call. If you already have
2646
+ * a starting index and count, use {@link FWorksheet.showRows} instead of calling this method for each row.
2647
+ *
2620
2648
  * @param {FRange} row - The range to unhide, if hidden.
2621
2649
  * @returns {FWorksheet} This sheet, for chaining.
2622
2650
  * @example
@@ -2644,6 +2672,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2644
2672
  }
2645
2673
  /**
2646
2674
  * Unhides one or more consecutive rows starting at the given zero-based index.
2675
+ *
2676
+ * For multiple consecutive rows, pass the full `numRows` in one call instead of looping
2677
+ * with the default count of one.
2678
+ *
2647
2679
  * @param {number} rowIndex - The starting index of the rows
2648
2680
  * @param {number} [numRows] - The number of rows
2649
2681
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -2676,6 +2708,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2676
2708
  }
2677
2709
  /**
2678
2710
  * Sets the row height of the given row in pixels. By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).
2711
+ *
2712
+ * For the same height across consecutive rows, prefer {@link FWorksheet.setRowHeights} with the full
2713
+ * row count instead of calling this method for each row.
2714
+ *
2679
2715
  * @param {number} rowPosition - The row position to change.
2680
2716
  * @param {number} height - The height in pixels to set it to.
2681
2717
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -2903,6 +2939,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2903
2939
  }
2904
2940
  /**
2905
2941
  * Inserts a column after the given column position.
2942
+ *
2943
+ * To insert multiple columns, prefer {@link FWorksheet.insertColumnsAfter} with the full count
2944
+ * instead of repeatedly calling this method.
2945
+ *
2906
2946
  * @param {number} afterPosition - The column after which the new column should be added, starting at 0 for the first column
2907
2947
  * @returns {FWorksheet} This worksheet instance for chaining
2908
2948
  * @example
@@ -2920,6 +2960,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2920
2960
  }
2921
2961
  /**
2922
2962
  * Inserts a column before the given column position.
2963
+ *
2964
+ * To insert multiple columns, prefer {@link FWorksheet.insertColumnsBefore} with the full count
2965
+ * instead of repeatedly calling this method.
2966
+ *
2923
2967
  * @param {number} beforePosition - The column before which the new column should be added, starting at 0 for the first column
2924
2968
  * @returns {FWorksheet} This worksheet instance for chaining
2925
2969
  * @example
@@ -2937,6 +2981,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2937
2981
  }
2938
2982
  /**
2939
2983
  * Inserts one or more consecutive blank columns in a sheet starting at the specified location.
2984
+ *
2985
+ * For multiple consecutive columns, pass the full `numColumns` in one call instead of looping
2986
+ * with the default count of one.
2987
+ *
2940
2988
  * @param {number} columnIndex - The index indicating where to insert a column, starting at 0 for the first column
2941
2989
  * @param {number} [numColumns] - The number of columns to insert
2942
2990
  * @returns {FWorksheet} This sheet, for chaining
@@ -3031,6 +3079,11 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3031
3079
  }
3032
3080
  /**
3033
3081
  * Deletes the column at the given column position.
3082
+ *
3083
+ * For consecutive columns, prefer {@link FWorksheet.deleteColumns} with the full count. For
3084
+ * non-contiguous columns, use {@link FWorksheet.deleteColumnsByPoints} so shifting indices are handled
3085
+ * without a manual loop over this method.
3086
+ *
3034
3087
  * @param {number} columnPosition - The position of the column, starting at 0 for the first column
3035
3088
  * @returns {FWorksheet} This sheet, for chaining
3036
3089
  * @example
@@ -3132,6 +3185,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3132
3185
  }
3133
3186
  /**
3134
3187
  * Hides the column or columns in the given range.
3188
+ *
3189
+ * For multiple columns, pass an FRange spanning all target columns in one call. If you already have
3190
+ * a starting index and count, use {@link FWorksheet.hideColumns} instead of calling this method for each column.
3191
+ *
3135
3192
  * @param {FRange} column - The column range to hide
3136
3193
  * @returns {FWorksheet} This sheet, for chaining
3137
3194
  * @example
@@ -3159,6 +3216,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3159
3216
  }
3160
3217
  /**
3161
3218
  * Hides one or more consecutive columns starting at the given index. Use 0-index for this method
3219
+ *
3220
+ * For multiple consecutive columns, pass the full `numColumn` in one call instead of looping
3221
+ * with the default count of one.
3222
+ *
3162
3223
  * @param {number} columnIndex - The starting index of the columns to hide
3163
3224
  * @param {number} [numColumn] - The number of columns to hide
3164
3225
  * @returns {FWorksheet} This sheet, for chaining
@@ -3191,6 +3252,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3191
3252
  }
3192
3253
  /**
3193
3254
  * Show the column in the given range.
3255
+ *
3256
+ * For multiple columns, pass an FRange spanning all target columns in one call. If you already have
3257
+ * a starting index and count, use {@link FWorksheet.showColumns} instead of calling this method for each column.
3258
+ *
3194
3259
  * @param {FRange} column - The range to unhide, if hidden
3195
3260
  * @returns {FWorksheet} This sheet, for chaining
3196
3261
  * @example
@@ -3218,6 +3283,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3218
3283
  }
3219
3284
  /**
3220
3285
  * Show one or more consecutive columns starting at the given index. Use 0-index for this method
3286
+ *
3287
+ * For multiple consecutive columns, pass the full `numColumns` in one call instead of looping
3288
+ * with the default count of one.
3289
+ *
3221
3290
  * @param {number} columnIndex - The starting index of the columns to unhide
3222
3291
  * @param {number} [numColumns] - The number of columns to unhide
3223
3292
  * @returns {FWorksheet} This sheet, for chaining
@@ -3250,6 +3319,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3250
3319
  }
3251
3320
  /**
3252
3321
  * Sets the width of the given column in pixels.
3322
+ *
3323
+ * For the same width across consecutive columns, prefer {@link FWorksheet.setColumnWidths} with the
3324
+ * full column count instead of calling this method for each column.
3325
+ *
3253
3326
  * @param {number} columnPosition - The position of the given column to set
3254
3327
  * @param {number} width - The width in pixels to set it to
3255
3328
  * @returns {FWorksheet} This sheet, for chaining
@@ -4345,7 +4418,7 @@ let FRangePermission = class FRangePermission extends FBase {
4345
4418
  }
4346
4419
  collaborators.push({
4347
4420
  id: existingCollaborator.id,
4348
- role: UnitRole.Editor,
4421
+ role: UnitRole$1.Editor,
4349
4422
  subject: existingCollaborator.subject
4350
4423
  });
4351
4424
  });
@@ -4689,6 +4762,9 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4689
4762
  /**
4690
4763
  * Return first cell style in this range.
4691
4764
  *
4765
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
4766
+ * {@link FRange.getCellStyles} once instead of calling this method for each cell.
4767
+ *
4692
4768
  * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
4693
4769
  * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
4694
4770
  * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
@@ -4740,6 +4816,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4740
4816
  }
4741
4817
  /**
4742
4818
  * Returns the raw value of the top-left cell in the range. Empty cells return `null`.
4819
+ *
4820
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
4821
+ * {@link FRange.getRawValues} once instead of calling this method for each cell.
4822
+ *
4743
4823
  * @returns {Nullable<CellValue>} The raw value of the cell. Returns `null` if the cell is empty.
4744
4824
  * @example
4745
4825
  * ```ts
@@ -4764,6 +4844,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4764
4844
  }
4765
4845
  /**
4766
4846
  * Returns the displayed value of the top-left cell in the range. The value is a String. Empty cells return an empty string.
4847
+ *
4848
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
4849
+ * {@link FRange.getDisplayValues} once instead of calling this method for each cell.
4850
+ *
4767
4851
  * @returns {string} The displayed value of the cell. Returns an empty string if the cell is empty.
4768
4852
  * @example
4769
4853
  * ```ts
@@ -4917,6 +5001,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4917
5001
  }
4918
5002
  /**
4919
5003
  * Return first cell model data in this range
5004
+ *
5005
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5006
+ * {@link FRange.getCellDataGrid} once instead of calling this method for each cell.
5007
+ *
4920
5008
  * @returns {ICellData | null} The cell model data
4921
5009
  * @example
4922
5010
  * ```ts
@@ -5038,6 +5126,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5038
5126
  }
5039
5127
  /**
5040
5128
  * Returns the formula (A1 notation) of the top-left cell in the range, or an empty string if the cell is empty or doesn't contain a formula.
5129
+ *
5130
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5131
+ * {@link FRange.getFormulas} once instead of calling this method for each cell.
5132
+ *
5041
5133
  * @returns {string} The formula for the cell.
5042
5134
  * @example
5043
5135
  * ```ts
@@ -5080,6 +5172,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5080
5172
  }
5081
5173
  /**
5082
5174
  * Gets whether text wrapping is enabled for top-left cell in the range.
5175
+ *
5176
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5177
+ * {@link FRange.getWraps} once instead of calling this method for each cell.
5178
+ *
5083
5179
  * @returns {boolean} whether text wrapping is enabled for the cell.
5084
5180
  * @example
5085
5181
  * ```ts
@@ -5140,6 +5236,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5140
5236
  /**
5141
5237
  * Returns the horizontal alignment of the top-left cell as `left`, `center`, or `normal` (right alignment).
5142
5238
  * Default and other core alignment values return `general`, which is not accepted by `setHorizontalAlignment()`.
5239
+ *
5240
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5241
+ * {@link FRange.getHorizontalAlignments} once instead of calling this method for each cell.
5242
+ *
5143
5243
  * @returns {string} The horizontal alignment of the text in the cell.
5144
5244
  * @example
5145
5245
  * ```ts
@@ -5173,6 +5273,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5173
5273
  /**
5174
5274
  * Returns `top`, `middle`, or `bottom` for the top-left cell; unspecified alignment returns `general`.
5175
5275
  * `general` is a getter result and is not accepted by `setVerticalAlignment()`.
5276
+ *
5277
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5278
+ * {@link FRange.getVerticalAlignments} once instead of calling this method for each cell.
5279
+ *
5176
5280
  * @returns {string} The vertical alignment of the text in the cell.
5177
5281
  * @example
5178
5282
  * ```ts
@@ -5203,7 +5307,12 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5203
5307
  return this._worksheet.getRange(this._range).getVerticalAlignments().map((row) => row.map((alignment) => transformCoreVerticalAlignment(alignment)));
5204
5308
  }
5205
5309
  /**
5206
- * Set custom meta data for first cell in current range.
5310
+ * Set the same custom metadata for every cell in the current range.
5311
+ *
5312
+ * For the same metadata across multiple cells, call this method once on the entire target range.
5313
+ * For different metadata per cell, prefer {@link FRange.setCustomMetaDatas} with a two-dimensional
5314
+ * array matching the range dimensions instead of calling this method for each cell.
5315
+ *
5207
5316
  * @param {CustomData} data The custom meta data
5208
5317
  * @returns {FRange} This range, for chaining
5209
5318
  * @example
@@ -5257,6 +5366,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5257
5366
  }
5258
5367
  /**
5259
5368
  * Returns the custom meta data for the cell at the start of this range.
5369
+ *
5370
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5371
+ * {@link FRange.getCustomMetaDatas} once instead of calling this method for each cell.
5372
+ *
5260
5373
  * @returns {CustomData | null} The custom meta data
5261
5374
  * @example
5262
5375
  * ```ts
@@ -5290,6 +5403,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5290
5403
  }
5291
5404
  /**
5292
5405
  * Sets basic border properties for the current range.
5406
+ *
5407
+ * For borders on multiple cells, call this method once on the full target range. Border types such as
5408
+ * outer and inner are relative to that range, so applying them to each cell can produce different borders.
5409
+ *
5293
5410
  * @param {BorderType} type The type of border to apply
5294
5411
  * @param {BorderStyleTypes} style The border style
5295
5412
  * @param {string} [color] Optional border color in CSS notation
@@ -5318,6 +5435,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5318
5435
  }
5319
5436
  /**
5320
5437
  * Returns the background color of the top-left cell in the range.
5438
+ *
5439
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5440
+ * {@link FRange.getBackgrounds} once instead of calling this method for each cell.
5441
+ *
5321
5442
  * @returns {string} The color code of the background.
5322
5443
  * @example
5323
5444
  * ```ts
@@ -5353,6 +5474,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5353
5474
  }
5354
5475
  /**
5355
5476
  * Set background color for current range.
5477
+ *
5478
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5479
+ * and call this method once instead of calling it on each cell separately.
5480
+ *
5356
5481
  * @param {string} color The background color
5357
5482
  * @returns {FRange} This range, for chaining
5358
5483
  * @example
@@ -5378,6 +5503,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5378
5503
  }
5379
5504
  /**
5380
5505
  * Set background color for current range.
5506
+ *
5507
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5508
+ * and call this method once instead of calling it on each cell separately.
5509
+ *
5381
5510
  * @param {string} color The background color
5382
5511
  * @returns {FRange} This range, for chaining
5383
5512
  * @example
@@ -5395,6 +5524,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5395
5524
  }
5396
5525
  /**
5397
5526
  * Set rotation for text in current range.
5527
+ *
5528
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5529
+ * and call this method once instead of calling it on each cell separately.
5530
+ *
5398
5531
  * @param {number} rotation - The rotation angle in degrees
5399
5532
  * @returns This range, for chaining
5400
5533
  * @example
@@ -5418,6 +5551,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5418
5551
  /**
5419
5552
  * Sets the value or specified cell properties for every cell in this range.
5420
5553
  *
5554
+ * For the same value or cell-data update across multiple cells, call this method once on the entire
5555
+ * target range. For different values or updates per cell, prefer {@link FRange.setValues} with a
5556
+ * two-dimensional array or sparse matrix instead of calling this method for each cell.
5557
+ *
5421
5558
  * There are two input modes:
5422
5559
  *
5423
5560
  * - `CellValue` (`number`, `string`, or `boolean`): replaces the cell content. A string starting
@@ -5483,6 +5620,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5483
5620
  /**
5484
5621
  * Sets the value or specified cell properties of the top-left cell in this range.
5485
5622
  * Uses the same scalar parsing and cell-data update rules as {@link FRange.setValue}.
5623
+ *
5624
+ * For multiple cells, prefer {@link FRange.setValues} on the target range with a two-dimensional array
5625
+ * or sparse matrix. To apply the same value to the entire range, use {@link FRange.setValue} once.
5626
+ *
5486
5627
  * @param {CellValue | ICellData} value The scalar content or cell-data update to apply to the top-left cell only.
5487
5628
  * @returns {FRange} This range, for chaining
5488
5629
  * @example
@@ -5515,6 +5656,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5515
5656
  }
5516
5657
  /**
5517
5658
  * Set the rich text value for the cell at the start of this range.
5659
+ *
5660
+ * For multiple cells, prefer {@link FRange.setRichTextValues} on the target range with a two-dimensional
5661
+ * array matching its dimensions instead of calling this method for each cell.
5662
+ *
5518
5663
  * @param {RichTextValue | IDocumentData} value The rich text value
5519
5664
  * @returns {FRange} The range
5520
5665
  * @example
@@ -5590,6 +5735,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5590
5735
  * Set the cell wrap of the given range.
5591
5736
  * Pass `true` to set `WrapStrategy.WRAP`, or `false` to reset to `WrapStrategy.UNSPECIFIED`.
5592
5737
  * Use `setWrapStrategy()` to explicitly select clipping or overflow behavior.
5738
+ *
5739
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5740
+ * and call this method once instead of calling it on each cell separately.
5741
+ *
5593
5742
  * @param {boolean} isWrapEnabled Whether to enable wrap
5594
5743
  * @returns {FRange} this range, for chaining
5595
5744
  * @example
@@ -5613,6 +5762,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5613
5762
  }
5614
5763
  /**
5615
5764
  * Sets whether cells shrink their font size to fit the cell width.
5765
+ *
5766
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5767
+ * and call this method once instead of calling it on each cell separately.
5768
+ *
5616
5769
  * @param {boolean} enabled Whether to enable shrink-to-fit for this range.
5617
5770
  * @returns {FRange} This range, for chaining.
5618
5771
  * @example
@@ -5631,6 +5784,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5631
5784
  }
5632
5785
  /**
5633
5786
  * Sets the text wrapping strategy for the cells in the range.
5787
+ *
5788
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5789
+ * and call this method once instead of calling it on each cell separately.
5790
+ *
5634
5791
  * @param {WrapStrategy} strategy The text wrapping strategy
5635
5792
  * @returns {FRange} this range, for chaining
5636
5793
  * @example
@@ -5654,6 +5811,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5654
5811
  }
5655
5812
  /**
5656
5813
  * Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
5814
+ *
5815
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5816
+ * and call this method once instead of calling it on each cell separately.
5817
+ *
5657
5818
  * @param {FVerticalAlignment} alignment The vertical alignment
5658
5819
  * @returns {FRange} this range, for chaining
5659
5820
  * @example
@@ -5677,6 +5838,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5677
5838
  /**
5678
5839
  * Sets the horizontal alignment for the range using `left`, `center`, or `normal`.
5679
5840
  * These parameter names follow Google Apps Script. In Univer, `normal` means right alignment; `right` is not accepted.
5841
+ *
5842
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5843
+ * and call this method once instead of calling it on each cell separately.
5844
+ *
5680
5845
  * @param {FHorizontalAlignment} alignment The horizontal alignment: `left`, `center`, or `normal` (right alignment).
5681
5846
  * @returns {FRange} this range, for chaining
5682
5847
  * @example
@@ -5701,6 +5866,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5701
5866
  * Sets cell values or specified cell properties using an array or a sparse matrix.
5702
5867
  * Each entry follows the scalar parsing and cell-data update rules of {@link FRange.setValue}.
5703
5868
  *
5869
+ * For multiple cells, pass all values or cell-data updates in one call instead of calling this method
5870
+ * on individual cell ranges. Use a matching two-dimensional array for a rectangle, or a sparse matrix
5871
+ * with absolute worksheet coordinates for non-contiguous cells.
5872
+ *
5704
5873
  * A two-dimensional array is relative to this range's top-left cell and must match its dimensions.
5705
5874
  * A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries
5706
5875
  * are updated; matrix coordinates are not offset by or clipped to this range.
@@ -5736,6 +5905,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5736
5905
  }
5737
5906
  /**
5738
5907
  * Sets the font weight for the given range (normal/bold),
5908
+ *
5909
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5910
+ * and call this method once instead of calling it on each cell separately.
5911
+ *
5739
5912
  * @param {FontWeight|null} fontWeight The font weight, either 'normal' or 'bold'; a null value resets the font weight.
5740
5913
  * @returns {FRange} This range, for chaining
5741
5914
  * @example
@@ -5768,6 +5941,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5768
5941
  }
5769
5942
  /**
5770
5943
  * Sets the font style for the given range ('italic' or 'normal').
5944
+ *
5945
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5946
+ * and call this method once instead of calling it on each cell separately.
5947
+ *
5771
5948
  * @param {FontStyle|null} fontStyle The font style, either 'italic' or 'normal'; a null value resets the font style.
5772
5949
  * @returns {FRange} This range, for chaining
5773
5950
  * @example
@@ -5800,6 +5977,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5800
5977
  }
5801
5978
  /**
5802
5979
  * Sets the font line style of the given range ('underline', 'line-through', or 'none').
5980
+ *
5981
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5982
+ * and call this method once instead of calling it on each cell separately.
5983
+ *
5803
5984
  * @param {FontLine|null} fontLine The font line style, either 'underline', 'line-through', or 'none'; a null value resets the font line style.
5804
5985
  * @returns {FRange} This range, for chaining
5805
5986
  * @example
@@ -5861,6 +6042,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5861
6042
  }
5862
6043
  /**
5863
6044
  * Sets the font family, such as "Arial" or "Helvetica".
6045
+ *
6046
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
6047
+ * and call this method once instead of calling it on each cell separately.
6048
+ *
5864
6049
  * @param {string|null} fontFamily The font family to set; a null value resets the font family.
5865
6050
  * @returns {FRange} This range, for chaining
5866
6051
  * @example
@@ -5888,6 +6073,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5888
6073
  }
5889
6074
  /**
5890
6075
  * Sets the font size, with the size being the point size to use.
6076
+ *
6077
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
6078
+ * and call this method once instead of calling it on each cell separately.
6079
+ *
5891
6080
  * @param {number|null} size A font size in point size. A null value resets the font size.
5892
6081
  * @returns {FRange} This range, for chaining
5893
6082
  * @example
@@ -5915,6 +6104,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5915
6104
  }
5916
6105
  /**
5917
6106
  * Sets the font color in CSS notation (such as '#ffffff' or 'white').
6107
+ *
6108
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
6109
+ * and call this method once instead of calling it on each cell separately.
6110
+ *
5918
6111
  * @param {string|null} color The font color in CSS notation (such as '#ffffff' or 'white'); a null value resets the color.
5919
6112
  * @returns {FRange} This range, for chaining
5920
6113
  * @example
@@ -6334,6 +6527,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6334
6527
  /**
6335
6528
  * Clears the range content and formatting, or only one of them as specified by the options.
6336
6529
  * Both content and formatting are cleared when both flags are true or both are false.
6530
+ *
6531
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
6532
+ * method once instead of clearing each cell separately.
6533
+ *
6337
6534
  * @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
6338
6535
  * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. Effective only when `formatOnly` is false. Defaults to false.
6339
6536
  * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
@@ -6365,6 +6562,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6365
6562
  }
6366
6563
  /**
6367
6564
  * Clears content of the range, while preserving formatting information.
6565
+ *
6566
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
6567
+ * method once instead of clearing each cell separately.
6568
+ *
6368
6569
  * @returns {FRange} This range, for chaining.
6369
6570
  * @example
6370
6571
  * ```typescript
@@ -6387,6 +6588,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6387
6588
  }
6388
6589
  /**
6389
6590
  * Clears formatting information of the range, while preserving contents.
6591
+ *
6592
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
6593
+ * method once instead of clearing each cell separately.
6594
+ *
6390
6595
  * @returns {FRange} This range, for chaining.
6391
6596
  * @example
6392
6597
  * ```typescript
@@ -6670,6 +6875,11 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6670
6875
  }
6671
6876
  /**
6672
6877
  * Updates the formula for this range. The given formula must be in A1 notation.
6878
+ *
6879
+ * For the same formula string across multiple cells, call this method once on the entire target range.
6880
+ * For different formulas per cell, prefer {@link FRange.setFormulas} with a two-dimensional array
6881
+ * matching the range dimensions instead of calling this method for each cell.
6882
+ *
6673
6883
  * @param {string} formula - A string representing the formula to set for the cell.
6674
6884
  * @returns {FRange} This range instance for chaining.
6675
6885
  * @example
@@ -8530,7 +8740,7 @@ var FSheetsEnumMixin = class extends FEnum {
8530
8740
  return SplitDelimiterEnum;
8531
8741
  }
8532
8742
  get UnitRole() {
8533
- return UnitRole$1;
8743
+ return UnitRole;
8534
8744
  }
8535
8745
  get WorkbookPermissionPoint() {
8536
8746
  return WorkbookPermissionPoint;