@univerjs/sheets 1.3.1 → 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.
Files changed (92) hide show
  1. package/README.md +21 -5
  2. package/lib/cjs/facade.js +246 -57
  3. package/lib/cjs/index.js +1143 -21533
  4. package/lib/cjs/locale/ar-SA.js +1 -2
  5. package/lib/cjs/locale/ca-ES.js +1 -2
  6. package/lib/cjs/locale/de-DE.js +1 -2
  7. package/lib/cjs/locale/en-US.js +1 -2
  8. package/lib/cjs/locale/es-ES.js +1 -2
  9. package/lib/cjs/locale/fa-IR.js +1 -2
  10. package/lib/cjs/locale/fr-FR.js +1 -2
  11. package/lib/cjs/locale/id-ID.js +1 -2
  12. package/lib/cjs/locale/it-IT.js +1 -2
  13. package/lib/cjs/locale/ja-JP.js +1 -2
  14. package/lib/cjs/locale/ko-KR.js +1 -2
  15. package/lib/cjs/locale/pl-PL.js +1 -2
  16. package/lib/cjs/locale/pt-BR.js +1 -2
  17. package/lib/cjs/locale/ru-RU.js +1 -2
  18. package/lib/cjs/locale/sk-SK.js +1 -2
  19. package/lib/cjs/locale/vi-VN.js +1 -2
  20. package/lib/cjs/locale/zh-CN.js +1 -2
  21. package/lib/cjs/locale/zh-HK.js +1 -2
  22. package/lib/cjs/locale/zh-TW.js +1 -2
  23. package/lib/cjs/plugin-tI5Deb_a.js +22421 -0
  24. package/lib/cjs/worker.js +9 -0
  25. package/lib/es/facade.js +256 -67
  26. package/lib/es/index.js +719 -21110
  27. package/lib/es/locale/ar-SA.js +1 -2
  28. package/lib/es/locale/ca-ES.js +1 -2
  29. package/lib/es/locale/de-DE.js +1 -2
  30. package/lib/es/locale/en-US.js +1 -2
  31. package/lib/es/locale/es-ES.js +1 -2
  32. package/lib/es/locale/fa-IR.js +1 -2
  33. package/lib/es/locale/fr-FR.js +1 -2
  34. package/lib/es/locale/id-ID.js +1 -2
  35. package/lib/es/locale/it-IT.js +1 -2
  36. package/lib/es/locale/ja-JP.js +1 -2
  37. package/lib/es/locale/ko-KR.js +1 -2
  38. package/lib/es/locale/pl-PL.js +1 -2
  39. package/lib/es/locale/pt-BR.js +1 -2
  40. package/lib/es/locale/ru-RU.js +1 -2
  41. package/lib/es/locale/sk-SK.js +1 -2
  42. package/lib/es/locale/vi-VN.js +1 -2
  43. package/lib/es/locale/zh-CN.js +1 -2
  44. package/lib/es/locale/zh-HK.js +1 -2
  45. package/lib/es/locale/zh-TW.js +1 -2
  46. package/lib/es/plugin-Bmc8YRpc.js +20148 -0
  47. package/lib/es/worker.js +3 -0
  48. package/lib/facade.js +256 -67
  49. package/lib/index.js +719 -21110
  50. package/lib/locale/ar-SA.js +1 -2
  51. package/lib/locale/ca-ES.js +1 -2
  52. package/lib/locale/de-DE.js +1 -2
  53. package/lib/locale/en-US.js +1 -2
  54. package/lib/locale/es-ES.js +1 -2
  55. package/lib/locale/fa-IR.js +1 -2
  56. package/lib/locale/fr-FR.js +1 -2
  57. package/lib/locale/id-ID.js +1 -2
  58. package/lib/locale/it-IT.js +1 -2
  59. package/lib/locale/ja-JP.js +1 -2
  60. package/lib/locale/ko-KR.js +1 -2
  61. package/lib/locale/pl-PL.js +1 -2
  62. package/lib/locale/pt-BR.js +1 -2
  63. package/lib/locale/ru-RU.js +1 -2
  64. package/lib/locale/sk-SK.js +1 -2
  65. package/lib/locale/vi-VN.js +1 -2
  66. package/lib/locale/zh-CN.js +1 -2
  67. package/lib/locale/zh-HK.js +1 -2
  68. package/lib/locale/zh-TW.js +1 -2
  69. package/lib/plugin-Bmc8YRpc.js +20148 -0
  70. package/lib/types/commands/commands/move-rows-cols.command.d.ts +2 -2
  71. package/lib/types/commands/commands/reorder-range.command.d.ts +1 -1
  72. package/lib/types/commands/commands/set-border.command.d.ts +1 -1
  73. package/lib/types/commands/mutations/numfmt.mutation.d.ts +1 -1
  74. package/lib/types/controllers/permission/sheet-permission-init.controller.d.ts +3 -2
  75. package/lib/types/facade/f-range.d.ts +154 -7
  76. package/lib/types/facade/f-worksheet.d.ts +76 -2
  77. package/lib/types/index.d.ts +1 -1
  78. package/lib/types/models/range-protection.cache.d.ts +9 -9
  79. package/lib/types/models/range-theme-model.d.ts +1 -1
  80. package/lib/types/services/auto-fill/auto-fill.service.d.ts +1 -1
  81. package/lib/types/services/auto-fill/tools.d.ts +6 -6
  82. package/lib/types/services/exclusive-range/exclusive-range.service.d.ts +1 -1
  83. package/lib/types/services/numfmt/type.d.ts +1 -1
  84. package/lib/types/services/permission/range-permission/range-protection.ref-range.d.ts +13 -4
  85. package/lib/types/services/ref-range/util.d.ts +31 -16
  86. package/lib/types/services/selections/ref-selections.service.d.ts +1 -1
  87. package/lib/types/services/sheet-interceptor/interceptor-const.d.ts +2 -1
  88. package/lib/types/worker.d.ts +16 -0
  89. package/lib/umd/facade.js +1 -1
  90. package/lib/umd/index.js +2 -2
  91. package/lib/worker.js +3 -0
  92. package/package.json +17 -12
