feat: supplement facade example (#4799)

dream-num · Mar 9, 2025 · c43b0c9 · c43b0c9
1 parent c3574ee
commit c43b0c9
Show file tree

Hide file tree

Showing 8 changed files with 98 additions and 59 deletions.
diff --git a/packages/core/src/facade/f-univer.ts b/packages/core/src/facade/f-univer.ts
@@ -298,7 +298,7 @@ export class FUniver extends Disposable {
      *
      * @example
      * ```ts
-     * univerAPI.undo();
+     * await univerAPI.undo();
      * ```
      */
     undo(): Promise<boolean> {
@@ -311,7 +311,7 @@ export class FUniver extends Disposable {
      *
      * @example
      * ```ts
-     * univerAPI.redo();
+     * await univerAPI.redo();
      * ```
      */
     redo(): Promise<boolean> {

diff --git a/packages/sheets-filter/src/facade/f-filter.ts b/packages/sheets-filter/src/facade/f-filter.ts
@@ -44,7 +44,9 @@ export class FFilter {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
-     * const fRange = fWorksheet.getRange('A1:D10');
+     *
+     * // Set some values of the range C1:F10
+     * const fRange = fWorksheet.getRange('C1:F10');
      * fRange.setValues([
      *   [1, 2, 3, 4],
      *   [2, 3, 4, 5],
@@ -58,7 +60,7 @@ export class FFilter {
      *   [10, 11, 12, 13],
      * ]);
      *
-     * // Create a filter on the range
+     * // Create a filter on the range C1:F10
      * let fFilter = fRange.createFilter();
      *
      * // If the filter already exists, remove it and create a new one
@@ -67,15 +69,17 @@ export class FFilter {
      *   fFilter = fRange.createFilter();
      * }
      *
-     * // Set the filter criteria of the column A
-     * fFilter?.setColumnFilterCriteria(0, {
+     * // Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
+     * const column = fWorksheet.getRange('C:C').getColumn();
+     * fFilter.setColumnFilterCriteria(column, {
      *   colId: 0,
      *   filters: {
      *     filters: ['1', '5', '9'],
      *   },
      * });
      *
-     * console.log(fFilter?.getFilteredOutRows()); // [1, 2, 3, 5, 6, 7, 9]
+     * // Get the filtered out rows
+     * console.log(fFilter.getFilteredOutRows()); // [1, 2, 3, 5, 6, 7, 9]
      * ```
      */
     getFilteredOutRows(): number[] {
@@ -90,7 +94,9 @@ export class FFilter {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
-     * const fRange = fWorksheet.getRange('A1:D10');
+     *
+     * // Set some values of the range C1:F10
+     * const fRange = fWorksheet.getRange('C1:F10');
      * fRange.setValues([
      *   [1, 2, 3, 4],
      *   [2, 3, 4, 5],
@@ -104,7 +110,7 @@ export class FFilter {
      *   [10, 11, 12, 13],
      * ]);
      *
-     * // Create a filter on the range
+     * // Create a filter on the range C1:F10
      * let fFilter = fRange.createFilter();
      *
      * // If the filter already exists, remove it and create a new one
@@ -113,16 +119,18 @@ export class FFilter {
      *   fFilter = fRange.createFilter();
      * }
      *
-     * // Set the filter criteria of the column A
-     * fFilter?.setColumnFilterCriteria(0, {
+     * // Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
+     * const column = fWorksheet.getRange('C:C').getColumn();
+     * fFilter.setColumnFilterCriteria(column, {
      *   colId: 0,
      *   filters: {
      *     filters: ['1', '5', '9'],
      *   },
      * });
      *
-     * console.log(fFilter?.getColumnFilterCriteria(0)); // { colId: 0, filters: { filters: ['1', '5', '9'] } }
-     * console.log(fFilter?.getColumnFilterCriteria(1)); // undefined
+     * // Print the filter criteria of the column C and D
+     * console.log(fFilter.getColumnFilterCriteria(column)); // { colId: 0, filters: { filters: ['1', '5', '9'] } }
+     * console.log(fFilter.getColumnFilterCriteria(column + 1)); // undefined
      * ```
      */
     getColumnFilterCriteria(column: number): Nullable<IFilterColumn> {
@@ -137,7 +145,9 @@ export class FFilter {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
-     * const fRange = fWorksheet.getRange('A1:D10');
+     *
+     * // Set some values of the range C1:F10
+     * const fRange = fWorksheet.getRange('C1:F10');
      * fRange.setValues([
      *   [1, 2, 3, 4],
      *   [2, 3, 4, 5],
@@ -151,7 +161,7 @@ export class FFilter {
      *   [10, 11, 12, 13],
      * ]);
      *
-     * // Create a filter on the range
+     * // Create a filter on the range C1:F10
      * let fFilter = fRange.createFilter();
      *
      * // If the filter already exists, remove it and create a new one
@@ -160,17 +170,18 @@ export class FFilter {
      *   fFilter = fRange.createFilter();
      * }
      *
-     * // Set the filter criteria of the column A
-     * fFilter?.setColumnFilterCriteria(0, {
+     * // Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
+     * const column = fWorksheet.getRange('C:C').getColumn();
+     * fFilter.setColumnFilterCriteria(column, {
      *   colId: 0,
      *   filters: {
      *     filters: ['1', '5', '9'],
      *   },
      * });
      *
-     * // Clear the filter criteria of the column A after 3 seconds
+     * // Clear the filter criteria of the column C after 3 seconds
      * setTimeout(() => {
-     *   fFilter?.removeColumnFilterCriteria(0);
+     *   fFilter.removeColumnFilterCriteria(column);
      * }, 3000);
      * ```
      */
@@ -193,7 +204,9 @@ export class FFilter {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
-     * const fRange = fWorksheet.getRange('A1:D10');
+     *
+     * // Set some values of the range C1:F10
+     * const fRange = fWorksheet.getRange('C1:F10');
      * fRange.setValues([
      *   [1, 2, 3, 4],
      *   [2, 3, 4, 5],
@@ -207,7 +220,7 @@ export class FFilter {
      *   [10, 11, 12, 13],
      * ]);
      *
-     * // Create a filter on the range
+     * // Create a filter on the range C1:F10
      * let fFilter = fRange.createFilter();
      *
      * // If the filter already exists, remove it and create a new one
@@ -216,8 +229,9 @@ export class FFilter {
      *   fFilter = fRange.createFilter();
      * }
      *
-     * // Set the filter criteria of the column A
-     * fFilter?.setColumnFilterCriteria(0, {
+     * // Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
+     * const column = fWorksheet.getRange('C:C').getColumn();
+     * fFilter.setColumnFilterCriteria(column, {
      *   colId: 0,
      *   filters: {
      *     filters: ['1', '5', '9'],
@@ -258,7 +272,9 @@ export class FFilter {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
-     * const fRange = fWorksheet.getRange('A1:D10');
+     *
+     * // Set some values of the range C1:F10
+     * const fRange = fWorksheet.getRange('C1:F10');
      * fRange.setValues([
      *   [1, 2, 3, 4],
      *   [2, 3, 4, 5],
@@ -272,7 +288,7 @@ export class FFilter {
      *   [10, 11, 12, 13],
      * ]);
      *
-     * // Create a filter on the range
+     * // Create a filter on the range C1:F10
      * let fFilter = fRange.createFilter();
      *
      * // If the filter already exists, remove it and create a new one
@@ -281,8 +297,9 @@ export class FFilter {
      *   fFilter = fRange.createFilter();
      * }
      *
-     * // Set the filter criteria of the column A
-     * fFilter?.setColumnFilterCriteria(0, {
+     * // Set the filter criteria of the column C, filter out the rows that are not 1, 5, 9
+     * const column = fWorksheet.getRange('C:C').getColumn();
+     * fFilter.setColumnFilterCriteria(column, {
      *   colId: 0,
      *   filters: {
      *     filters: ['1', '5', '9'],
@@ -291,7 +308,7 @@ export class FFilter {
      *
      * // Clear the filter criteria of all columns after 3 seconds
      * setTimeout(() => {
-     *   fFilter?.removeFilterCriteria();
+     *   fFilter.removeFilterCriteria();
      * }, 3000);
      * ```
      */

diff --git a/packages/sheets-filter/src/facade/f-range.ts b/packages/sheets-filter/src/facade/f-range.ts
@@ -41,7 +41,7 @@ export interface IFRangeFilter {
      *   fWorksheet.getFilter().remove();
      *   fFilter = fRange.createFilter();
      * }
-     * console.log(fFilter);
+     * console.log(fFilter, fFilter.getRange().getA1Notation());
      * ```
      */
     createFilter(this: FRange): FFilter | null;
@@ -61,7 +61,7 @@ export interface IFRangeFilter {
      * if (!fFilter) {
      *    fFilter = fRange.createFilter();
      * }
-     * console.log(fFilter);
+     * console.log(fFilter, fFilter.getRange().getA1Notation());
      * ```
      */
     getFilter(): FFilter | null;

diff --git a/packages/sheets-numfmt/src/facade/f-range.ts b/packages/sheets-numfmt/src/facade/f-range.ts
@@ -32,6 +32,8 @@ export interface IFRangeSheetsNumfmtMixin {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set the number format of the A1 cell to '#,##0.00'.
      * const fRange = fWorksheet.getRange('A1');
      * fRange.setValue(1234.567).setNumberFormat('#,##0.00');
      * console.log(fRange.getDisplayValue()); // 1,234.57
@@ -47,6 +49,8 @@ export interface IFRangeSheetsNumfmtMixin {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set the number formats of the A1:B2 range.
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   [1234.567, 0.1234],
@@ -67,6 +71,8 @@ export interface IFRangeSheetsNumfmtMixin {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Get the number format of the top-left cell of the A1:B2 range.
      * const fRange = fWorksheet.getRange('A1:B2');
      * console.log(fRange.getNumberFormat());
      * ```
@@ -80,6 +86,8 @@ export interface IFRangeSheetsNumfmtMixin {
      * ```ts
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Get the number formats of the A1:B2 range.
      * const fRange = fWorksheet.getRange('A1:B2');
      * console.log(fRange.getNumberFormats());
      * ```

diff --git a/packages/sheets-ui/src/facade/f-range.ts b/packages/sheets-ui/src/facade/f-range.ts
@@ -189,9 +189,20 @@ interface IFRangeSheetsUIMixin {
      * const fRange = fWorksheet.getRange('C3:E5');
      * fRange.highlight();
      *
-     * // Highlight the range C7:E9 with custom style
+     * // Highlight the range C7:E9 with custom style and primary cell D8
      * const fRange2 = fWorksheet.getRange('C7:E9');
-     * const disposable = fRange2.highlight({ stroke: 'red', fill: 'yellow' });
+     * const primaryCell = fWorksheet.getRange('D8').getRange();
+     * const disposable = fRange2.highlight(
+     *   {
+     *     stroke: 'red',
+     *     fill: 'yellow'
+     *   },
+     *   {
+     *     ...primaryCell,
+     *     actualRow: primaryCell.startRow,
+     *     actualColumn: primaryCell.startColumn
+     *   }
+     * );
      *
      * // Remove the range C7:E9 highlight after 5 seconds
      * setTimeout(() => {

diff --git a/packages/sheets/src/facade/f-range.ts b/packages/sheets/src/facade/f-range.ts
@@ -1119,8 +1119,9 @@ export class FRange extends FBaseInitialable {
      * const fRange = fWorksheet.getRange('A1:B2');
      * console.log(fRange.getValue(true));
      *
-     * // set the first cell value to 123
-     * const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } })
+     * // Set A1 cell value to rich text
+     * const richText = univerAPI.newRichText()
+     *   .insertText('Hello World')
      *   .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
      *   .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
      * fRange.setRichTextValueForCell(richText);
@@ -1155,8 +1156,9 @@ export class FRange extends FBaseInitialable {
      * const fRange = fWorksheet.getRange('A1:B2');
      * console.log(fRange.getValue(true));
      *
-     * // set the first cell value to 123
-     * const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } })
+     * // Set A1:B2 cell value to rich text
+     * const richText = univerAPI.newRichText()
+     *   .insertText('Hello World')
      *   .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
      *   .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
      * fRange.setRichTextValues([
@@ -1815,14 +1817,14 @@ export class FRange extends FBaseInitialable {
      * const fWorksheet = fWorkbook.getActiveSheet();
      *
      * // A1:A3 has following values:
-     * //  A      | B | C
-     * //  1,2,3  |   |
-     * //  4,,5,6 |   |
+     * //    A    |
+     * //  1,2,3  |
+     * //  4,,5,6 |
      * const fRange = fWorksheet.getRange('A1:A3');
      * fRange.setValues([
-     *   ['A', 'B', 'C'],
-     *   ['1,2,3', null, null],
-     *   ['4,,5,6', null, null]
+     *   ['A'],
+     *   ['1,2,3'],
+     *   ['4,,5,6']
      * ]);
      *
      * // After calling splitTextToColumns(true), the range will be:
@@ -1849,14 +1851,14 @@ export class FRange extends FBaseInitialable {
      * const fWorksheet = fWorkbook.getActiveSheet();
      *
      * // A1:A3 has following values:
-     * //     A   | B | C
-     * //  1;;2;3 |   |
-     * //  1;,2;3 |   |
+     * //     A   |
+     * //  1;;2;3 |
+     * //  1;,2;3 |
      * const fRange = fWorksheet.getRange('A1:A3');
      * fRange.setValues([
-     *   ['A', 'B', 'C'],
-     *   ['1;;2;3', null, null],
-     *   ['1;,2;3', null, null]
+     *   ['A'],
+     *   ['1;;2;3'],
+     *   ['1;,2;3']
      * ]);
      *
      * // After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma), the range will be:
@@ -1884,14 +1886,14 @@ export class FRange extends FBaseInitialable {
      * const fWorksheet = fWorkbook.getActiveSheet();
      *
      * // A1:A3 has following values:
-     * //     A   | B | C
-     * //  1#2#3  |   |
-     * //  4##5#6 |   |
+     * //     A   |
+     * //  1#2#3  |
+     * //  4##5#6 |
      * const fRange = fWorksheet.getRange('A1:A3');
      * fRange.setValues([
-     *   ['A', 'B', 'C'],
-     *   ['1#2#3', null, null],
-     *   ['4##5#6', null, null]
+     *   ['A'],
+     *   ['1#2#3'],
+     *   ['4##5#6']
      * ]);
      *
      * // After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be:

diff --git a/packages/sheets/src/facade/f-selection.ts b/packages/sheets/src/facade/f-selection.ts
@@ -143,8 +143,7 @@ export class FSelection {
      * const cell = fWorksheet.getRange('B11');
      *
      * let fSelection = fWorksheet.getSelection();
-     * fSelection.updatePrimaryCell(cell);
-     * fSelection = fWorksheet.getSelection();
+     * fSelection = fSelection.updatePrimaryCell(cell);
      *
      * const currentCell = fSelection.getCurrentCell();
      * const { actualRow, actualColumn } = currentCell;