@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/facade.js CHANGED
@@ -2,9 +2,9 @@ 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
- //#region src/facade/const.ts
7
+ // src/facade/const.ts
8
8
  /**
9
9
  * Copyright 2023-present DreamNum Co., Ltd.
10
10
  *
@@ -22,8 +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
- //#endregion
26
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/typeof.js
25
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/typeof.js
27
26
  function _typeof(o) {
28
27
  "@babel/helpers - typeof";
29
28
  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -33,28 +32,25 @@ function _typeof(o) {
33
32
  }, _typeof(o);
34
33
  }
35
34
 
36
- //#endregion
37
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPrimitive.js
38
- function toPrimitive(t, r) {
35
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/toPrimitive.js
36
+ function toPrimitive(t, e) {
39
37
  if ("object" != _typeof(t) || !t) return t;
40
- var e = t[Symbol.toPrimitive];
41
- if (void 0 !== e) {
42
- 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");
43
41
  if ("object" != _typeof(i)) return i;
44
42
  throw new TypeError("@@toPrimitive must return a primitive value.");
45
43
  }
46
- return ("string" === r ? String : Number)(t);
44
+ return ("string" === e ? String : Number)(t);
47
45
  }
48
46
 
49
- //#endregion
50
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/toPropertyKey.js
47
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/toPropertyKey.js
51
48
  function toPropertyKey(t) {
52
49
  var i = toPrimitive(t, "string");
53
50
  return "symbol" == _typeof(i) ? i : i + "";
54
51
  }
55
52
 
56
- //#endregion
57
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/defineProperty.js
53
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/defineProperty.js
58
54
  function _defineProperty(e, r, t) {
59
55
  return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
60
56
  value: t,
@@ -64,16 +60,14 @@ function _defineProperty(e, r, t) {
64
60
  }) : e[r] = t, e;
65
61
  }
66
62
 
67
- //#endregion
68
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateParam.js
63
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/decorateParam.js
69
64
  function __decorateParam(paramIndex, decorator) {
70
65
  return function(target, key) {
71
66
  decorator(target, key, paramIndex);
72
67
  };
73
68
  }
74
69
 
75
- //#endregion
76
- //#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
70
+ // \0@oxc-project+runtime@0.157.0/helpers/esm/decorate.js
77
71
  function __decorate(decorators, target, key, desc) {
78
72
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
79
73
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -81,8 +75,7 @@ function __decorate(decorators, target, key, desc) {
81
75
  return c > 3 && r && Object.defineProperty(target, key, r), r;
82
76
  }
83
77
 
84
- //#endregion
85
- //#region src/facade/f-defined-name.ts
78
+ // src/facade/f-defined-name.ts
86
79
  /**
87
80
  * Get defined name field name
88
81
  * @param {string} unitId - unit id
@@ -582,8 +575,7 @@ FDefinedName = __decorate([
582
575
  __decorateParam(9, IDefinedNamesService)
583
576
  ], FDefinedName);
584
577
 
585
- //#endregion
586
- //#region src/facade/f-selection.ts
578
+ // src/facade/f-selection.ts
587
579
  var _FSelection;
588
580
  let FSelection = _FSelection = class FSelection {
589
581
  constructor(_workbook, _worksheet, _selections, _injector) {
@@ -755,8 +747,7 @@ let FSelection = _FSelection = class FSelection {
755
747
  };
756
748
  FSelection = _FSelection = __decorate([__decorateParam(3, Inject(Injector))], FSelection);
757
749
 
758
- //#endregion
759
- //#region src/facade/permission/permission-types.ts
750
+ // src/facade/permission/permission-types.ts
760
751
  /**
761
752
  * Copyright 2023-present DreamNum Co., Ltd.
762
753
  *
@@ -780,7 +771,7 @@ FSelection = _FSelection = __decorate([__decorateParam(3, Inject(Injector))], FS
780
771
  /**
781
772
  * User role in a unit (Workbook)
782
773
  */
