@univerjs/sheets 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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
@@ -868,6 +940,10 @@ export declare class FRange extends FBaseInitialable {
868
940
  /**
869
941
  * Sets the value or specified cell properties of the top-left cell in this range.
870
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
+ *
871
947
  * @param {CellValue | ICellData} value The scalar content or cell-data update to apply to the top-left cell only.
872
948
  * @returns {FRange} This range, for chaining
873
949
  * @example
@@ -885,6 +961,10 @@ export declare class FRange extends FBaseInitialable {
885
961
  setValueForCell(value: CellValue | ICellData): FRange;
886
962
  /**
887
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
+ *
888
968
  * @param {RichTextValue | IDocumentData} value The rich text value
889
969
  * @returns {FRange} The range
890
970
  * @example
@@ -934,6 +1014,10 @@ export declare class FRange extends FBaseInitialable {
934
1014
  * Set the cell wrap of the given range.
935
1015
  * Pass `true` to set `WrapStrategy.WRAP`, or `false` to reset to `WrapStrategy.UNSPECIFIED`.
936
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
+ *
937
1021
  * @param {boolean} isWrapEnabled Whether to enable wrap
938
1022
  * @returns {FRange} this range, for chaining
939
1023
  * @example
@@ -949,6 +1033,10 @@ export declare class FRange extends FBaseInitialable {
949
1033
  setWrap(isWrapEnabled: boolean): FRange;
950
1034
  /**
951
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
+ *
952
1040
  * @param {boolean} enabled Whether to enable shrink-to-fit for this range.
953
1041
  * @returns {FRange} This range, for chaining.
954
1042
  * @example
@@ -959,6 +1047,10 @@ export declare class FRange extends FBaseInitialable {
959
1047
  setShrinkToFit(enabled: boolean): FRange;
960
1048
  /**
961
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
+ *
962
1054
  * @param {WrapStrategy} strategy The text wrapping strategy
963
1055
  * @returns {FRange} this range, for chaining
964
1056
  * @example
@@ -974,6 +1066,10 @@ export declare class FRange extends FBaseInitialable {
974
1066
  setWrapStrategy(strategy: WrapStrategy): FRange;
975
1067
  /**
976
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
+ *
977
1073
  * @param {FVerticalAlignment} alignment The vertical alignment
978
1074
  * @returns {FRange} this range, for chaining
979
1075
  * @example
@@ -989,6 +1085,10 @@ export declare class FRange extends FBaseInitialable {
989
1085
  /**
990
1086
  * Sets the horizontal alignment for the range using `left`, `center`, or `normal`.
991
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
+ *
992
1092
  * @param {FHorizontalAlignment} alignment The horizontal alignment: `left`, `center`, or `normal` (right alignment).
993
1093
  * @returns {FRange} this range, for chaining
994
1094
  * @example
@@ -1005,6 +1105,10 @@ export declare class FRange extends FBaseInitialable {
1005
1105
  * Sets cell values or specified cell properties using an array or a sparse matrix.
1006
1106
  * Each entry follows the scalar parsing and cell-data update rules of {@link FRange.setValue}.
1007
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
+ *
1008
1112
  * A two-dimensional array is relative to this range's top-left cell and must match its dimensions.
1009
1113
  * A sparse matrix uses absolute, zero-based worksheet row and column keys. Only supplied entries
1010
1114
  * are updated; matrix coordinates are not offset by or clipped to this range.
@@ -1031,6 +1135,10 @@ export declare class FRange extends FBaseInitialable {
1031
1135
  setValues(value: CellValue[][] | IObjectMatrixPrimitiveType<CellValue> | ICellData[][] | IObjectMatrixPrimitiveType<ICellData>): FRange;
1032
1136
  /**
1033
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
+ *
1034
1142
  * @param {FontWeight|null} fontWeight The font weight, either 'normal' or 'bold'; a null value resets the font weight.
1035
1143
  * @returns {FRange} This range, for chaining
1036
1144
  * @example
@@ -1045,6 +1153,10 @@ export declare class FRange extends FBaseInitialable {
1045
1153
  setFontWeight(fontWeight: FontWeight | null): this;
1046
1154
  /**
1047
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
+ *
1048
1160
  * @param {FontStyle|null} fontStyle The font style, either 'italic' or 'normal'; a null value resets the font style.
1049
1161
  * @returns {FRange} This range, for chaining
1050
1162
  * @example
@@ -1059,6 +1171,10 @@ export declare class FRange extends FBaseInitialable {
1059
1171
  setFontStyle(fontStyle: FontStyle | null): this;
1060
1172
  /**
1061
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
+ *
1062
1178
  * @param {FontLine|null} fontLine The font line style, either 'underline', 'line-through', or 'none'; a null value resets the font line style.
1063
1179
  * @returns {FRange} This range, for chaining
1064
1180
  * @example
@@ -1085,6 +1201,10 @@ export declare class FRange extends FBaseInitialable {
1085
1201
  private _setFontStrikethrough;
1086
1202
  /**
1087
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
+ *
1088
1208
  * @param {string|null} fontFamily The font family to set; a null value resets the font family.
1089
1209
  * @returns {FRange} This range, for chaining
1090
1210
  * @example
@@ -1099,6 +1219,10 @@ export declare class FRange extends FBaseInitialable {
1099
1219
  setFontFamily(fontFamily: string | null): this;
1100
1220
  /**
1101
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
+ *
1102
1226
  * @param {number|null} size A font size in point size. A null value resets the font size.
1103
1227
  * @returns {FRange} This range, for chaining
1104
1228
  * @example
@@ -1113,6 +1237,10 @@ export declare class FRange extends FBaseInitialable {
1113
1237
  setFontSize(size: number | null): this;
1114
1238
  /**
1115
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
+ *
1116
1244
  * @param {string|null} color The font color in CSS notation (such as '#ffffff' or 'white'); a null value resets the color.
1117
1245
  * @returns {FRange} This range, for chaining
1118
1246
  * @example
@@ -1458,6 +1586,10 @@ export declare class FRange extends FBaseInitialable {
1458
1586
  /**
1459
1587
  * Clears the range content and formatting, or only one of them as specified by the options.
1460
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
+ *
1461
1593
  * @param {IFacadeClearOptions} [options] - Options for clearing the range. If not provided, the contents and formatting are cleared both.
1462
1594
  * @param {boolean} [options.contentsOnly] - If true, the contents of the range are cleared. Effective only when `formatOnly` is false. Defaults to false.
1463
1595
  * @param {boolean} [options.formatOnly] - Clears only formatting when true and `contentsOnly` is false. Defaults to false.
@@ -1479,6 +1611,10 @@ export declare class FRange extends FBaseInitialable {
1479
1611
  clear(options?: IFacadeClearOptions): FRange;
1480
1612
  /**
1481
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
+ *
1482
1618
  * @returns {FRange} This range, for chaining.
1483
1619
  * @example
1484
1620
  * ```typescript
@@ -1494,6 +1630,10 @@ export declare class FRange extends FBaseInitialable {
1494
1630
  clearContent(): FRange;
1495
1631
  /**
1496
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
+ *
1497
1637
  * @returns {FRange} This range, for chaining.
1498
1638
  * @example
1499
1639
  * ```typescript
@@ -1719,6 +1859,11 @@ export declare class FRange extends FBaseInitialable {
1719
1859
  offset(rowOffset: number, columnOffset: number, numRows: number): FRange;
1720
1860
  /**
1721
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
+ *
1722
1867
  * @param {string} formula - A string representing the formula to set for the cell.
1723
1868
  * @returns {FRange} This range instance for chaining.
1724
1869
  * @example
@@ -14,11 +14,11 @@
14
14
  * limitations under the License.
15
15
  */
16
16
  import type { CellValue, CustomData, IColumnRange, IFreeze, IObjectArrayPrimitiveType, IRange, IRowRange, IStyleData, Nullable, Workbook, Worksheet } from '@univerjs/core';
17
- import type { FDefinedName } from './f-defined-name';
18
- import type { FWorkbook } from './f-workbook';
19
17
  import { BooleanNumber, ICommandService, ILogService, Injector, WorksheetHiddenState } from '@univerjs/core';
20
18
  import { FBaseInitialable } from '@univerjs/core/facade';
21
19
  import { SheetsSelectionsService } from '@univerjs/sheets';
20
+ import type { FDefinedName } from './f-defined-name';
21
+ import type { FWorkbook } from './f-workbook';
22
22
  import { FRange } from './f-range';
23
23
  import { FSelection } from './f-selection';
24
24
  import { FWorksheetPermission } from './permission/f-worksheet-permission';
@@ -312,6 +312,10 @@ export declare class FWorksheet extends FBaseInitialable {
312
312
  getMaxRows(): number;
313
313
  /**
314
314
  * Inserts a row after the given row position.
315
+ *
316
+ * To insert multiple rows, prefer {@link FWorksheet.insertRowsAfter} with the full count
317
+ * instead of repeatedly calling this method.
318
+ *
315
319
  * @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`.
316
320
  * @returns {FWorksheet} This sheet, for chaining.
317
321
  * @example
@@ -327,6 +331,10 @@ export declare class FWorksheet extends FBaseInitialable {
327
331
  insertRowAfter(afterPosition: number): FWorksheet;
328
332
  /**
329
333
  * Inserts a row before the given row position.
334
+ *
335
+ * To insert multiple rows, prefer {@link FWorksheet.insertRowsBefore} with the full count
336
+ * instead of repeatedly calling this method.
337
+ *
330
338
  * @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`.
331
339
  * @returns {FWorksheet} This sheet, for chaining.
332
340
  * @example
@@ -342,6 +350,10 @@ export declare class FWorksheet extends FBaseInitialable {
342
350
  insertRowBefore(beforePosition: number): FWorksheet;
343
351
  /**
344
352
  * Inserts one or more consecutive blank rows in a sheet starting at the specified location.
353
+ *
354
+ * For multiple consecutive rows, pass the full `numRows` in one call instead of looping
355
+ * with the default count of one.
356
+ *
345
357
  * @param {number} rowIndex - The existing row before which rows are inserted. The index is zero-based and must be between 0 and `getMaxRows() - 1`.
346
358
  * @param {number} [numRows] - The positive number of rows to insert.
347
359
  * @returns {FWorksheet} This sheet, for chaining.
@@ -390,6 +402,11 @@ export declare class FWorksheet extends FBaseInitialable {
390
402
  insertRowsBefore(beforePosition: number, howMany: number): FWorksheet;
391
403
  /**
392
404
  * Deletes the row at the given row position.
405
+ *
406
+ * For consecutive rows, prefer {@link FWorksheet.deleteRows} with the full count. For
407
+ * non-contiguous rows, use {@link FWorksheet.deleteRowsByPoints} so shifting indices are handled
408
+ * without a manual loop over this method.
409
+ *
393
410
  * @param {number} rowPosition - The position of the row, starting at 0 for the first row.
394
411
  * @returns {FWorksheet} This sheet, for chaining.
395
412
  * @example
@@ -452,6 +469,10 @@ export declare class FWorksheet extends FBaseInitialable {
452
469
  moveRows(rowSpec: FRange, destinationIndex: number): FWorksheet;
453
470
  /**
454
471
  * Hides the rows in the given range.
472
+ *
473
+ * For multiple rows, pass an FRange spanning all target rows in one call. If you already have
474
+ * a starting index and count, use {@link FWorksheet.hideRows} instead of calling this method for each row.
475
+ *
455
476
  * @param {FRange} row - The row range to hide.
456
477
  * @returns {FWorksheet} This sheet, for chaining.
457
478
  * @example
@@ -469,6 +490,10 @@ export declare class FWorksheet extends FBaseInitialable {
469
490
  hideRow(row: FRange): FWorksheet;
470
491
  /**
471
492
  * Hides one or more consecutive rows starting at the given index. Use 0-index for this method
493
+ *
494
+ * For multiple consecutive rows, pass the full `numRow` in one call instead of looping
495
+ * with the default count of one.
496
+ *
472
497
  * @param {number} rowIndex - The starting index of the rows to hide
473
498
  * @param {number} [numRow] - The number of rows to hide
474
499
  * @returns {FWorksheet} This sheet, for chaining.
@@ -485,6 +510,10 @@ export declare class FWorksheet extends FBaseInitialable {
485
510
  hideRows(rowIndex: number, numRow?: number): FWorksheet;
486
511
  /**
487
512
  * Make the row in the given range visible.
513
+ *
514
+ * For multiple rows, pass an FRange spanning all target rows in one call. If you already have
515
+ * a starting index and count, use {@link FWorksheet.showRows} instead of calling this method for each row.
516
+ *
488
517
  * @param {FRange} row - The range to unhide, if hidden.
489
518
  * @returns {FWorksheet} This sheet, for chaining.
490
519
  * @example
@@ -502,6 +531,10 @@ export declare class FWorksheet extends FBaseInitialable {
502
531
  unhideRow(row: FRange): FWorksheet;
503
532
  /**
504
533
  * Unhides one or more consecutive rows starting at the given zero-based index.
534
+ *
535
+ * For multiple consecutive rows, pass the full `numRows` in one call instead of looping
536
+ * with the default count of one.
537
+ *
505
538
  * @param {number} rowIndex - The starting index of the rows
506
539
  * @param {number} [numRows] - The number of rows
507
540
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -518,6 +551,10 @@ export declare class FWorksheet extends FBaseInitialable {
518
551
  showRows(rowIndex: number, numRows?: number): FWorksheet;
519
552
  /**
520
553
  * 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).
554
+ *
555
+ * For the same height across consecutive rows, prefer {@link FWorksheet.setRowHeights} with the full
556
+ * row count instead of calling this method for each row.
557
+ *
521
558
  * @param {number} rowPosition - The row position to change.
522
559
  * @param {number} height - The height in pixels to set it to.
523
560
  * @returns {FWorksheet} This worksheet instance for chaining
@@ -636,6 +673,10 @@ export declare class FWorksheet extends FBaseInitialable {
636
673
  setRowCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet;
637
674
  /**
638
675
  * Inserts a column after the given column position.
676
+ *
677
+ * To insert multiple columns, prefer {@link FWorksheet.insertColumnsAfter} with the full count
678
+ * instead of repeatedly calling this method.
679
+ *
639
680
  * @param {number} afterPosition - The column after which the new column should be added, starting at 0 for the first column
640
681
  * @returns {FWorksheet} This worksheet instance for chaining
641
682
  * @example
@@ -651,6 +692,10 @@ export declare class FWorksheet extends FBaseInitialable {
651
692
  insertColumnAfter(afterPosition: number): FWorksheet;
652
693
  /**
653
694
  * Inserts a column before the given column position.
695
+ *
696
+ * To insert multiple columns, prefer {@link FWorksheet.insertColumnsBefore} with the full count
697
+ * instead of repeatedly calling this method.
698
+ *
654
699
  * @param {number} beforePosition - The column before which the new column should be added, starting at 0 for the first column
655
700
  * @returns {FWorksheet} This worksheet instance for chaining
656
701
  * @example
@@ -666,6 +711,10 @@ export declare class FWorksheet extends FBaseInitialable {
666
711
  insertColumnBefore(beforePosition: number): FWorksheet;
667
712
  /**
668
713
  * Inserts one or more consecutive blank columns in a sheet starting at the specified location.
714
+ *
715
+ * For multiple consecutive columns, pass the full `numColumns` in one call instead of looping
716
+ * with the default count of one.
717
+ *
669
718
  * @param {number} columnIndex - The index indicating where to insert a column, starting at 0 for the first column
670
719
  * @param {number} [numColumns] - The number of columns to insert
671
720
  * @returns {FWorksheet} This sheet, for chaining
@@ -714,6 +763,11 @@ export declare class FWorksheet extends FBaseInitialable {
714
763
  insertColumnsBefore(beforePosition: number, howMany: number): FWorksheet;
715
764
  /**
716
765
  * Deletes the column at the given column position.
766
+ *
767
+ * For consecutive columns, prefer {@link FWorksheet.deleteColumns} with the full count. For
768
+ * non-contiguous columns, use {@link FWorksheet.deleteColumnsByPoints} so shifting indices are handled
769
+ * without a manual loop over this method.
770
+ *
717
771
  * @param {number} columnPosition - The position of the column, starting at 0 for the first column
718
772
  * @returns {FWorksheet} This sheet, for chaining
719
773
  * @example
@@ -776,6 +830,10 @@ export declare class FWorksheet extends FBaseInitialable {
776
830
  moveColumns(columnSpec: FRange, destinationIndex: number): FWorksheet;
777
831
  /**
778
832
  * Hides the column or columns in the given range.
833
+ *
834
+ * For multiple columns, pass an FRange spanning all target columns in one call. If you already have
835
+ * a starting index and count, use {@link FWorksheet.hideColumns} instead of calling this method for each column.
836
+ *
779
837
  * @param {FRange} column - The column range to hide
780
838
  * @returns {FWorksheet} This sheet, for chaining
781
839
  * @example
@@ -793,6 +851,10 @@ export declare class FWorksheet extends FBaseInitialable {
793
851
  hideColumn(column: FRange): FWorksheet;
794
852
  /**
795
853
  * Hides one or more consecutive columns starting at the given index. Use 0-index for this method
854
+ *
855
+ * For multiple consecutive columns, pass the full `numColumn` in one call instead of looping
856
+ * with the default count of one.
857
+ *
796
858
  * @param {number} columnIndex - The starting index of the columns to hide
797
859
  * @param {number} [numColumn] - The number of columns to hide
798
860
  * @returns {FWorksheet} This sheet, for chaining
@@ -809,6 +871,10 @@ export declare class FWorksheet extends FBaseInitialable {
809
871
  hideColumns(columnIndex: number, numColumn?: number): FWorksheet;
810
872
  /**
811
873
  * Show the column in the given range.
874
+ *
875
+ * For multiple columns, pass an FRange spanning all target columns in one call. If you already have
876
+ * a starting index and count, use {@link FWorksheet.showColumns} instead of calling this method for each column.
877
+ *
812
878
  * @param {FRange} column - The range to unhide, if hidden
813
879
  * @returns {FWorksheet} This sheet, for chaining
814
880
  * @example
@@ -826,6 +892,10 @@ export declare class FWorksheet extends FBaseInitialable {
826
892
  unhideColumn(column: FRange): FWorksheet;
827
893
  /**
828
894
  * Show one or more consecutive columns starting at the given index. Use 0-index for this method
895
+ *
896
+ * For multiple consecutive columns, pass the full `numColumns` in one call instead of looping
897
+ * with the default count of one.
898
+ *
829
899
  * @param {number} columnIndex - The starting index of the columns to unhide
830
900
  * @param {number} [numColumns] - The number of columns to unhide
831
901
  * @returns {FWorksheet} This sheet, for chaining
@@ -842,6 +912,10 @@ export declare class FWorksheet extends FBaseInitialable {
842
912
  showColumns(columnIndex: number, numColumns?: number): FWorksheet;
843
913
  /**
844
914
  * Sets the width of the given column in pixels.
915
+ *
916
+ * For the same width across consecutive columns, prefer {@link FWorksheet.setColumnWidths} with the
917
+ * full column count instead of calling this method for each column.
918
+ *
845
919
  * @param {number} columnPosition - The position of the given column to set
846
920
  * @param {number} width - The width in pixels to set it to
847
921
  * @returns {FWorksheet} This sheet, for chaining
@@ -14,11 +14,11 @@
14
14
  * limitations under the License.
15
15
  */
16
16
  import type { IMutationInfo } from '@univerjs/core';
17
+ import { Disposable, DisposableCollection, ICommandService, IUniverInstanceService } from '@univerjs/core';
17
18
  import type { IAddRangeProtectionMutationParams } from '../../../commands/mutations/add-range-protection.mutation';
18
19
  import type { IDeleteRangeProtectionMutationParams } from '../../../commands/mutations/delete-range-protection.mutation';
19
20
  import type { ISetRangeProtectionMutationParams } from '../../../commands/mutations/set-range-protection.mutation';
20
21
  import type { EffectRefRangeParams } from '../../ref-range/type';
21
- import { Disposable, DisposableCollection, ICommandService, IUniverInstanceService } from '@univerjs/core';
22
22
  import { RangeProtectionRenderModel } from '../../../models/range-protection-render.model';
23
23
  import { RangeProtectionRuleModel } from '../../../models/range-protection-rule.model';
24
24
  import { RangeProtectionCache } from '../../../models/range-protection.cache';
@@ -57,6 +57,15 @@ export declare class RangeProtectionRefRangeService extends Disposable {
57
57
  private _getRefRangeMutationsByMoveCols;
58
58
  private _correctPermissionRange;
59
59
  private _checkIsRightRange;
60
+ private _coversAllRows;
61
+ private _coversAllColumns;
62
+ /**
63
+ * A whole column/row/sheet protection range always covers that axis, so inserting or removing
64
+ * rows/columns there only moves its end instead of shifting it.
65
+ *
66
+ * @returns `true` when the range was adjusted as a whole range
67
+ */
68
+ private _adjustWholeRangeForStructuralChange;
60
69
  private _initReBuildCache;
61
70
  private _initRemoveSheet;
62
71
  }
@@ -14,6 +14,7 @@
14
14
  * limitations under the License.
15
15
  */
16
16
  import type { IAccessor, ICommandInfo, IMutationInfo, IRange, Nullable } from '@univerjs/core';
17
+ import { RANGE_TYPE } from '@univerjs/core';
17
18
  import type { IInsertColMutationParams, IInsertRowMutationParams, IRemoveColMutationParams, IRemoveRowsMutationParams, IRemoveSheetMutationParams } from '../../basics';
18
19
  import type { IInsertColCommandParams, IInsertRowCommandParams } from '../../commands/commands/insert-row-col.command';
19
20
  import type { IRemoveRowColCommandInterceptParams } from '../../commands/commands/remove-row-col.command';
@@ -22,7 +23,6 @@ import type { IMoveColumnsMutationParams, IMoveRowsMutationParams } from '../../
22
23
  import type { ISheetCommandSharedParams } from '../../commands/utils/interface';
23
24
  import type { SheetsSelectionsService } from '../selections/selection.service';
24
25
  import type { EffectRefRangeParams, IDeleteRangeMoveLeftCommand, IDeleteRangeMoveUpCommand, IInsertColCommand, IInsertRangeMoveDownCommand, IInsertRangeMoveRightCommand, IInsertRowCommand, IMoveColsCommand, IMoveRangeCommand, IMoveRowsCommand, IOperator, IRemoveRowColCommand, IReorderRangeCommand } from './type';
25
- import { RANGE_TYPE } from '@univerjs/core';
26
26
  export declare const handleRangeTypeInput: (range: IRange) => {
27
27
  unitId?: string;
28
28
  sheetId?: string;
@@ -105,7 +105,22 @@ export declare const handleRemoveRowCommon: (param: IRemoveRowColCommandIntercep
105
105
  startRow: number;
106
106
  endRow: number;
107
107
  }[];
108
+ /**
109
+ * A ref range follows the data it covers, whichever command entry produced the insertion:
110
+ * inserting above the range shifts it down, inserting inside the range expands it, and
111
+ * inserting below the range leaves it untouched.
112
+ *
113
+ * `direction` only decides which row the inserted cells inherit styles and height from, so it
114
+ * is deliberately ignored here: two entry points that insert a row at the same position must
115
+ * return the same range. This matches `handleBaseInsertRange`, which serves the mutation based
116
+ * ref-range paths, and the collaboration transform algorithms, which cannot supply a direction
117
+ * at all.
118
+ */
108
119
  export declare const handleInsertRowCommon: (info: ICommandInfo<IInsertRowCommandParams>, targetRange: IRange) => IRange[];
120
+ /**
121
+ * Column counterpart of {@link handleInsertRowCommon}: a ref range follows the data it covers,
122
+ * so `direction` is deliberately ignored here as well.
123
+ */
109
124
  export declare const handleInsertColCommon: (info: ICommandInfo<IInsertColCommandParams>, targetRange: IRange) => IRange[];
110
125
  export declare const runRefRangeMutations: (operators: IOperator[], range: IRange) => IRange | null;
111
126
  export declare const handleDefaultRangeChangeWithEffectRefCommands: (range: IRange, commandInfo: ICommandInfo) => IRange | null;