package/lib/cjs/facade.js CHANGED
@@ -5,7 +5,7 @@ let _univerjs_sheets = require("@univerjs/sheets");
5
5
  let _univerjs_engine_formula = require("@univerjs/engine-formula");
6
6
  let _univerjs_protocol = require("@univerjs/protocol");
7
7
 
8
- //#region src/facade/const.ts
8
+ // src/facade/const.ts
9
9
  /**
10
10
  * Copyright 2023-present DreamNum Co., Ltd.
11
11
  *
@@ -23,8 +23,7 @@ let _univerjs_protocol = require("@univerjs/protocol");
23
23
  */
24
24
  const SHEETS_CUSTOM_FIELD_WARNING_MESSAGE = "[Facade]: The sheets custom field is not recommended for external use. Use it at your own risk.";
25
25
 
26
- //#endregion
27
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/typeof.js
26
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/typeof.js
28
27
  function _typeof(o) {
29
28
  "@babel/helpers - typeof";
30
29
  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -34,28 +33,25 @@ function _typeof(o) {
34
33
  }, _typeof(o);
35
34
  }
36
35
 
37
- //#endregion
38
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPrimitive.js
39
- function toPrimitive(t, r) {
36
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/toPrimitive.js
37
+ function toPrimitive(t, e) {
40
38
  if ("object" != _typeof(t) || !t) return t;
41
- var e = t[Symbol.toPrimitive];
42
- if (void 0 !== e) {
43
- var i = e.call(t, r || "default");
39
+ var r;
40
+ if ("undefined" != typeof Symbol && void 0 !== (r = t[Symbol.toPrimitive])) {
41
+ var i = r.call(t, e || "default");
44
42
  if ("object" != _typeof(i)) return i;
45
43
  throw new TypeError("@@toPrimitive must return a primitive value.");
46
44
  }
47
- return ("string" === r ? String : Number)(t);
45
+ return ("string" === e ? String : Number)(t);
48
46
  }
49
47
 
50
- //#endregion
51
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPropertyKey.js
48
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/toPropertyKey.js
52
49
  function toPropertyKey(t) {
53
50
  var i = toPrimitive(t, "string");
54
51
  return "symbol" == _typeof(i) ? i : i + "";
55
52
  }
56
53
 
57
- //#endregion
58
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/defineProperty.js
54
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/defineProperty.js
59
55
  function _defineProperty(e, r, t) {
60
56
  return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
61
57
  value: t,
@@ -65,16 +61,14 @@ function _defineProperty(e, r, t) {
65
61
  }) : e[r] = t, e;
66
62
  }
67
63
 
68
- //#endregion
69
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateParam.js
64
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/decorateParam.js
70
65
  function __decorateParam(paramIndex, decorator) {
71
66
  return function(target, key) {
72
67
  decorator(target, key, paramIndex);
73
68
  };
74
69
  }
75
70
 
76
- //#endregion
77
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
71
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/decorate.js
78
72
  function __decorate(decorators, target, key, desc) {
79
73
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
80
74
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -82,8 +76,7 @@ function __decorate(decorators, target, key, desc) {
82
76
  return c > 3 && r && Object.defineProperty(target, key, r), r;
83
77
  }
84
78
 
85
- //#endregion
86
- //#region src/facade/f-defined-name.ts
79
+ // src/facade/f-defined-name.ts
87
80
  /**
88
81
  * Get defined name field name
89
82
  * @param {string} unitId - unit id
@@ -583,8 +576,7 @@ FDefinedName = __decorate([
583
576
  __decorateParam(9, _univerjs_engine_formula.IDefinedNamesService)
584
577
  ], FDefinedName);
585
578
 
586
- //#endregion
587
- //#region src/facade/f-selection.ts
579
+ // src/facade/f-selection.ts
588
580
  var _FSelection;
589
581
  let FSelection = _FSelection = class FSelection {
590
582
  constructor(_workbook, _worksheet, _selections, _injector) {
@@ -756,8 +748,7 @@ let FSelection = _FSelection = class FSelection {
756
748
  };
757
749
  FSelection = _FSelection = __decorate([__decorateParam(3, (0, _univerjs_core.Inject)(_univerjs_core.Injector))], FSelection);
758
750
 
759
- //#endregion
760
- //#region src/facade/permission/permission-types.ts
751
+ // src/facade/permission/permission-types.ts
761
752
  /**
762
753
  * Copyright 2023-present DreamNum Co., Ltd.
763
754
  *
@@ -896,8 +887,7 @@ let RangePermissionPoint = /* @__PURE__ */ function(RangePermissionPoint) {
896
887
  return RangePermissionPoint;
897
888
  }({});
898
889
 
899
- //#endregion
900
- //#region src/facade/permission/permission-point-map.ts
890
+ // src/facade/permission/permission-point-map.ts
901
891
  /**
902
892
  * Mapping table from Workbook permission point enum to class constructors
903
893
  */
@@ -960,8 +950,7 @@ const RANGE_PERMISSION_POINT_MAP = {
960
950
  ["RangeDeleteProtection"]: _univerjs_sheets.RangeProtectionPermissionDeleteProtectionPoint
961
951
  };
962
952
 
963
- //#endregion
964
- //#region src/facade/permission/util.ts
953
+ // src/facade/permission/util.ts
965
954
  function determineViewState(allowViewByOthers) {
966
955
  if (allowViewByOthers === false) return _univerjs_sheets.ViewStateEnum.NoOneElseCanView;
967
956
  return _univerjs_sheets.ViewStateEnum.OthersCanView;
@@ -1040,8 +1029,7 @@ async function getListRangeProtectionRules(injector, unitId, subUnitId, options)
1040
1029
  }))).map(({ id, permissionId, ranges, options }) => injector.createInstance(FRangeProtectionRule, unitId, subUnitId, id, permissionId, ranges, options));