783
- let UnitRole$1 = /* @__PURE__ */ function(UnitRole) {
774
+ let UnitRole = /* @__PURE__ */ function(UnitRole) {
784
775
  UnitRole[UnitRole["Reader"] = 0] = "Reader";
785
776
  UnitRole[UnitRole["Editor"] = 1] = "Editor";
786
777
  UnitRole[UnitRole["Owner"] = 2] = "Owner";
@@ -895,8 +886,7 @@ let RangePermissionPoint = /* @__PURE__ */ function(RangePermissionPoint) {
895
886
  return RangePermissionPoint;
896
887
  }({});
897
888
 
898
- //#endregion
899
- //#region src/facade/permission/permission-point-map.ts
889
+ // src/facade/permission/permission-point-map.ts
900
890
  /**
901
891
  * Mapping table from Workbook permission point enum to class constructors
902
892
  */
@@ -959,8 +949,7 @@ const RANGE_PERMISSION_POINT_MAP = {
959
949
  ["RangeDeleteProtection"]: RangeProtectionPermissionDeleteProtectionPoint
960
950
  };
961
951
 
962
- //#endregion
963
- //#region src/facade/permission/util.ts
952
+ // src/facade/permission/util.ts
964
953
  function determineViewState(allowViewByOthers) {
965
954
  if (allowViewByOthers === false) return ViewStateEnum.NoOneElseCanView;
966
955
  return ViewStateEnum.OthersCanView;
@@ -1039,8 +1028,7 @@ async function getListRangeProtectionRules(injector, unitId, subUnitId, options)
1039
1028
  }))).map(({ id, permissionId, ranges, options }) => injector.createInstance(FRangeProtectionRule, unitId, subUnitId, id, permissionId, ranges, options));
1040
1029
  }
1041
1030
 
1042
- //#endregion
1043
- //#region src/facade/permission/f-range-protection-rule.ts
1031
+ // src/facade/permission/f-range-protection-rule.ts
1044
1032
  let FRangeProtectionRule = class FRangeProtectionRule {
1045
1033
  constructor(_unitId, _subUnitId, _ruleId, _permissionId, _ranges, _options, _injector, _permissionService, _authzIoService, _commandService, _rangeProtectionRuleModel) {
1046
1034
  this._unitId = _unitId;
@@ -1188,7 +1176,7 @@ let FRangeProtectionRule = class FRangeProtectionRule {
1188
1176
  name: this._options.name || "",
1189
1177
  strategies: [{
1190
1178
  action: instance.subType,
1191
- role: value ? UnitRole.Editor : UnitRole.Owner
1179
+ role: value ? UnitRole$1.Editor : UnitRole$1.Owner
1192
1180
  }],
1193
1181
  scope: void 0,
1194
1182
  collaborators: void 0
@@ -1333,8 +1321,7 @@ FRangeProtectionRule = __decorate([
1333
1321
  __decorateParam(10, Inject(RangeProtectionRuleModel))
1334
1322
  ], FRangeProtectionRule);
1335
1323
 
1336
- //#endregion
1337
- //#region src/facade/permission/f-worksheet-permission.ts
1324
+ // src/facade/permission/f-worksheet-permission.ts
1338
1325
  let FWorksheetPermission = class FWorksheetPermission extends FBase {
1339
1326
  constructor(_worksheet, _injector, _permissionService, _authzIoService, _commandService, _rangeProtectionRuleModel, _worksheetProtectionPointModel, _worksheetProtectionRuleModel) {
1340
1327
  super();
@@ -1411,7 +1398,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1411
1398
  }
1412
1399
  collaborators.push({
1413
1400
  id: existingCollaborator.id,
1414
- role: UnitRole.Editor,
1401
+ role: UnitRole$1.Editor,
1415
1402
  subject: existingCollaborator.subject
1416
1403
  });
1417
1404
  });
@@ -1422,10 +1409,10 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1422
1409
  collaborators,
1423
1410
  unitID: this._unitId,
1424
1411
  strategies: [{
1425
- role: UnitRole.Editor,
1412
+ role: UnitRole$1.Editor,
1426
1413
  action: UnitAction.Edit
1427
1414
  }, {
1428
- role: UnitRole.Reader,
1415
+ role: UnitRole$1.Reader,
1429
1416
  action: UnitAction.View
1430
1417
  }],
1431
1418
  name: (options === null || options === void 0 ? void 0 : options.name) || "",
@@ -1574,7 +1561,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1574
1561
  name: worksheetProtectionRule.description || "",
1575
1562
  strategies: [{
1576
1563
  action: instance.subType,
1577
- role: value ? UnitRole.Editor : UnitRole.Owner
1564
+ role: value ? UnitRole$1.Editor : UnitRole$1.Owner
1578
1565
  }],
1579
1566
  scope: void 0,
1580
1567
  collaborators: void 0
@@ -1791,7 +1778,7 @@ let FWorksheetPermission = class FWorksheetPermission extends FBase {
1791
1778
  }
1792
1779
  collaborators.push({
1793
1780
  id: existingCollaborator.id,
1794
- role: UnitRole.Editor,
1781
+ role: UnitRole$1.Editor,
1795
1782
  subject: existingCollaborator.subject
1796
1783
  });
1797
1784
  });
