@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
@@ -21,7 +21,7 @@ export interface IMoveRowsCommandParams {
21
21
  fromRange: IRange;
22
22
  toRange: IRange;
23
23
  }
24
- export declare const MoveRowsCommandId: "sheet.command.move-rows";
24
+ export declare const MoveRowsCommandId: 'sheet.command.move-rows';
25
25
  /**
26
26
  * Command to move the selected rows (must currently selected) to the specified row.
27
27
  */
@@ -33,5 +33,5 @@ export interface IMoveColsCommandParams {
33
33
  fromRange: IRange;
34
34
  toRange: IRange;
35
35
  }
36
- export declare const MoveColsCommandId: "sheet.command.move-cols";
36
+ export declare const MoveColsCommandId: 'sheet.command.move-cols';
37
37
  export declare const MoveColsCommand: ICommand<IMoveColsCommandParams>;
@@ -21,5 +21,5 @@ export interface IReorderRangeCommandParams extends ISheetCommandSharedParams {
21
21
  [key: number]: number;
22
22
  };
23
23
  }
24
- export declare const ReorderRangeCommandId: "sheet.command.reorder-range";
24
+ export declare const ReorderRangeCommandId: 'sheet.command.reorder-range';
25
25
  export declare const ReorderRangeCommand: ICommand<IReorderRangeCommandParams>;
@@ -14,8 +14,8 @@
14
14
  * limitations under the License.
15
15
  */
16
16
  import type { BorderStyleTypes, ICommand, IRange } from '@univerjs/core';
17
- import type { IBorderInfo } from '../../services/border-style-manager.service';
18
17
  import { BorderType } from '@univerjs/core';