1041
1030
  }
1042
1031
 
1043
- //#endregion
1044
- //#region src/facade/permission/f-range-protection-rule.ts
1032
+ // src/facade/permission/f-range-protection-rule.ts
1045
1033
  let FRangeProtectionRule = class FRangeProtectionRule {
1046
1034
  constructor(_unitId, _subUnitId, _ruleId, _permissionId, _ranges, _options, _injector, _permissionService, _authzIoService, _commandService, _rangeProtectionRuleModel) {
1047
1035
  this._unitId = _unitId;
@@ -1334,8 +1322,7 @@ FRangeProtectionRule = __decorate([
1334
1322
  __decorateParam(10, (0, _univerjs_core.Inject)(_univerjs_sheets.RangeProtectionRuleModel))
1335
1323
  ], FRangeProtectionRule);
1336
1324
 
1337
- //#endregion
1338
- //#region src/facade/permission/f-worksheet-permission.ts
1325
+ // src/facade/permission/f-worksheet-permission.ts
1339
1326
  let FWorksheetPermission = class FWorksheetPermission extends _univerjs_core_facade.FBase {
1340
1327
  constructor(_worksheet, _injector, _permissionService, _authzIoService, _commandService, _rangeProtectionRuleModel, _worksheetProtectionPointModel, _worksheetProtectionRuleModel) {
1341
1328
  super();
@@ -1929,8 +1916,7 @@ FWorksheetPermission = __decorate([
1929
1916
  __decorateParam(7, (0, _univerjs_core.Inject)(_univerjs_sheets.WorksheetProtectionRuleModel))
1930
1917
  ], FWorksheetPermission);
1931
1918
 
1932
- //#endregion
1933
- //#region src/facade/utils.ts
1919
+ // src/facade/utils.ts
1934
1920
  /**
1935
1921
  * Transform the Facade API horizontal alignment to the Univer Core horizontal alignment.
1936
1922
  * @param {FHorizontalAlignment} value - The Facade API horizontal alignment.
@@ -2014,8 +2000,7 @@ function covertToColRange(range, worksheet) {
2014
2000
  };
2015
2001
  }
2016
2002
 
2017
- //#endregion
2018
- //#region src/facade/f-worksheet.ts
2003
+ // src/facade/f-worksheet.ts
2019
2004
  var _FWorksheet;
2020
2005
  function assertValidRowInsertion(methodName, rowIndex, rowCount, howMany) {
2021
2006
  if (!Number.isInteger(howMany) || howMany <= 0) throw new RangeError(`${methodName}(): row count ${howMany} must be a positive integer.`);
@@ -2293,7 +2278,6 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2293
2278
  ...parsedRange,
2294
2279
  unitId: this._workbook.getUnitId(),
2295
2280
  sheetId: sheet.getSheetId(),
2296
- rangeType: _univerjs_core.RANGE_TYPE.NORMAL,
2297
2281
  startRow: parsedRange.rangeType === _univerjs_core.RANGE_TYPE.COLUMN ? 0 : parsedRange.startRow,
2298
2282
  endRow: parsedRange.rangeType === _univerjs_core.RANGE_TYPE.COLUMN ? sheet.getMaxRows() - 1 : parsedRange.endRow,
2299
2283
  startColumn: parsedRange.rangeType === _univerjs_core.RANGE_TYPE.ROW ? 0 : parsedRange.startColumn,
@@ -2342,6 +2326,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2342
2326
  }
2343
2327
  /**
2344
2328
  * Inserts a row after the given row position.
2329
+ *
2330
+ * To insert multiple rows, prefer {@link FWorksheet.insertRowsAfter} with the full count
2331
+ * instead of repeatedly calling this method.
2332
+ *
2345
2333
  * @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`.
2346
2334
  * @returns {FWorksheet} This sheet, for chaining.
2347
2335
  * @example
@@ -2359,6 +2347,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2359
2347
  }
2360
2348
  /**
2361
2349
  * Inserts a row before the given row position.
2350
+ *
2351
+ * To insert multiple rows, prefer {@link FWorksheet.insertRowsBefore} with the full count
2352
+ * instead of repeatedly calling this method.
2353
+ *
2362
2354
  * @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`.
2363
2355
  * @returns {FWorksheet} This sheet, for chaining.
2364
2356
  * @example
@@ -2376,6 +2368,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2376
2368
  }
2377
2369
  /**
2378
2370
  * Inserts one or more consecutive blank rows in a sheet starting at the specified location.
2371
+ *
2372
+ * For multiple consecutive rows, pass the full `numRows` in one call instead of looping
2373
+ * with the default count of one.
2374
+ *
2379
2375
  * @param {number} rowIndex - The existing row before which rows are inserted. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
2380
2376
  * @param {number} [numRows] - The positive number of rows to insert.
2381
2377
  * @returns {FWorksheet} This sheet, for chaining.
@@ -2473,6 +2469,11 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2473
2469
  }
2474
2470
  /**
2475
2471
  * Deletes the row at the given row position.
2472
+ *
2473
+ * For consecutive rows, prefer {@link FWorksheet.deleteRows} with the full count. For
2474
+ * non-contiguous rows, use {@link FWorksheet.deleteRowsByPoints} so shifting indices are handled
2475
+ * without a manual loop over this method.
2476
+ *
2476
2477
  * @param {number} rowPosition - The position of the row, starting at 0 for the first row.
2477
2478
  * @returns {FWorksheet} This sheet, for chaining.
2478
2479
  * @example
@@ -2574,6 +2575,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2574
2575
  }
2575
2576
  /**
2576
2577
  * Hides the rows in the given range.
2578
+ *
2579
+ * For multiple rows, pass an FRange spanning all target rows in one call. If you already have
2580
+ * a starting index and count, use {@link FWorksheet.hideRows} instead of calling this method for each row.
2581
+ *
2577
2582
  * @param {FRange} row - The row range to hide.
2578
2583
  * @returns {FWorksheet} This sheet, for chaining.
2579
2584
  * @example
@@ -2601,6 +2606,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2601
2606
  }
2602
2607
  /**
2603
2608
  * Hides one or more consecutive rows starting at the given index. Use 0-index for this method
2609
+ *
2610
+ * For multiple consecutive rows, pass the full `numRow` in one call instead of looping
2611
+ * with the default count of one.
2612
+ *
2604
2613
  * @param {number} rowIndex - The starting index of the rows to hide
2605
2614
  * @param {number} [numRow] - The number of rows to hide
2606
2615
  * @returns {FWorksheet} This sheet, for chaining.
@@ -2633,6 +2642,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2633
2642
  }
2634
2643
  /**
2635
2644
  * Make the row in the given range visible.
2645
+ *
2646
+ * For multiple rows, pass an FRange spanning all target rows in one call. If you already have
2647
+ * a starting index and count, use {@link FWorksheet.showRows} instead of calling this method for each row.
2648
+ *
2636
2649
  * @param {FRange} row - The range to unhide, if hidden.
2637
2650
  * @returns {FWorksheet} This sheet, for chaining.
2638
2651
  * @example
@@ -2660,6 +2673,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2660
2673
  }
2661
2674
  /**
2662
2675
  * Unhides one or more consecutive rows starting at the given zero-based index.
2676
+ *
2677
+ * For multiple consecutive rows, pass the full `numRows` in one call instead of looping
2678
+ * with the default count of one.
2679
+ *
2663
2680
  * @param {number} rowIndex - The starting index of the rows
2664
2681
  * @param {number} [numRows] - The number of rows
2665
2682
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -2692,6 +2709,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2692
2709
  }
2693
2710
  /**
2694
2711
  * 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).
2712
+ *
2713
+ * For the same height across consecutive rows, prefer {@link FWorksheet.setRowHeights} with the full
2714
+ * row count instead of calling this method for each row.
2715
+ *
2695
2716
  * @param {number} rowPosition - The row position to change.
2696
2717
  * @param {number} height - The height in pixels to set it to.
2697
2718
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -2919,6 +2940,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2919
2940
  }
2920
2941
  /**
2921
2942
  * Inserts a column after the given column position.
2943
+ *
2944
+ * To insert multiple columns, prefer {@link FWorksheet.insertColumnsAfter} with the full count
2945
+ * instead of repeatedly calling this method.
2946
+ *
2922
2947
  * @param {number} afterPosition - The column after which the new column should be added, starting at 0 for the first column
2923
2948
  * @returns {FWorksheet} This worksheet instance for chaining
2924
2949
  * @example
@@ -2936,6 +2961,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2936
2961
  }
2937
2962
  /**
2938
2963
  * Inserts a column before the given column position.
2964
+ *
2965
+ * To insert multiple columns, prefer {@link FWorksheet.insertColumnsBefore} with the full count
2966
+ * instead of repeatedly calling this method.
2967
+ *
2939
2968
  * @param {number} beforePosition - The column before which the new column should be added, starting at 0 for the first column
2940
2969
  * @returns {FWorksheet} This worksheet instance for chaining
2941
2970
  * @example
@@ -2953,6 +2982,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
2953
2982
  }
2954
2983
  /**
2955
2984
  * Inserts one or more consecutive blank columns in a sheet starting at the specified location.
2985
+ *
2986
+ * For multiple consecutive columns, pass the full `numColumns` in one call instead of looping
2987
+ * with the default count of one.
2988
+ *
2956
2989
  * @param {number} columnIndex - The index indicating where to insert a column, starting at 0 for the first column
2957
2990
  * @param {number} [numColumns] - The number of columns to insert
2958
2991
  * @returns {FWorksheet} This sheet, for chaining
@@ -3047,6 +3080,11 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
3047
3080
  }
3048
3081
  /**
3049
3082
  * Deletes the column at the given column position.
3083
+ *
3084
+ * For consecutive columns, prefer {@link FWorksheet.deleteColumns} with the full count. For
3085
+ * non-contiguous columns, use {@link FWorksheet.deleteColumnsByPoints} so shifting indices are handled
3086
+ * without a manual loop over this method.
3087
+ *
3050
3088
  * @param {number} columnPosition - The position of the column, starting at 0 for the first column
3051
3089
  * @returns {FWorksheet} This sheet, for chaining
3052
3090
  * @example
@@ -3148,6 +3186,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
3148
3186
  }
3149
3187
  /**
3150
3188
  * Hides the column or columns in the given range.
3189
+ *
3190
+ * For multiple columns, pass an FRange spanning all target columns in one call. If you already have
3191
+ * a starting index and count, use {@link FWorksheet.hideColumns} instead of calling this method for each column.
3192
+ *
3151
3193
  * @param {FRange} column - The column range to hide
3152
3194
  * @returns {FWorksheet} This sheet, for chaining
3153
3195
  * @example
@@ -3175,6 +3217,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
3175
3217
  }
3176
3218
  /**
3177
3219
  * Hides one or more consecutive columns starting at the given index. Use 0-index for this method
3220
+ *
3221
+ * For multiple consecutive columns, pass the full `numColumn` in one call instead of looping
3222
+ * with the default count of one.
3223
+ *
3178
3224
  * @param {number} columnIndex - The starting index of the columns to hide
3179
3225
  * @param {number} [numColumn] - The number of columns to hide
3180
3226
  * @returns {FWorksheet} This sheet, for chaining
@@ -3207,6 +3253,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
3207
3253
  }
3208
3254
  /**
3209
3255
  * Show the column in the given range.
3256
+ *
3257
+ * For multiple columns, pass an FRange spanning all target columns in one call. If you already have
3258
+ * a starting index and count, use {@link FWorksheet.showColumns} instead of calling this method for each column.
3259
+ *
3210
3260
  * @param {FRange} column - The range to unhide, if hidden
3211
3261
  * @returns {FWorksheet} This sheet, for chaining
3212
3262
  * @example
@@ -3234,6 +3284,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
3234
3284
  }
3235
3285
  /**
3236
3286
  * Show one or more consecutive columns starting at the given index. Use 0-index for this method
3287
+ *
3288
+ * For multiple consecutive columns, pass the full `numColumns` in one call instead of looping
3289
+ * with the default count of one.
3290
+ *
3237
3291
  * @param {number} columnIndex - The starting index of the columns to unhide
3238
3292
  * @param {number} [numColumns] - The number of columns to unhide
3239
3293
  * @returns {FWorksheet} This sheet, for chaining
@@ -3266,6 +3320,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends _univerjs_core_facade.FB
3266
3320
  }
3267
3321
  /**
3268
3322
  * Sets the width of the given column in pixels.
3323
+ *
3324
+ * For the same width across consecutive columns, prefer {@link FWorksheet.setColumnWidths} with the
3325
+ * full column count instead of calling this method for each column.
3326
+ *
3269
3327
  * @param {number} columnPosition - The position of the given column to set
3270
3328
  * @param {number} width - The width in pixels to set it to
3271
3329
  * @returns {FWorksheet} This sheet, for chaining
@@ -4291,8 +4349,7 @@ FWorksheet = _FWorksheet = __decorate([
4291
4349
  __decorateParam(6, _univerjs_core.ICommandService)
4292
4350
  ], FWorksheet);
4293
4351
 
4294
- //#endregion
4295
- //#region src/facade/permission/f-range-permission.ts
4352
+ // src/facade/permission/f-range-permission.ts
4296
4353
  let FRangePermission = class FRangePermission extends _univerjs_core_facade.FBase {
4297
4354
  constructor(_unitId, _subUnitId, _range, _worksheet, _injector, _authzIoService, _commandService, _rangeProtectionRuleModel) {
4298
4355
  super();
@@ -4447,8 +4504,7 @@ FRangePermission = __decorate([
4447
4504
  __decorateParam(7, (0, _univerjs_core.Inject)(_univerjs_sheets.RangeProtectionRuleModel))
4448
4505
  ], FRangePermission);
4449
4506
 
4450
- //#endregion
4451
- //#region src/facade/f-range.ts
4507
+ // src/facade/f-range.ts
4452
4508
  var _FRange;
4453
4509
  var _FRange2;
4454
4510
  let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialable {
@@ -4707,6 +4763,9 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
4707
4763
  /**
4708
4764
  * Return first cell style in this range.
4709
4765
  *
4766
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
4767
+ * {@link FRange.getCellStyles} once instead of calling this method for each cell.
4768
+ *
4710
4769
  * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
4711
4770
  * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
4712
4771
  * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
@@ -4758,6 +4817,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
4758
4817
  }
4759
4818
  /**
4760
4819
  * Returns the raw value of the top-left cell in the range. Empty cells return `null`.
4820
+ *
4821
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
4822
+ * {@link FRange.getRawValues} once instead of calling this method for each cell.
4823
+ *
4761
4824
  * @returns {Nullable<CellValue>} The raw value of the cell. Returns `null` if the cell is empty.
4762
4825
  * @example
4763
4826
  * ```ts
@@ -4782,6 +4845,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
4782
4845
  }
4783
4846
  /**
4784
4847
  * Returns the displayed value of the top-left cell in the range. The value is a String. Empty cells return an empty string.
4848
+ *
4849
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
4850
+ * {@link FRange.getDisplayValues} once instead of calling this method for each cell.
4851
+ *
4785
4852
  * @returns {string} The displayed value of the cell. Returns an empty string if the cell is empty.
4786
4853
  * @example
4787
4854
  * ```ts
@@ -4935,6 +5002,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
4935
5002
  }
4936
5003
  /**
4937
5004
  * Return first cell model data in this range
5005
+ *
5006
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5007
+ * {@link FRange.getCellDataGrid} once instead of calling this method for each cell.
5008
+ *
4938
5009
  * @returns {ICellData | null} The cell model data
4939
5010
  * @example
4940
5011
  * ```ts
@@ -5056,6 +5127,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5056
5127
  }
5057
5128
  /**
5058
5129
  * 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.
5130
+ *
5131
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5132
+ * {@link FRange.getFormulas} once instead of calling this method for each cell.
5133
+ *
5059
5134
  * @returns {string} The formula for the cell.
5060
5135
  * @example
5061
5136
  * ```ts
@@ -5098,6 +5173,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5098
5173
  }
5099
5174
  /**
5100
5175
  * Gets whether text wrapping is enabled for top-left cell in the range.
5176
+ *
5177
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5178
+ * {@link FRange.getWraps} once instead of calling this method for each cell.
5179
+ *
5101
5180
  * @returns {boolean} whether text wrapping is enabled for the cell.
5102
5181
  * @example
5103
5182
  * ```ts
@@ -5158,6 +5237,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5158
5237
  /**
5159
5238
  * Returns the horizontal alignment of the top-left cell as `left`, `center`, or `normal` (right alignment).
5160
5239
  * Default and other core alignment values return `general`, which is not accepted by `setHorizontalAlignment()`.
5240
+ *
5241
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5242
+ * {@link FRange.getHorizontalAlignments} once instead of calling this method for each cell.
5243
+ *
5161
5244
  * @returns {string} The horizontal alignment of the text in the cell.
5162
5245
  * @example
5163
5246
  * ```ts
@@ -5191,6 +5274,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5191
5274
  /**
5192
5275
  * Returns `top`, `middle`, or `bottom` for the top-left cell; unspecified alignment returns `general`.
5193
5276
  * `general` is a getter result and is not accepted by `setVerticalAlignment()`.
5277
+ *
5278
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5279
+ * {@link FRange.getVerticalAlignments} once instead of calling this method for each cell.
5280
+ *
5194
5281
  * @returns {string} The vertical alignment of the text in the cell.
5195
5282
  * @example
5196
5283
  * ```ts
@@ -5221,7 +5308,12 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5221
5308
  return this._worksheet.getRange(this._range).getVerticalAlignments().map((row) => row.map((alignment) => transformCoreVerticalAlignment(alignment)));
5222
5309
  }
5223
5310
  /**
5224
- * Set custom meta data for first cell in current range.
5311
+ * Set the same custom metadata for every cell in the current range.
5312
+ *
5313
+ * For the same metadata across multiple cells, call this method once on the entire target range.
5314
+ * For different metadata per cell, prefer {@link FRange.setCustomMetaDatas} with a two-dimensional
5315
+ * array matching the range dimensions instead of calling this method for each cell.
5316
+ *
5225
5317
  * @param {CustomData} data The custom meta data
5226
5318
  * @returns {FRange} This range, for chaining
5227
5319
  * @example
@@ -5275,6 +5367,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5275
5367
  }
5276
5368
  /**
5277
5369
  * Returns the custom meta data for the cell at the start of this range.
5370
+ *
5371
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5372
+ * {@link FRange.getCustomMetaDatas} once instead of calling this method for each cell.
5373
+ *
5278
5374
  * @returns {CustomData | null} The custom meta data
5279
5375
  * @example
5280
5376
  * ```ts
@@ -5308,6 +5404,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5308
5404
  }
5309
5405
  /**
5310
5406
  * Sets basic border properties for the current range.
5407
+ *
5408
+ * For borders on multiple cells, call this method once on the full target range. Border types such as
5409
+ * outer and inner are relative to that range, so applying them to each cell can produce different borders.
5410
+ *
5311
5411
  * @param {BorderType} type The type of border to apply
5312
5412
  * @param {BorderStyleTypes} style The border style
5313
5413
  * @param {string} [color] Optional border color in CSS notation
@@ -5336,6 +5436,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5336
5436
  }
5337
5437
  /**
5338
5438
  * Returns the background color of the top-left cell in the range.
5439
+ *
5440
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
5441
+ * {@link FRange.getBackgrounds} once instead of calling this method for each cell.
5442
+ *
5339
5443
  * @returns {string} The color code of the background.
5340
5444
  * @example
5341
5445
  * ```ts
@@ -5371,6 +5475,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5371
5475
  }
5372
5476
  /**
5373
5477
  * Set background color for current range.
5478
+ *
5479
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5480
+ * and call this method once instead of calling it on each cell separately.
5481
+ *
5374
5482
  * @param {string} color The background color
5375
5483
  * @returns {FRange} This range, for chaining
5376
5484
  * @example
@@ -5396,6 +5504,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5396
5504
  }
5397
5505
  /**
5398
5506
  * Set background color for current range.
5507
+ *
5508
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5509
+ * and call this method once instead of calling it on each cell separately.
5510
+ *
5399
5511
  * @param {string} color The background color
5400
5512
  * @returns {FRange} This range, for chaining
5401
5513
  * @example
@@ -5413,6 +5525,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5413
5525
  }
5414
5526
  /**
5415
5527
  * Set rotation for text in current range.
5528
+ *
5529
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5530
+ * and call this method once instead of calling it on each cell separately.
5531
+ *
5416
5532
  * @param {number} rotation - The rotation angle in degrees
5417
5533
  * @returns This range, for chaining
5418
5534
  * @example
@@ -5436,6 +5552,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5436
5552
  /**
5437
5553
  * Sets the value or specified cell properties for every cell in this range.
5438
5554
  *
5555
+ * For the same value or cell-data update across multiple cells, call this method once on the entire
5556
+ * target range. For different values or updates per cell, prefer {@link FRange.setValues} with a
5557
+ * two-dimensional array or sparse matrix instead of calling this method for each cell.
5558
+ *
5439
5559
  * There are two input modes:
5440
5560
  *
5441
5561
  * - `CellValue` (`number`, `string`, or `boolean`): replaces the cell content. A string starting
@@ -5447,10 +5567,12 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5447
5567
  * - `ICellData`: updates cell-data fields directly, for explicit control over `v` (value),
5448
5568
  * `f` (formula), `p` (rich text), `t` (value type), and `s` (style). The object bypasses the
5449
5569
  * formula and formatted-number parsing above: `{ v: '=SUM(A1:A2)' }` does not set a formula;
5450
- * use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Omitted content fields are not
5451
- * automatically cleared, so use `f: null` and `p: null` when replacing a formula or rich text
5452
- * with `v`. Use `v: null` to clear the stored value. Supplied style properties are merged into
5453
- * the existing style; `s: null` clears the style.
5570
+ * use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Writing `v` or `p` without `f` and
5571
+ * `si` replaces the target formula, as writing a scalar value does, and writing `f` without
5572
+ * `si` disassociates the cell from its previous shared formula. Rich text is still not
5573
+ * cleared by a value write, so pass `p: null` when replacing rich text with `v`. Use
5574
+ * `v: null` to clear the stored value. Supplied style properties are merged into the existing
5575
+ * style; `s: null` clears the style.
5454
5576
  *
5455
5577
  * In both modes, the stored value is converted according to its cell type. Unless an `ICellData`
5456
5578
  * input supplies `t`, the type is inferred from the value, number format, and existing cell type.
@@ -5499,6 +5621,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5499
5621
  /**
5500
5622
  * Sets the value or specified cell properties of the top-left cell in this range.
5501
5623
  * Uses the same scalar parsing and cell-data update rules as {@link FRange.setValue}.
5624
+ *
5625
+ * For multiple cells, prefer {@link FRange.setValues} on the target range with a two-dimensional array
5626
+ * or sparse matrix. To apply the same value to the entire range, use {@link FRange.setValue} once.
5627
+ *
5502
5628
  * @param {CellValue | ICellData} value The scalar content or cell-data update to apply to the top-left cell only.
5503
5629
  * @returns {FRange} This range, for chaining
5504
5630
  * @example
@@ -5531,6 +5657,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5531
5657
  }
5532
5658
  /**
5533
5659
  * Set the rich text value for the cell at the start of this range.
5660
+ *
5661
+ * For multiple cells, prefer {@link FRange.setRichTextValues} on the target range with a two-dimensional
5662
+ * array matching its dimensions instead of calling this method for each cell.
5663
+ *
5534
5664
  * @param {RichTextValue | IDocumentData} value The rich text value
5535
5665
  * @returns {FRange} The range
5536
5666
  * @example
@@ -5606,6 +5736,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5606
5736
  * Set the cell wrap of the given range.
5607
5737
  * Pass `true` to set `WrapStrategy.WRAP`, or `false` to reset to `WrapStrategy.UNSPECIFIED`.
5608
5738
  * Use `setWrapStrategy()` to explicitly select clipping or overflow behavior.
5739
+ *
5740
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5741
+ * and call this method once instead of calling it on each cell separately.
5742
+ *
5609
5743
  * @param {boolean} isWrapEnabled Whether to enable wrap
5610
5744
  * @returns {FRange} this range, for chaining
5611
5745
  * @example
@@ -5629,6 +5763,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5629
5763
  }
5630
5764
  /**
5631
5765
  * Sets whether cells shrink their font size to fit the cell width.
5766
+ *
5767
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5768
+ * and call this method once instead of calling it on each cell separately.
5769
+ *
5632
5770
  * @param {boolean} enabled Whether to enable shrink-to-fit for this range.
5633
5771
  * @returns {FRange} This range, for chaining.
5634
5772
  * @example
@@ -5647,6 +5785,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5647
5785
  }
5648
5786
  /**
5649
5787
  * Sets the text wrapping strategy for the cells in the range.
5788
+ *
5789
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5790
+ * and call this method once instead of calling it on each cell separately.
5791
+ *
5650
5792
  * @param {WrapStrategy} strategy The text wrapping strategy
5651
5793
  * @returns {FRange} this range, for chaining
5652
5794
  * @example
@@ -5670,6 +5812,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5670
5812
  }
5671
5813
  /**
5672
5814
  * Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
5815
+ *
5816
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5817
+ * and call this method once instead of calling it on each cell separately.
5818
+ *
5673
5819
  * @param {FVerticalAlignment} alignment The vertical alignment
5674
5820
  * @returns {FRange} this range, for chaining
5675
5821
  * @example
@@ -5693,6 +5839,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5693
5839
  /**
5694
5840
  * Sets the horizontal alignment for the range using `left`, `center`, or `normal`.
5695
5841
  * These parameter names follow Google Apps Script. In Univer, `normal` means right alignment; `right` is not accepted.
5842
+ *
5843
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5844
+ * and call this method once instead of calling it on each cell separately.
5845
+ *
5696
5846
  * @param {FHorizontalAlignment} alignment The horizontal alignment: `left`, `center`, or `normal` (right alignment).
5697
5847
  * @returns {FRange} this range, for chaining
5698
5848
  * @example
@@ -5717,6 +5867,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5717
5867
  * Sets cell values or specified cell properties using an array or a sparse matrix.
5718
5868
  * Each entry follows the scalar parsing and cell-data update rules of {@link FRange.setValue}.
5719
5869
  *
5870
+ * For multiple cells, pass all values or cell-data updates in one call instead of calling this method
5871
+ * on individual cell ranges. Use a matching two-dimensional array for a rectangle, or a sparse matrix
5872
+ * with absolute worksheet coordinates for non-contiguous cells.
5873
+ *
5720
5874
  * A two-dimensional array is relative to this range's top-left cell and must match its dimensions.
5721
5875
  * A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries
5722
5876
  * are updated; matrix coordinates are not offset by or clipped to this range.
@@ -5752,6 +5906,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5752
5906
  }
5753
5907
  /**
5754
5908
  * Sets the font weight for the given range (normal/bold),
5909
+ *
5910
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5911
+ * and call this method once instead of calling it on each cell separately.
5912
+ *
5755
5913
  * @param {FontWeight|null} fontWeight The font weight, either 'normal' or 'bold'; a null value resets the font weight.
5756
5914
  * @returns {FRange} This range, for chaining
5757
5915
  * @example
@@ -5784,6 +5942,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5784
5942
  }
5785
5943
  /**
5786
5944
  * Sets the font style for the given range ('italic' or 'normal').
5945
+ *
5946
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5947
+ * and call this method once instead of calling it on each cell separately.
5948
+ *
5787
5949
  * @param {FontStyle|null} fontStyle The font style, either 'italic' or 'normal'; a null value resets the font style.
5788
5950
  * @returns {FRange} This range, for chaining
5789
5951
  * @example
@@ -5816,6 +5978,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5816
5978
  }
5817
5979
  /**
5818
5980
  * Sets the font line style of the given range ('underline', 'line-through', or 'none').
5981
+ *
5982
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
5983
+ * and call this method once instead of calling it on each cell separately.
5984
+ *
5819
5985
  * @param {FontLine|null} fontLine The font line style, either 'underline', 'line-through', or 'none'; a null value resets the font line style.
5820
5986
  * @returns {FRange} This range, for chaining
5821
5987
  * @example
@@ -5877,6 +6043,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5877
6043
  }
5878
6044
  /**
5879
6045
  * Sets the font family, such as "Arial" or "Helvetica".
6046
+ *
6047
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
6048
+ * and call this method once instead of calling it on each cell separately.
6049
+ *
5880
6050
  * @param {string|null} fontFamily The font family to set; a null value resets the font family.
5881
6051
  * @returns {FRange} This range, for chaining
5882
6052
  * @example
@@ -5904,6 +6074,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5904
6074
  }
5905
6075
  /**
5906
6076
  * Sets the font size, with the size being the point size to use.
6077
+ *
6078
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
6079
+ * and call this method once instead of calling it on each cell separately.
6080
+ *
5907
6081
  * @param {number|null} size A font size in point size. A null value resets the font size.
5908
6082
  * @returns {FRange} This range, for chaining
5909
6083
  * @example
@@ -5931,6 +6105,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
5931
6105
  }
5932
6106
  /**
5933
6107
  * Sets the font color in CSS notation (such as '#ffffff' or 'white').
6108
+ *
6109
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
6110
+ * and call this method once instead of calling it on each cell separately.
6111
+ *
5934
6112
  * @param {string|null} color The font color in CSS notation (such as '#ffffff' or 'white'); a null value resets the color.
5935
6113
  * @returns {FRange} This range, for chaining
5936
6114
  * @example
@@ -6350,6 +6528,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
6350
6528
  /**
6351
6529
  * Clears the range content and formatting, or only one of them as specified by the options.
6352
6530
  * Both content and formatting are cleared when both flags are true or both are false.
6531
+ *
6532
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
6533
+ * method once instead of clearing each cell separately.
6534
+ *
6353
6535
  * @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
6354
6536
  * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. Effective only when `formatOnly` is false. Defaults to false.
6355
6537
  * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
@@ -6381,6 +6563,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
6381
6563
  }
6382
6564
  /**
6383
6565
  * Clears content of the range, while preserving formatting information.
6566
+ *
6567
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
6568
+ * method once instead of clearing each cell separately.
6569
+ *
6384
6570
  * @returns {FRange} This range, for chaining.
6385
6571
  * @example
6386
6572
  * ```typescript
@@ -6403,6 +6589,10 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
6403
6589
  }
6404
6590
  /**
6405
6591
  * Clears formatting information of the range, while preserving contents.
6592
+ *
6593
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
6594
+ * method once instead of clearing each cell separately.
6595
+ *
6406
6596
  * @returns {FRange} This range, for chaining.
6407
6597
  * @example
6408
6598
  * ```typescript
@@ -6686,6 +6876,11 @@ let FRange = _FRange = class FRange extends _univerjs_core_facade.FBaseInitialab
6686
6876
  }
6687
6877
  /**
6688
6878
  * Updates the formula for this range. The given formula must be in A1 notation.
6879
+ *
6880
+ * For the same formula string across multiple cells, call this method once on the entire target range.
6881
+ * For different formulas per cell, prefer {@link FRange.setFormulas} with a two-dimensional array
6882
+ * matching the range dimensions instead of calling this method for each cell.
6883
+ *
6689
6884
  * @param {string} formula - A string representing the formula to set for the cell.
6690
6885
  * @returns {FRange} This range instance for chaining.
6691
6886
  * @example
@@ -6820,8 +7015,7 @@ FRange = _FRange = __decorate([
6820
7015
  __decorateParam(6, _univerjs_core.ILogService)
6821
7016
  ], FRange);
6822
7017
 
6823
- //#endregion
6824
- //#region src/facade/permission/f-workbook-permission.ts
7018
+ // src/facade/permission/f-workbook-permission.ts
6825
7019
  let FWorkbookPermission = class FWorkbookPermission extends _univerjs_core_facade.FBase {
6826
7020
  constructor(_unitId, _injector, _permissionService, _authzIoService) {
6827
7021
  super();
@@ -7148,8 +7342,7 @@ FWorkbookPermission = __decorate([
7148
7342
  __decorateParam(3, _univerjs_core.IAuthzIoService)
7149
7343
  ], FWorkbookPermission);
7150
7344
 
7151
- //#endregion
7152
- //#region src/facade/f-workbook.ts
7345
+ // src/facade/f-workbook.ts
7153
7346
  let FWorkbook = class FWorkbook extends _univerjs_core_facade.FBaseInitialable {
7154
7347
  constructor(_workbook, _injector, _resourceLoaderService, _selectionManagerService, _univerInstanceService, _commandService, _permissionService, _logService, _definedNamesService) {
7155
7348
  super(_injector);
@@ -8163,8 +8356,7 @@ FWorkbook = __decorate([
8163
8356
  __decorateParam(8, _univerjs_engine_formula.IDefinedNamesService)
8164
8357
  ], FWorkbook);
8165
8358
 
8166
- //#endregion
8167
- //#region src/facade/f-univer.ts
8359
+ // src/facade/f-univer.ts
8168
8360
  var FUniverSheetsMixin = class extends _univerjs_core_facade.FUniver {
8169
8361
  createWorkbook(data, options) {
8170
8362
  const workbook = this._injector.get(_univerjs_core.IUniverInstanceService).createUnit(_univerjs_core.UniverInstanceType.UNIVER_SHEET, data, options);
@@ -8522,8 +8714,7 @@ var FUniverSheetsMixin = class extends _univerjs_core_facade.FUniver {
8522
8714
  };
8523
8715
  _univerjs_core_facade.FUniver.extend(FUniverSheetsMixin);
8524
8716
 
8525
- //#endregion
8526
- //#region src/facade/f-enum.ts
8717
+ // src/facade/f-enum.ts
8527
8718
  /**
8528
8719
  * Copyright 2023-present DreamNum Co., Ltd.
8529
8720
  *
@@ -8564,8 +8755,7 @@ var FSheetsEnumMixin = class extends _univerjs_core_facade.FEnum {
8564
8755
  };
8565
8756
  _univerjs_core_facade.FEnum.extend(FSheetsEnumMixin);
8566
8757
 
8567
- //#endregion
8568
- //#region src/facade/f-event.ts
8758
+ // src/facade/f-event.ts
8569
8759
  var FSheetsEventNameMixin = class extends _univerjs_core_facade.FEventName {
8570
8760
  get SheetCreated() {
8571
8761
  return "SheetCreated";
@@ -8630,7 +8820,6 @@ var FSheetsEventNameMixin = class extends _univerjs_core_facade.FEventName {
8630
8820
  };
8631
8821
  _univerjs_core_facade.FEventName.extend(FSheetsEventNameMixin);
8632
8822
 
8633
- //#endregion
8634
8823
  Object.defineProperty(exports, "FRange", {
8635
8824
  enumerable: true,
8636
8825
  get: function () {