@@ -1928,8 +1915,7 @@ FWorksheetPermission = __decorate([
1928
1915
  __decorateParam(7, Inject(WorksheetProtectionRuleModel))
1929
1916
  ], FWorksheetPermission);
1930
1917
 
1931
- //#endregion
1932
- //#region src/facade/utils.ts
1918
+ // src/facade/utils.ts
1933
1919
  /**
1934
1920
  * Transform the Facade API horizontal alignment to the Univer Core horizontal alignment.
1935
1921
  * @param {FHorizontalAlignment} value - The Facade API horizontal alignment.
@@ -2013,8 +1999,7 @@ function covertToColRange(range, worksheet) {
2013
1999
  };
2014
2000
  }
2015
2001
 
2016
- //#endregion
2017
- //#region src/facade/f-worksheet.ts
2002
+ // src/facade/f-worksheet.ts
2018
2003
  var _FWorksheet;
2019
2004
  function assertValidRowInsertion(methodName, rowIndex, rowCount, howMany) {
2020
2005
  if (!Number.isInteger(howMany) || howMany <= 0) throw new RangeError(`${methodName}(): row count ${howMany} must be a positive integer.`);
@@ -2292,7 +2277,6 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2292
2277
  ...parsedRange,
2293
2278
  unitId: this._workbook.getUnitId(),
2294
2279
  sheetId: sheet.getSheetId(),
2295
- rangeType: RANGE_TYPE.NORMAL,
2296
2280
  startRow: parsedRange.rangeType === RANGE_TYPE.COLUMN ? 0 : parsedRange.startRow,
2297
2281
  endRow: parsedRange.rangeType === RANGE_TYPE.COLUMN ? sheet.getMaxRows() - 1 : parsedRange.endRow,
2298
2282
  startColumn: parsedRange.rangeType === RANGE_TYPE.ROW ? 0 : parsedRange.startColumn,
@@ -2341,6 +2325,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2341
2325
  }
2342
2326
  /**
2343
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
+ *
2344
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`.
2345
2333
  * @returns {FWorksheet} This sheet, for chaining.
2346
2334
  * @example
@@ -2358,6 +2346,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2358
2346
  }
2359
2347
  /**
2360
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
+ *
2361
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`.
2362
2354
  * @returns {FWorksheet} This sheet, for chaining.
2363
2355
  * @example
@@ -2375,6 +2367,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2375
2367
  }
2376
2368
  /**
2377
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
+ *
2378
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`.
2379
2375
  * @param {number} [numRows] - The positive number of rows to insert.
2380
2376
  * @returns {FWorksheet} This sheet, for chaining.
@@ -2472,6 +2468,11 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2472
2468
  }
2473
2469
  /**
2474
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
+ *
2475
2476
  * @param {number} rowPosition - The position of the row, starting at 0 for the first row.
2476
2477
  * @returns {FWorksheet} This sheet, for chaining.
2477
2478
  * @example
@@ -2573,6 +2574,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2573
2574
  }
2574
2575
  /**
2575
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
+ *
2576
2581
  * @param {FRange} row - The row range to hide.
2577
2582
  * @returns {FWorksheet} This sheet, for chaining.
2578
2583
  * @example
@@ -2600,6 +2605,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2600
2605
  }
2601
2606
  /**
2602
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
+ *
2603
2612
  * @param {number} rowIndex - The starting index of the rows to hide
2604
2613
  * @param {number} [numRow] - The number of rows to hide
2605
2614
  * @returns {FWorksheet} This sheet, for chaining.
@@ -2632,6 +2641,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2632
2641
  }
2633
2642
  /**
2634
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
+ *
2635
2648
  * @param {FRange} row - The range to unhide, if hidden.
2636
2649
  * @returns {FWorksheet} This sheet, for chaining.
2637
2650
  * @example
@@ -2659,6 +2672,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2659
2672
  }
2660
2673
  /**
2661
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
+ *
2662
2679
  * @param {number} rowIndex - The starting index of the rows
2663
2680
  * @param {number} [numRows] - The number of rows
2664
2681
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -2691,6 +2708,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2691
2708
  }
2692
2709
  /**
2693
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
+ *
2694
2715
  * @param {number} rowPosition - The row position to change.
2695
2716
  * @param {number} height - The height in pixels to set it to.
2696
2717
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -2918,6 +2939,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2918
2939
  }
2919
2940
  /**
2920
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
+ *
2921
2946
  * @param {number} afterPosition - The column after which the new column should be added, starting at 0 for the first column
2922
2947
  * @returns {FWorksheet} This worksheet instance for chaining
2923
2948
  * @example
@@ -2935,6 +2960,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2935
2960
  }
2936
2961
  /**
2937
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
+ *
2938
2967
  * @param {number} beforePosition - The column before which the new column should be added, starting at 0 for the first column
2939
2968
  * @returns {FWorksheet} This worksheet instance for chaining
2940
2969
  * @example
@@ -2952,6 +2981,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
2952
2981
  }
2953
2982
  /**
2954
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
+ *
2955
2988
  * @param {number} columnIndex - The index indicating where to insert a column, starting at 0 for the first column
2956
2989
  * @param {number} [numColumns] - The number of columns to insert
2957
2990
  * @returns {FWorksheet} This sheet, for chaining
@@ -3046,6 +3079,11 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3046
3079
  }
3047
3080
  /**
3048
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
+ *
3049
3087
  * @param {number} columnPosition - The position of the column, starting at 0 for the first column
3050
3088
  * @returns {FWorksheet} This sheet, for chaining
3051
3089
  * @example
@@ -3147,6 +3185,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3147
3185
  }
3148
3186
  /**
3149
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
+ *
3150
3192
  * @param {FRange} column - The column range to hide
3151
3193
  * @returns {FWorksheet} This sheet, for chaining
3152
3194
  * @example
@@ -3174,6 +3216,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3174
3216
  }
3175
3217
  /**
3176
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
+ *
3177
3223
  * @param {number} columnIndex - The starting index of the columns to hide
3178
3224
  * @param {number} [numColumn] - The number of columns to hide
3179
3225
  * @returns {FWorksheet} This sheet, for chaining
@@ -3206,6 +3252,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3206
3252
  }
3207
3253
  /**
3208
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
+ *
3209
3259
  * @param {FRange} column - The range to unhide, if hidden
3210
3260
  * @returns {FWorksheet} This sheet, for chaining
3211
3261
  * @example
@@ -3233,6 +3283,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3233
3283
  }
3234
3284
  /**
3235
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
+ *
3236
3290
  * @param {number} columnIndex - The starting index of the columns to unhide
3237
3291
  * @param {number} [numColumns] - The number of columns to unhide
3238
3292
  * @returns {FWorksheet} This sheet, for chaining
@@ -3265,6 +3319,10 @@ let FWorksheet = _FWorksheet = class FWorksheet extends FBaseInitialable {
3265
3319
  }
3266
3320
  /**
3267
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
+ *
3268
3326
  * @param {number} columnPosition - The position of the given column to set
3269
3327
  * @param {number} width - The width in pixels to set it to
3270
3328
  * @returns {FWorksheet} This sheet, for chaining
@@ -4290,8 +4348,7 @@ FWorksheet = _FWorksheet = __decorate([
4290
4348
  __decorateParam(6, ICommandService)
4291
4349
  ], FWorksheet);
4292
4350
 
4293
- //#endregion
4294
- //#region src/facade/permission/f-range-permission.ts
4351
+ // src/facade/permission/f-range-permission.ts
4295
4352
  let FRangePermission = class FRangePermission extends FBase {
4296
4353
  constructor(_unitId, _subUnitId, _range, _worksheet, _injector, _authzIoService, _commandService, _rangeProtectionRuleModel) {
4297
4354
  super();
@@ -4361,7 +4418,7 @@ let FRangePermission = class FRangePermission extends FBase {
4361
4418
  }
4362
4419
  collaborators.push({
4363
4420
  id: existingCollaborator.id,
4364
- role: UnitRole.Editor,
4421
+ role: UnitRole$1.Editor,
4365
4422
  subject: existingCollaborator.subject
4366
4423
  });
4367
4424
  });
@@ -4446,8 +4503,7 @@ FRangePermission = __decorate([
4446
4503
  __decorateParam(7, Inject(RangeProtectionRuleModel))
4447
4504
  ], FRangePermission);
4448
4505
 
4449
- //#endregion
4450
- //#region src/facade/f-range.ts
4506
+ // src/facade/f-range.ts
4451
4507
  var _FRange;
4452
4508
  var _FRange2;
4453
4509
  let FRange = _FRange = class FRange extends FBaseInitialable {
@@ -4706,6 +4762,9 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4706
4762
  /**
4707
4763
  * Return first cell style in this range.
4708
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
+ *
4709
4768
  * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
4710
4769
  * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
4711
4770
  * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
@@ -4757,6 +4816,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4757
4816
  }
4758
4817
  /**
4759
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
+ *
4760
4823
  * @returns {Nullable<CellValue>} The raw value of the cell. Returns `null` if the cell is empty.
4761
4824
  * @example
4762
4825
  * ```ts
@@ -4781,6 +4844,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4781
4844
  }
4782
4845
  /**
4783
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
+ *
4784
4851
  * @returns {string} The displayed value of the cell. Returns an empty string if the cell is empty.
4785
4852
  * @example
4786
4853
  * ```ts
@@ -4934,6 +5001,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
4934
5001
  }
4935
5002
  /**
4936
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
+ *
4937
5008
  * @returns {ICellData | null} The cell model data
4938
5009
  * @example
4939
5010
  * ```ts
@@ -5055,6 +5126,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5055
5126
  }
5056
5127
  /**
5057
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
+ *
5058
5133
  * @returns {string} The formula for the cell.
5059
5134
  * @example
5060
5135
  * ```ts
@@ -5097,6 +5172,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5097
5172
  }
5098
5173
  /**
5099
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
+ *
5100
5179
  * @returns {boolean} whether text wrapping is enabled for the cell.
5101
5180
  * @example
5102
5181
  * ```ts
@@ -5157,6 +5236,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5157
5236
  /**
5158
5237
  * Returns the horizontal alignment of the top-left cell as `left`, `center`, or `normal` (right alignment).
5159
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
+ *
5160
5243
  * @returns {string} The horizontal alignment of the text in the cell.
5161
5244
  * @example
5162
5245
  * ```ts
@@ -5190,6 +5273,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5190
5273
  /**
5191
5274
  * Returns `top`, `middle`, or `bottom` for the top-left cell; unspecified alignment returns `general`.
5192
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
+ *
5193
5280
  * @returns {string} The vertical alignment of the text in the cell.
5194
5281
  * @example
5195
5282
  * ```ts
@@ -5220,7 +5307,12 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5220
5307
  return this._worksheet.getRange(this._range).getVerticalAlignments().map((row) => row.map((alignment) => transformCoreVerticalAlignment(alignment)));
5221
5308
  }
5222
5309
  /**
5223
- * 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
+ *
5224
5316
  * @param {CustomData} data The custom meta data
5225
5317
  * @returns {FRange} This range, for chaining
5226
5318
  * @example
@@ -5274,6 +5366,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5274
5366
  }
5275
5367
  /**
5276
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
+ *
5277
5373
  * @returns {CustomData | null} The custom meta data
5278
5374
  * @example
5279
5375
  * ```ts
@@ -5307,6 +5403,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5307
5403
  }
5308
5404
  /**
5309
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
+ *
5310
5410
  * @param {BorderType} type The type of border to apply
5311
5411
  * @param {BorderStyleTypes} style The border style
5312
5412
  * @param {string} [color] Optional border color in CSS notation
@@ -5335,6 +5435,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5335
5435
  }
5336
5436
  /**
5337
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
+ *
5338
5442
  * @returns {string} The color code of the background.
5339
5443
  * @example
5340
5444
  * ```ts
@@ -5370,6 +5474,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5370
5474
  }
5371
5475
  /**
5372
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
+ *
5373
5481
  * @param {string} color The background color
5374
5482
  * @returns {FRange} This range, for chaining
5375
5483
  * @example
@@ -5395,6 +5503,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5395
5503
  }
5396
5504
  /**
5397
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
+ *
5398
5510
  * @param {string} color The background color
5399
5511
  * @returns {FRange} This range, for chaining
5400
5512
  * @example
@@ -5412,6 +5524,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5412
5524
  }
5413
5525
  /**
5414
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
+ *
5415
5531
  * @param {number} rotation - The rotation angle in degrees
5416
5532
  * @returns This range, for chaining
5417
5533
  * @example
@@ -5435,6 +5551,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5435
5551
  /**
5436
5552
  * Sets the value or specified cell properties for every cell in this range.
5437
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
+ *
5438
5558
  * There are two input modes:
5439
5559
  *
5440
5560
  * - `CellValue` (`number`, `string`, or `boolean`): replaces the cell content. A string starting
@@ -5446,10 +5566,12 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5446
5566
  * - `ICellData`: updates cell-data fields directly, for explicit control over `v` (value),
5447
5567
  * `f` (formula), `p` (rich text), `t` (value type), and `s` (style). The object bypasses the
5448
5568
  * formula and formatted-number parsing above: `{ v: '=SUM(A1:A2)' }` does not set a formula;
5449
- * use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Omitted content fields are not
5450
- * automatically cleared, so use `f: null` and `p: null` when replacing a formula or rich text
5451
- * with `v`. Use `v: null` to clear the stored value. Supplied style properties are merged into
5452
- * the existing style; `s: null` clears the style.
5569
+ * use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Writing `v` or `p` without `f` and
5570
+ * `si` replaces the target formula, as writing a scalar value does, and writing `f` without
5571
+ * `si` disassociates the cell from its previous shared formula. Rich text is still not
5572
+ * cleared by a value write, so pass `p: null` when replacing rich text with `v`. Use
5573
+ * `v: null` to clear the stored value. Supplied style properties are merged into the existing
5574
+ * style; `s: null` clears the style.
5453
5575
  *
5454
5576
  * In both modes, the stored value is converted according to its cell type. Unless an `ICellData`
5455
5577
  * input supplies `t`, the type is inferred from the value, number format, and existing cell type.
@@ -5498,6 +5620,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5498
5620
  /**
5499
5621
  * Sets the value or specified cell properties of the top-left cell in this range.
5500
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
+ *
5501
5627
  * @param {CellValue | ICellData} value The scalar content or cell-data update to apply to the top-left cell only.
5502
5628
  * @returns {FRange} This range, for chaining
5503
5629
  * @example
@@ -5530,6 +5656,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5530
5656
  }
5531
5657
  /**
5532
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
+ *
5533
5663
  * @param {RichTextValue | IDocumentData} value The rich text value
5534
5664
  * @returns {FRange} The range
5535
5665
  * @example
@@ -5605,6 +5735,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5605
5735
  * Set the cell wrap of the given range.
5606
5736
  * Pass `true` to set `WrapStrategy.WRAP`, or `false` to reset to `WrapStrategy.UNSPECIFIED`.
5607
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
+ *
5608
5742
  * @param {boolean} isWrapEnabled Whether to enable wrap
5609
5743
  * @returns {FRange} this range, for chaining
5610
5744
  * @example
@@ -5628,6 +5762,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5628
5762
  }
5629
5763
  /**
5630
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
+ *
5631
5769
  * @param {boolean} enabled Whether to enable shrink-to-fit for this range.
5632
5770
  * @returns {FRange} This range, for chaining.
5633
5771
  * @example
@@ -5646,6 +5784,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5646
5784
  }
5647
5785
  /**
5648
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
+ *
5649
5791
  * @param {WrapStrategy} strategy The text wrapping strategy
5650
5792
  * @returns {FRange} this range, for chaining
5651
5793
  * @example
@@ -5669,6 +5811,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5669
5811
  }
5670
5812
  /**
5671
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
+ *
5672
5818
  * @param {FVerticalAlignment} alignment The vertical alignment
5673
5819
  * @returns {FRange} this range, for chaining
5674
5820
  * @example
@@ -5692,6 +5838,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5692
5838
  /**
5693
5839
  * Sets the horizontal alignment for the range using `left`, `center`, or `normal`.
5694
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
+ *
5695
5845
  * @param {FHorizontalAlignment} alignment The horizontal alignment: `left`, `center`, or `normal` (right alignment).
5696
5846
  * @returns {FRange} this range, for chaining
5697
5847
  * @example
@@ -5716,6 +5866,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5716
5866
  * Sets cell values or specified cell properties using an array or a sparse matrix.
5717
5867
  * Each entry follows the scalar parsing and cell-data update rules of {@link FRange.setValue}.
5718
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
+ *
5719
5873
  * A two-dimensional array is relative to this range's top-left cell and must match its dimensions.
5720
5874
  * A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries
5721
5875
  * are updated; matrix coordinates are not offset by or clipped to this range.
@@ -5751,6 +5905,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5751
5905
  }
5752
5906
  /**
5753
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
+ *
5754
5912
  * @param {FontWeight|null} fontWeight The font weight, either 'normal' or 'bold'; a null value resets the font weight.
5755
5913
  * @returns {FRange} This range, for chaining
5756
5914
  * @example
@@ -5783,6 +5941,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5783
5941
  }
5784
5942
  /**
5785
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
+ *
5786
5948
  * @param {FontStyle|null} fontStyle The font style, either 'italic' or 'normal'; a null value resets the font style.
5787
5949
  * @returns {FRange} This range, for chaining
5788
5950
  * @example
@@ -5815,6 +5977,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5815
5977
  }
5816
5978
  /**
5817
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
+ *
5818
5984
  * @param {FontLine|null} fontLine The font line style, either 'underline', 'line-through', or 'none'; a null value resets the font line style.
5819
5985
  * @returns {FRange} This range, for chaining
5820
5986
  * @example
@@ -5876,6 +6042,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5876
6042
  }
5877
6043
  /**
5878
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
+ *
5879
6049
  * @param {string|null} fontFamily The font family to set; a null value resets the font family.
5880
6050
  * @returns {FRange} This range, for chaining
5881
6051
  * @example
@@ -5903,6 +6073,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5903
6073
  }
5904
6074
  /**
5905
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
+ *
5906
6080
  * @param {number|null} size A font size in point size. A null value resets the font size.
5907
6081
  * @returns {FRange} This range, for chaining
5908
6082
  * @example
@@ -5930,6 +6104,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
5930
6104
  }
5931
6105
  /**
5932
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
+ *
5933
6111
  * @param {string|null} color The font color in CSS notation (such as '#ffffff' or 'white'); a null value resets the color.
5934
6112
  * @returns {FRange} This range, for chaining
5935
6113
  * @example
@@ -6349,6 +6527,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6349
6527
  /**
6350
6528
  * Clears the range content and formatting, or only one of them as specified by the options.
6351
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
+ *
6352
6534
  * @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
6353
6535
  * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. Effective only when `formatOnly` is false. Defaults to false.
6354
6536
  * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
@@ -6380,6 +6562,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6380
6562
  }
6381
6563
  /**
6382
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
+ *
6383
6569
  * @returns {FRange} This range, for chaining.
6384
6570
  * @example
6385
6571
  * ```typescript
@@ -6402,6 +6588,10 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6402
6588
  }
6403
6589
  /**
6404
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
+ *
6405
6595
  * @returns {FRange} This range, for chaining.
6406
6596
  * @example
6407
6597
  * ```typescript
@@ -6685,6 +6875,11 @@ let FRange = _FRange = class FRange extends FBaseInitialable {
6685
6875
  }
6686
6876
  /**
6687
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
+ *
6688
6883
  * @param {string} formula - A string representing the formula to set for the cell.
6689
6884
  * @returns {FRange} This range instance for chaining.
6690
6885
  * @example
@@ -6819,8 +7014,7 @@ FRange = _FRange = __decorate([
6819
7014
  __decorateParam(6, ILogService)
6820
7015
  ], FRange);
6821
7016
 
6822
- //#endregion
6823
- //#region src/facade/permission/f-workbook-permission.ts
7017
+ // src/facade/permission/f-workbook-permission.ts
6824
7018
  let FWorkbookPermission = class FWorkbookPermission extends FBase {
6825
7019
  constructor(_unitId, _injector, _permissionService, _authzIoService) {
6826
7020
  super();
@@ -7147,8 +7341,7 @@ FWorkbookPermission = __decorate([
7147
7341
  __decorateParam(3, IAuthzIoService)
7148
7342
  ], FWorkbookPermission);
7149
7343
 
7150
- //#endregion
7151
- //#region src/facade/f-workbook.ts
7344
+ // src/facade/f-workbook.ts
7152
7345
  let FWorkbook = class FWorkbook extends FBaseInitialable {
7153
7346
  constructor(_workbook, _injector, _resourceLoaderService, _selectionManagerService, _univerInstanceService, _commandService, _permissionService, _logService, _definedNamesService) {
7154
7347
  super(_injector);
@@ -8162,8 +8355,7 @@ FWorkbook = __decorate([
8162
8355
  __decorateParam(8, IDefinedNamesService)
8163
8356
  ], FWorkbook);
8164
8357
 
8165
- //#endregion
8166
- //#region src/facade/f-univer.ts
8358
+ // src/facade/f-univer.ts
8167
8359
  var FUniverSheetsMixin = class extends FUniver {
8168
8360
  createWorkbook(data, options) {
8169
8361
  const workbook = this._injector.get(IUniverInstanceService).createUnit(UniverInstanceType.UNIVER_SHEET, data, options);
@@ -8521,8 +8713,7 @@ var FUniverSheetsMixin = class extends FUniver {
8521
8713
  };
8522
8714
  FUniver.extend(FUniverSheetsMixin);
8523
8715
 
8524
- //#endregion
8525
- //#region src/facade/f-enum.ts
8716
+ // src/facade/f-enum.ts
8526
8717
  /**
8527
8718
  * Copyright 2023-present DreamNum Co., Ltd.
8528
8719
  *
@@ -8549,7 +8740,7 @@ var FSheetsEnumMixin = class extends FEnum {
8549
8740
  return SplitDelimiterEnum;
8550
8741
  }
8551
8742
  get UnitRole() {
8552
- return UnitRole$1;
8743
+ return UnitRole;
8553
8744
  }
8554
8745
  get WorkbookPermissionPoint() {
8555
8746
  return WorkbookPermissionPoint;
@@ -8563,8 +8754,7 @@ var FSheetsEnumMixin = class extends FEnum {
8563
8754
  };
8564
8755
  FEnum.extend(FSheetsEnumMixin);
8565
8756
 
8566
- //#endregion
8567
- //#region src/facade/f-event.ts
8757
+ // src/facade/f-event.ts
8568
8758
  var FSheetsEventNameMixin = class extends FEventName {
8569
8759
  get SheetCreated() {
8570
8760
  return "SheetCreated";
@@ -8629,5 +8819,4 @@ var FSheetsEventNameMixin = class extends FEventName {
8629
8819
  };
8630
8820
  FEventName.extend(FSheetsEventNameMixin);
8631
8821
 
8632
- //#endregion
8633
8822
  export { FRange, FSelection, FSheetsEnumMixin, FSheetsEventNameMixin, FWorkbook, FWorkbookPermission, FWorksheet };