18
+ import type { IBorderInfo } from '../../services/border-style-manager.service';
19
19
  export interface ISetBorderBasicCommandParams {
20
20
  unitId?: string;
21
21
  subUnitId?: string;
@@ -14,7 +14,7 @@
14
14
  * limitations under the License.
15
15
  */
16
16
  import type { IAccessor, ICommand, IMutationInfo, IRange } from '@univerjs/core';
17
- export declare const factorySetNumfmtUndoMutation: (accessor: IAccessor, option: ISetNumfmtMutationParams) => IMutationInfo<ISetNumfmtMutationParams | IRemoveNumfmtMutationParams>[];
17
+ export declare const factorySetNumfmtUndoMutation: (accessor: IAccessor, option: ISetNumfmtMutationParams) => IMutationInfo<IRemoveNumfmtMutationParams | ISetNumfmtMutationParams>[];
18
18
  export interface ISetNumfmtMutationParams {
19
19
  values: {
20
20
  [id: string]: {
@@ -16,7 +16,8 @@
16
16
  import { Disposable, IAuthzIoService, ICommandService, IPermissionService, IUndoRedoService, IUniverInstanceService, UserManagerService } from '@univerjs/core';
17
17
  import { RangeProtectionRuleModel } from '../../models/range-protection-rule.model';
18
18
  import { WorkbookPermissionService } from '../../services/permission/workbook-permission/workbook-permission.service';
19
- import { WorksheetProtectionPointModel, WorksheetProtectionRuleModel } from '../../services/permission/worksheet-permission';
19
+ import { WorksheetProtectionPointModel } from '../../services/permission/worksheet-permission/worksheet-permission-point.model';
20
+ import { WorksheetProtectionRuleModel } from '../../services/permission/worksheet-permission/worksheet-permission-rule.model';
20
21
  export declare class SheetPermissionInitController extends Disposable {
21
22
  private readonly _univerInstanceService;
22
23
  private _permissionService;
@@ -40,5 +41,5 @@ export declare class SheetPermissionInitController extends Disposable {
40
41
  private _initWorksheetPermissionFromSnapshot;
41
42
  private _initUserChange;
42
43
  refreshPermission(unitId: string, permissionId: string): void;
43
- private _refreshPermissionByCollaCreate;
44
+ private _clearHistoryOnProtectionApplied;
44
45
  }
@@ -15,11 +15,11 @@
15
15
  */
16
16
  import type { AbsoluteRefType, BorderStyleTypes, BorderType, CellValue, CustomData, ICellData, IDocumentData, IObjectMatrixPrimitiveType, IRange, IStyleData, Nullable, Workbook, Worksheet } from '@univerjs/core';
17
17
  import type { AUTO_FILL_APPLY_TYPE, IMergeCellsUtilOptions, SplitDelimiterEnum } from '@univerjs/sheets';
18
- import type { IFacadeClearOptions } from './f-worksheet';
19
- import type { FHorizontalAlignment, FVerticalAlignment } from './utils';
20
18
  import { Dimension, ICommandService, ILogService, Injector, RichTextValue, TextStyleValue, WrapStrategy } from '@univerjs/core';
21
19
  import { FBaseInitialable } from '@univerjs/core/facade';
22
20
  import { FormulaDataModel } from '@univerjs/engine-formula';
21
+ import type { IFacadeClearOptions } from './f-worksheet';
22
+ import type { FHorizontalAlignment, FVerticalAlignment } from './utils';
23
23
  import { FRangePermission } from './permission/f-range-permission';
24
24
  export type FontLine = 'none' | 'underline' | 'line-through';
25
25
  export type FontStyle = 'normal' | 'italic';
@@ -256,6 +256,9 @@ export declare class FRange extends FBaseInitialable {
256
256
  /**
257
257
  * Return first cell style in this range.
258
258
  *
259
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
260
+ * {@link FRange.getCellStyles} once instead of calling this method for each cell.
261
+ *
259
262
  * @param {GetStyleType} [type] - The type of the style to get. 'row' means get the composed style of row, col and
260
263
  * default worksheet style. 'col' means get the composed style of col, row and default worksheet style.
261
264
  * 'cell' means get the style of cell without merging row style, col style and default worksheet style.
@@ -293,6 +296,10 @@ export declare class FRange extends FBaseInitialable {
293
296
  getCellStyles(type?: GetStyleType): Array<Array<TextStyleValue | null>>;
294
297
  /**
295
298
  * Return first cell value in this range
299
+ *
300
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
301
+ * {@link FRange.getValues} once instead of calling this method for each cell.
302
+ *
296
303
  * @returns {CellValue | null} The cell value
297
304
  * @example
298
305
  * ```ts
@@ -310,6 +317,10 @@ export declare class FRange extends FBaseInitialable {
310
317
  getValue(): CellValue | null;
311
318
  /**
312
319
  * Return first cell value in this range
320
+ *
321
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
322
+ * {@link FRange.getValues} once instead of calling this method for each cell.
323
+ *
313
324
  * @param {true} includeRichText Pass `true` to return a `RichTextValue` for rich-text content instead of plain text.
314
325
  * @returns {CellValue | RichTextValue | null} The cell value
315
326
  * @example
@@ -332,6 +343,10 @@ export declare class FRange extends FBaseInitialable {
332
343
  getValue(includeRichText: true): Nullable<CellValue | RichTextValue>;
333
344
  /**
334
345
  * Returns the raw value of the top-left cell in the range. Empty cells return `null`.
346
+ *
347
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
348
+ * {@link FRange.getRawValues} once instead of calling this method for each cell.
349
+ *
335
350
  * @returns {Nullable<CellValue>} The raw value of the cell. Returns `null` if the cell is empty.
336
351
  * @example
337
352
  * ```ts
@@ -353,6 +368,10 @@ export declare class FRange extends FBaseInitialable {
353
368
  getRawValue(): Nullable<CellValue>;
354
369
  /**
355
370
  * Returns the displayed value of the top-left cell in the range. The value is a String. Empty cells return an empty string.
371
+ *
372
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
373
+ * {@link FRange.getDisplayValues} once instead of calling this method for each cell.
374
+ *
356
375
  * @returns {string} The displayed value of the cell. Returns an empty string if the cell is empty.
357
376
  * @example
358
377
  * ```ts
@@ -491,6 +510,10 @@ export declare class FRange extends FBaseInitialable {
491
510
  getDisplayValues(): string[][];
492
511
  /**
493
512
  * Return first cell model data in this range
513
+ *
514
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
515
+ * {@link FRange.getCellDataGrid} once instead of calling this method for each cell.
516
+ *
494
517
  * @returns {ICellData | null} The cell model data
495
518
  * @example
496
519
  * ```ts
@@ -543,6 +566,10 @@ export declare class FRange extends FBaseInitialable {
543
566
  getValueAndRichTextValues(): Nullable<CellValue | RichTextValue>[][];
544
567
  /**
545
568
  * 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.
569
+ *
570
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
571
+ * {@link FRange.getFormulas} once instead of calling this method for each cell.
572
+ *
546
573
  * @returns {string} The formula for the cell.
547
574
  * @example
548
575
  * ```ts
@@ -569,6 +596,10 @@ export declare class FRange extends FBaseInitialable {
569
596
  getFormulas(): string[][];
570
597
  /**
571
598
  * Gets whether text wrapping is enabled for top-left cell in the range.
599
+ *
600
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
601
+ * {@link FRange.getWraps} once instead of calling this method for each cell.
602
+ *
572
603
  * @returns {boolean} whether text wrapping is enabled for the cell.
573
604
  * @example
574
605
  * ```ts
@@ -614,6 +645,10 @@ export declare class FRange extends FBaseInitialable {
614
645
  /**
615
646
  * Returns the horizontal alignment of the top-left cell as `left`, `center`, or `normal` (right alignment).
616
647
  * Default and other core alignment values return `general`, which is not accepted by `setHorizontalAlignment()`.
648
+ *
649
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
650
+ * {@link FRange.getHorizontalAlignments} once instead of calling this method for each cell.
651
+ *
617
652
  * @returns {string} The horizontal alignment of the text in the cell.
618
653
  * @example
619
654
  * ```ts
@@ -642,6 +677,10 @@ export declare class FRange extends FBaseInitialable {
642
677
  /**
643
678
  * Returns `top`, `middle`, or `bottom` for the top-left cell; unspecified alignment returns `general`.
644
679
  * `general` is a getter result and is not accepted by `setVerticalAlignment()`.
680
+ *
681
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
682
+ * {@link FRange.getVerticalAlignments} once instead of calling this method for each cell.
683
+ *
645
684
  * @returns {string} The vertical alignment of the text in the cell.
646
685
  * @example
647
686
  * ```ts
@@ -668,7 +707,12 @@ export declare class FRange extends FBaseInitialable {
668
707
  */
669
708
  getVerticalAlignments(): string[][];
670
709
  /**
671
- * Set custom meta data for first cell in current range.
710
+ * Set the same custom metadata for every cell in the current range.
711
+ *
712
+ * For the same metadata across multiple cells, call this method once on the entire target range.
713
+ * For different metadata per cell, prefer {@link FRange.setCustomMetaDatas} with a two-dimensional
714
+ * array matching the range dimensions instead of calling this method for each cell.
715
+ *
672
716
  * @param {CustomData} data The custom meta data
673
717
  * @returns {FRange} This range, for chaining
674
718
  * @example
@@ -702,6 +746,10 @@ export declare class FRange extends FBaseInitialable {
702
746
  setCustomMetaDatas(datas: CustomData[][]): FRange;
703
747
  /**
704
748
  * Returns the custom meta data for the cell at the start of this range.
749
+ *
750
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
751
+ * {@link FRange.getCustomMetaDatas} once instead of calling this method for each cell.
752
+ *
705
753
  * @returns {CustomData | null} The custom meta data
706
754
  * @example
707
755
  * ```ts
@@ -728,6 +776,10 @@ export declare class FRange extends FBaseInitialable {
728
776
  getCustomMetaDatas(): Nullable<CustomData>[][];
729
777
  /**
730
778
  * Sets basic border properties for the current range.
779
+ *
780
+ * For borders on multiple cells, call this method once on the full target range. Border types such as
781
+ * outer and inner are relative to that range, so applying them to each cell can produce different borders.
782
+ *
731
783
  * @param {BorderType} type The type of border to apply
732
784
  * @param {BorderStyleTypes} style The border style
733
785
  * @param {string} [color] Optional border color in CSS notation
@@ -744,6 +796,10 @@ export declare class FRange extends FBaseInitialable {
744
796
  setBorder(type: BorderType, style: BorderStyleTypes, color?: string): FRange;
745
797
  /**
746
798
  * Returns the background color of the top-left cell in the range.
799
+ *
800
+ * For multiple cells, create the target range with {@link FWorksheet.getRange} and call
801
+ * {@link FRange.getBackgrounds} once instead of calling this method for each cell.
802
+ *
747
803
  * @returns {string} The color code of the background.
748
804
  * @example
749
805
  * ```ts
@@ -770,6 +826,10 @@ export declare class FRange extends FBaseInitialable {
770
826
  getBackgrounds(): string[][];
771
827
  /**
772
828
  * Set background color for current range.
829
+ *
830
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
831
+ * and call this method once instead of calling it on each cell separately.
832
+ *
773
833
  * @param {string} color The background color
774
834
  * @returns {FRange} This range, for chaining
775
835
  * @example
@@ -784,6 +844,10 @@ export declare class FRange extends FBaseInitialable {
784
844
  setBackgroundColor(color: string): FRange;
785
845
  /**
786
846
  * Set background color for current range.
847
+ *
848
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
849
+ * and call this method once instead of calling it on each cell separately.
850
+ *
787
851
  * @param {string} color The background color
788
852
  * @returns {FRange} This range, for chaining
789
853
  * @example
@@ -798,6 +862,10 @@ export declare class FRange extends FBaseInitialable {
798
862
  setBackground(color: string): FRange;
799
863
  /**
800
864
  * Set rotation for text in current range.
865
+ *
866
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
867
+ * and call this method once instead of calling it on each cell separately.
868
+ *
801
869
  * @param {number} rotation - The rotation angle in degrees
802
870
  * @returns This range, for chaining
803
871
  * @example
@@ -813,6 +881,10 @@ export declare class FRange extends FBaseInitialable {
813
881
  /**
814
882
  * Sets the value or specified cell properties for every cell in this range.
815
883
  *
884
+ * For the same value or cell-data update across multiple cells, call this method once on the entire
885
+ * target range. For different values or updates per cell, prefer {@link FRange.setValues} with a
886
+ * two-dimensional array or sparse matrix instead of calling this method for each cell.
887
+ *
816
888
  * There are two input modes:
817
889
  *
818
890
  * - `CellValue` (`number`, `string`, or `boolean`): replaces the cell content. A string starting
@@ -824,10 +896,12 @@ export declare class FRange extends FBaseInitialable {
824
896
  * - `ICellData`: updates cell-data fields directly, for explicit control over `v` (value),
825
897
  * `f` (formula), `p` (rich text), `t` (value type), and `s` (style). The object bypasses the
826
898
  * formula and formatted-number parsing above: `{ v: '=SUM(A1:A2)' }` does not set a formula;
827
- * use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Omitted content fields are not
828
- * automatically cleared, so use `f: null` and `p: null` when replacing a formula or rich text
829
- * with `v`. Use `v: null` to clear the stored value. Supplied style properties are merged into
830
- * the existing style; `s: null` clears the style.
899
+ * use `{ f: '=SUM(A1:A2)', v: null, p: null }` instead. Writing `v` or `p` without `f` and
900
+ * `si` replaces the target formula, as writing a scalar value does, and writing `f` without
901
+ * `si` disassociates the cell from its previous shared formula. Rich text is still not
902
+ * cleared by a value write, so pass `p: null` when replacing rich text with `v`. Use
903
+ * `v: null` to clear the stored value. Supplied style properties are merged into the existing
904
+ * style; `s: null` clears the style.
831
905
  *
832
906
  * In both modes, the stored value is converted according to its cell type. Unless an `ICellData`
833
907
  * input supplies `t`, the type is inferred from the value, number format, and existing cell type.
@@ -866,6 +940,10 @@ export declare class FRange extends FBaseInitialable {
866
940
  /**
867
941
  * Sets the value or specified cell properties of the top-left cell in this range.
868
942
  * Uses the same scalar parsing and cell-data update rules as {@link FRange.setValue}.
943
+ *
944
+ * For multiple cells, prefer {@link FRange.setValues} on the target range with a two-dimensional array
945
+ * or sparse matrix. To apply the same value to the entire range, use {@link FRange.setValue} once.
946
+ *
869
947
  * @param {CellValue | ICellData} value The scalar content or cell-data update to apply to the top-left cell only.
870
948
  * @returns {FRange} This range, for chaining
871
949
  * @example
@@ -883,6 +961,10 @@ export declare class FRange extends FBaseInitialable {
883
961
  setValueForCell(value: CellValue | ICellData): FRange;
884
962
  /**
885
963
  * Set the rich text value for the cell at the start of this range.
964
+ *
965
+ * For multiple cells, prefer {@link FRange.setRichTextValues} on the target range with a two-dimensional
966
+ * array matching its dimensions instead of calling this method for each cell.
967
+ *
886
968
  * @param {RichTextValue | IDocumentData} value The rich text value
887
969
  * @returns {FRange} The range
888
970
  * @example
@@ -932,6 +1014,10 @@ export declare class FRange extends FBaseInitialable {
932
1014
  * Set the cell wrap of the given range.
933
1015
  * Pass `true` to set `WrapStrategy.WRAP`, or `false` to reset to `WrapStrategy.UNSPECIFIED`.
934
1016
  * Use `setWrapStrategy()` to explicitly select clipping or overflow behavior.
1017
+ *
1018
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1019
+ * and call this method once instead of calling it on each cell separately.
1020
+ *
935
1021
  * @param {boolean} isWrapEnabled Whether to enable wrap
936
1022
  * @returns {FRange} this range, for chaining
937
1023
  * @example
@@ -947,6 +1033,10 @@ export declare class FRange extends FBaseInitialable {
947
1033
  setWrap(isWrapEnabled: boolean): FRange;
948
1034
  /**
949
1035
  * Sets whether cells shrink their font size to fit the cell width.
1036
+ *
1037
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1038
+ * and call this method once instead of calling it on each cell separately.
1039
+ *
950
1040
  * @param {boolean} enabled Whether to enable shrink-to-fit for this range.
951
1041
  * @returns {FRange} This range, for chaining.
952
1042
  * @example
@@ -957,6 +1047,10 @@ export declare class FRange extends FBaseInitialable {
957
1047
  setShrinkToFit(enabled: boolean): FRange;
958
1048
  /**
959
1049
  * Sets the text wrapping strategy for the cells in the range.
1050
+ *
1051
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1052
+ * and call this method once instead of calling it on each cell separately.
1053
+ *
960
1054
  * @param {WrapStrategy} strategy The text wrapping strategy
961
1055
  * @returns {FRange} this range, for chaining
962
1056
  * @example
@@ -972,6 +1066,10 @@ export declare class FRange extends FBaseInitialable {
972
1066
  setWrapStrategy(strategy: WrapStrategy): FRange;
973
1067
  /**
974
1068
  * Set the vertical (top to bottom) alignment for the given range (top/middle/bottom).
1069
+ *
1070
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1071
+ * and call this method once instead of calling it on each cell separately.
1072
+ *
975
1073
  * @param {FVerticalAlignment} alignment The vertical alignment
976
1074
  * @returns {FRange} this range, for chaining
977
1075
  * @example
@@ -987,6 +1085,10 @@ export declare class FRange extends FBaseInitialable {
987
1085
  /**
988
1086
  * Sets the horizontal alignment for the range using `left`, `center`, or `normal`.
989
1087
  * These parameter names follow Google Apps Script. In Univer, `normal` means right alignment; `right` is not accepted.
1088
+ *
1089
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1090
+ * and call this method once instead of calling it on each cell separately.
1091
+ *
990
1092
  * @param {FHorizontalAlignment} alignment The horizontal alignment: `left`, `center`, or `normal` (right alignment).
991
1093
  * @returns {FRange} this range, for chaining
992
1094
  * @example
@@ -1003,6 +1105,10 @@ export declare class FRange extends FBaseInitialable {
1003
1105
  * Sets cell values or specified cell properties using an array or a sparse matrix.
1004
1106
  * Each entry follows the scalar parsing and cell-data update rules of {@link FRange.setValue}.
1005
1107
  *
1108
+ * For multiple cells, pass all values or cell-data updates in one call instead of calling this method
1109
+ * on individual cell ranges. Use a matching two-dimensional array for a rectangle, or a sparse matrix
1110
+ * with absolute worksheet coordinates for non-contiguous cells.
1111
+ *
1006
1112
  * A two-dimensional array is relative to this range's top-left cell and must match its dimensions.
1007
1113
  * A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries
1008
1114
  * are updated; matrix coordinates are not offset by or clipped to this range.
@@ -1029,6 +1135,10 @@ export declare class FRange extends FBaseInitialable {
1029
1135
  setValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>): FRange;
1030
1136
  /**
1031
1137
  * Sets the font weight for the given range (normal/bold),
1138
+ *
1139
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1140
+ * and call this method once instead of calling it on each cell separately.
1141
+ *
1032
1142
  * @param {FontWeight|null} fontWeight The font weight, either 'normal' or 'bold'; a null value resets the font weight.
1033
1143
  * @returns {FRange} This range, for chaining
1034
1144
  * @example
@@ -1043,6 +1153,10 @@ export declare class FRange extends FBaseInitialable {
1043
1153
  setFontWeight(fontWeight: FontWeight | null): this;
1044
1154
  /**
1045
1155
  * Sets the font style for the given range ('italic' or 'normal').
1156
+ *
1157
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1158
+ * and call this method once instead of calling it on each cell separately.
1159
+ *
1046
1160
  * @param {FontStyle|null} fontStyle The font style, either 'italic' or 'normal'; a null value resets the font style.
1047
1161
  * @returns {FRange} This range, for chaining
1048
1162
  * @example
@@ -1057,6 +1171,10 @@ export declare class FRange extends FBaseInitialable {
1057
1171
  setFontStyle(fontStyle: FontStyle | null): this;
1058
1172
  /**
1059
1173
  * Sets the font line style of the given range ('underline', 'line-through', or 'none').
1174
+ *
1175
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1176
+ * and call this method once instead of calling it on each cell separately.
1177
+ *
1060
1178
  * @param {FontLine|null} fontLine The font line style, either 'underline', 'line-through', or 'none'; a null value resets the font line style.
1061
1179
  * @returns {FRange} This range, for chaining
1062
1180
  * @example
@@ -1083,6 +1201,10 @@ export declare class FRange extends FBaseInitialable {
1083
1201
  private _setFontStrikethrough;
1084
1202
  /**
1085
1203
  * Sets the font family, such as "Arial" or "Helvetica".
1204
+ *
1205
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1206
+ * and call this method once instead of calling it on each cell separately.
1207
+ *
1086
1208
  * @param {string|null} fontFamily The font family to set; a null value resets the font family.
1087
1209
  * @returns {FRange} This range, for chaining
1088
1210
  * @example
@@ -1097,6 +1219,10 @@ export declare class FRange extends FBaseInitialable {
1097
1219
  setFontFamily(fontFamily: string | null): this;
1098
1220
  /**
1099
1221
  * Sets the font size, with the size being the point size to use.
1222
+ *
1223
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1224
+ * and call this method once instead of calling it on each cell separately.
1225
+ *
1100
1226
  * @param {number|null} size A font size in point size. A null value resets the font size.
1101
1227
  * @returns {FRange} This range, for chaining
1102
1228
  * @example
@@ -1111,6 +1237,10 @@ export declare class FRange extends FBaseInitialable {
1111
1237
  setFontSize(size: number | null): this;
1112
1238
  /**
1113
1239
  * Sets the font color in CSS notation (such as '#ffffff' or 'white').
1240
+ *
1241
+ * To apply the same setting to multiple cells, create the full target range with {@link FWorksheet.getRange}
1242
+ * and call this method once instead of calling it on each cell separately.
1243
+ *
1114
1244
  * @param {string|null} color The font color in CSS notation (such as '#ffffff' or 'white'); a null value resets the color.
1115
1245
  * @returns {FRange} This range, for chaining
1116
1246
  * @example
@@ -1456,6 +1586,10 @@ export declare class FRange extends FBaseInitialable {
1456
1586
  /**
1457
1587
  * Clears the range content and formatting, or only one of them as specified by the options.
1458
1588
  * Both content and formatting are cleared when both flags are true or both are false.
1589
+ *
1590
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
1591
+ * method once instead of clearing each cell separately.
1592
+ *
1459
1593
  * @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
1460
1594
  * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. Effective only when `formatOnly` is false. Defaults to false.
1461
1595
  * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
@@ -1477,6 +1611,10 @@ export declare class FRange extends FBaseInitialable {
1477
1611
  clear(options?: IFacadeClearOptions): FRange;
1478
1612
  /**
1479
1613
  * Clears content of the range, while preserving formatting information.
1614
+ *
1615
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
1616
+ * method once instead of clearing each cell separately.
1617
+ *
1480
1618
  * @returns {FRange} This range, for chaining.
1481
1619
  * @example
1482
1620
  * ```typescript
@@ -1492,6 +1630,10 @@ export declare class FRange extends FBaseInitialable {
1492
1630
  clearContent(): FRange;
1493
1631
  /**
1494
1632
  * Clears formatting information of the range, while preserving contents.
1633
+ *
1634
+ * To clear multiple cells, create the full target range with {@link FWorksheet.getRange} and call this
1635
+ * method once instead of clearing each cell separately.
1636
+ *
1495
1637
  * @returns {FRange} This range, for chaining.
1496
1638
  * @example
1497
1639
  * ```typescript
@@ -1717,6 +1859,11 @@ export declare class FRange extends FBaseInitialable {
1717
1859
  offset(rowOffset: number, columnOffset: number, numRows: number): FRange;
1718
1860
  /**
1719
1861
  * Updates the formula for this range. The given formula must be in A1 notation.
1862
+ *
1863
+ * For the same formula string across multiple cells, call this method once on the entire target range.
1864
+ * For different formulas per cell, prefer {@link FRange.setFormulas} with a two-dimensional array
1865
+ * matching the range dimensions instead of calling this method for each cell.
1866
+ *
1720
1867
  * @param {string} formula - A string representing the formula to set for the cell.
1721
1868
  * @returns {FRange} This range instance for chaining.
1722
1869
  * @example