From 3760ee82dc68216bc8a9b9d700e4feb7e3f02741 Mon Sep 17 00:00:00 2001 From: wpxp123456 <2677556700@qq.com> Date: Thu, 13 Mar 2025 11:08:07 +0800 Subject: [PATCH] feat: supplement facade example (#4825) --- .../src/facade/f-range.ts | 4 +- .../src/facade/f-worksheet.ts | 6 +- .../src/facade/f-event.ts | 60 ++++++++--------- .../src/facade/f-worksheet.ts | 65 +++++++++++-------- .../src/facade/f-univer.ts | 2 + .../sheets-hyper-link/src/facade/f-range.ts | 8 ++- .../src/facade/f-range.ts | 24 +++++-- .../src/facade/f-workbook.ts | 4 +- packages/sheets/src/facade/f-worksheet.ts | 2 +- 9 files changed, 103 insertions(+), 72 deletions(-) diff --git a/packages/sheets-conditional-formatting/src/facade/f-range.ts b/packages/sheets-conditional-formatting/src/facade/f-range.ts index d1d0905a5e..200ddf47fc 100644 --- a/packages/sheets-conditional-formatting/src/facade/f-range.ts +++ b/packages/sheets-conditional-formatting/src/facade/f-range.ts @@ -48,7 +48,7 @@ export interface IFRangeConditionalFormattingMixin { * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); * - * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100. + * // Create a conditional formatting rule that sets the cell format to italic, red background, and green font color when the cell is not empty. * const fRange = fWorksheet.getRange('A1:T100'); * const rule = fWorksheet.newConditionalFormattingRule() * .whenCellNotEmpty() @@ -75,7 +75,7 @@ export interface IFRangeConditionalFormattingMixin { * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); * - * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100. + * // Create a conditional formatting rule that sets the cell format to italic, red background, and green font color when the cell is not empty. * const fRange = fWorksheet.getRange('A1:T100'); * const rule = fRange.createConditionalFormattingRule() * .whenCellNotEmpty() diff --git a/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts b/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts index a091e1c6e6..5d06cbaef6 100644 --- a/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts +++ b/packages/sheets-conditional-formatting/src/facade/f-worksheet.ts @@ -69,7 +69,7 @@ export interface IFWorksheetConditionalFormattingMixin { * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); * - * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100. + * // Create a conditional formatting rule that sets the cell format to italic, red background, and green font color when the cell is not empty. * const fRange = fWorksheet.getRange('A1:T100'); * const rule = fWorksheet.newConditionalFormattingRule() * .whenCellNotEmpty() @@ -93,7 +93,7 @@ export interface IFWorksheetConditionalFormattingMixin { * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); * - * // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100. + * // Create a conditional formatting rule that sets the cell format to italic, red background, and green font color when the cell is not empty. * const fRange = fWorksheet.getRange('A1:T100'); * const rule = fWorksheet.newConditionalFormattingRule() * .whenCellNotEmpty() @@ -155,6 +155,8 @@ export interface IFWorksheetConditionalFormattingMixin { * ```ts * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); + * + * // Create a conditional formatting rule that sets the cell format to italic, red background, and green font color when the cell is not empty. * const fRange = fWorksheet.getRange('A1:T100'); * const rule = fWorksheet.newConditionalFormattingRule() * .whenCellNotEmpty() diff --git a/packages/sheets-data-validation/src/facade/f-event.ts b/packages/sheets-data-validation/src/facade/f-event.ts index af46a59968..ec0352bd81 100644 --- a/packages/sheets-data-validation/src/facade/f-event.ts +++ b/packages/sheets-data-validation/src/facade/f-event.ts @@ -182,9 +182,9 @@ interface IDataValidationEvent { * @see {@link ISheetDataValidationChangedEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (event) => { - * const { origin, worksheet, workbook, changeType, oldRule, rule } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (params) => { + * const { origin, worksheet, workbook, changeType, oldRule, rule } = params; + * console.log(params); * }); * * // Remove the event listener, use `disposable.dispose()` @@ -197,9 +197,9 @@ interface IDataValidationEvent { * @see {@link ISheetDataValidatorStatusChangedEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (event) => { - * const { worksheet, workbook, row, column, status, rule } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (params) => { + * const { worksheet, workbook, row, column, status, rule } = params; + * console.log(params); * }); * * // Remove the event listener, use `disposable.dispose()` @@ -212,12 +212,12 @@ interface IDataValidationEvent { * @see {@link IBeforeSheetDataValidationAddEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (event) => { - * const { worksheet, workbook, rule } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (params) => { + * const { worksheet, workbook, rule } = params; + * console.log(params); * * // Cancel the data validation rule addition operation - * event.cancel = true; + * params.cancel = true; * }); * * // Remove the event listener, use `disposable.dispose()` @@ -230,12 +230,12 @@ interface IDataValidationEvent { * @see {@link IBeforeSheetDataValidationDeleteEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (event) => { - * const { worksheet, workbook, ruleId, rule } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (params) => { + * const { worksheet, workbook, ruleId, rule } = params; + * console.log(params); * * // Cancel the data validation rule deletion operation - * event.cancel = true; + * params.cancel = true; * }); * * // Remove the event listener, use `disposable.dispose()` @@ -248,12 +248,12 @@ interface IDataValidationEvent { * @see {@link IBeforeSheetDataValidationDeleteAllEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (event) => { - * const { worksheet, workbook, rules } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (params) => { + * const { worksheet, workbook, rules } = params; + * console.log(params); * * // Cancel the data validation rule deletion operation - * event.cancel = true; + * params.cancel = true; * }); * * // Remove the event listener, use `disposable.dispose()` @@ -266,12 +266,12 @@ interface IDataValidationEvent { * @see {@link IBeforeSheetDataValidationCriteriaUpdateEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (event) => { - * const { worksheet, workbook, ruleId, rule, newCriteria } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (params) => { + * const { worksheet, workbook, ruleId, rule, newCriteria } = params; + * console.log(params); * * // Cancel the data validation rule criteria update operation - * event.cancel = true; + * params.cancel = true; * }); * * // Remove the event listener, use `disposable.dispose()` @@ -284,12 +284,12 @@ interface IDataValidationEvent { * @see {@link IBeforeSheetDataValidationRangeUpdateEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (event) => { - * const { worksheet, workbook, ruleId, rule, newRanges } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (params) => { + * const { worksheet, workbook, ruleId, rule, newRanges } = params; + * console.log(params); * * // Cancel the data validation rule range update operation - * event.cancel = true; + * params.cancel = true; * }); * * // Remove the event listener, use `disposable.dispose()` @@ -302,12 +302,12 @@ interface IDataValidationEvent { * @see {@link IBeforeSheetDataValidationOptionsUpdateEvent} * @example * ```ts - * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (event) => { - * const { worksheet, workbook, ruleId, rule, newOptions } = event; - * console.log(event); + * const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (params) => { + * const { worksheet, workbook, ruleId, rule, newOptions } = params; + * console.log(params); * * // Cancel the data validation rule options update operation - * event.cancel = true; + * params.cancel = true; * }); * * // Remove the event listener, use `disposable.dispose()` diff --git a/packages/sheets-drawing-ui/src/facade/f-worksheet.ts b/packages/sheets-drawing-ui/src/facade/f-worksheet.ts index 18ce7b798c..6821240554 100644 --- a/packages/sheets-drawing-ui/src/facade/f-worksheet.ts +++ b/packages/sheets-drawing-ui/src/facade/f-worksheet.ts @@ -41,7 +41,7 @@ export interface IFWorksheetLegacy { * @param {string} [id] - The float dom id, if not given will be auto generated. * @returns float dom id and dispose function * @example - * ```ts + * ```tsx * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); * * // You should register components at an appropriate time (e.g., when Univer is loaded) @@ -74,7 +74,7 @@ export interface IFWorksheetLegacy { * }, * }); * - * // Remove the floating DOM + * // Remove the floating DOM after 2 seconds * setTimeout(() => { * disposeable?.dispose(); * }, 2000); @@ -93,7 +93,7 @@ export interface IFWorksheetLegacy { * @param {string} [id] - The float dom id, if not given will be auto generated * @returns float dom id and dispose function * @example - * ```ts + * ```tsx * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); * * // Register a range loading component @@ -120,9 +120,10 @@ export interface IFWorksheetLegacy { * univerAPI.registerComponent('RangeLoading', RangeLoading); * * // Add the range loading component covering the range A1:C3 - * const range = fWorksheet.getRange('A1:C3'); - * const disposeable = fWorksheet.addFloatDomToRange(range, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading'); + * const fRange = fWorksheet.getRange('A1:C3'); + * const disposeable = fWorksheet.addFloatDomToRange(fRange, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading'); * + * // Remove the floating DOM after 2 seconds * setTimeout(() => { * disposeable?.dispose(); * }, 2000); @@ -156,15 +157,20 @@ export interface IFWorksheetLegacy { * univerAPI.registerComponent('FloatButton', FloatButton); * * // Add the float button to the range A5:C7, position is start from A5 cell, and width is 100px, height is 30px, margin is 100% of range width and height - * const range2 = fWorksheet.getRange('A5:C7'); - * const disposeable2 = fWorksheet.addFloatDomToRange(range2, { - * componentKey: 'FloatButton', - * }, { - * width: 100, - * height: 30, - * marginX: '100%', // margin percent to range width, or pixel - * marginY: '100%' - * }, 'myFloatButton'); + * const fRange2 = fWorksheet.getRange('A5:C7'); + * const disposeable2 = fWorksheet.addFloatDomToRange( + * fRange2, + * { + * componentKey: 'FloatButton', + * }, + * { + * width: 100, + * height: 30, + * marginX: '100%', // margin percent to range width, or pixel + * marginY: '100%' + * }, + * 'myFloatButton' + * ); * ``` */ addFloatDomToRange(range: FRange, layer: Partial, domLayout: Partial, id?: string): Nullable<{ @@ -211,18 +217,23 @@ export interface IFWorksheetLegacy { * univerAPI.registerComponent('FloatButton', FloatButton); * * // Add the float button to the column D header, position is right align, width is 100px, height is 30px, margin is 0 - * const disposeable = fWorksheet.addFloatDomToColumnHeader(3, { - * componentKey: 'FloatButton', - * allowTransform: false, - * }, { - * width: 100, - * height: 30, - * marginX: 0, - * marginY: 0, - * horizonOffsetAlign: 'right', - * }, 'myFloatButton'); + * const disposeable = fWorksheet.addFloatDomToColumnHeader( + * 3, + * { + * componentKey: 'FloatButton', + * allowTransform: false, + * }, + * { + * width: 100, + * height: 30, + * marginX: 0, + * marginY: 0, + * horizonOffsetAlign: 'right', + * }, + * 'myFloatButton' + * ); * - * // Remove the float button + * // Remove the float button after 2 seconds * setTimeout(() => { * disposeable?.dispose(); * }, 2000); @@ -345,6 +356,8 @@ export interface IFWorksheetLegacy { * ```ts * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); * const image = fWorksheet.getImages()[0]; + * + * // Delete the first image of the sheet * fWorksheet.deleteImages([image]); * ``` */ @@ -369,7 +382,7 @@ export interface IFWorksheetLegacy { * .buildAsync(); * fWorksheet.insertImages([image]); * - * // update the image width to 100px and height to 50px + * // update the image width to 100px and height to 50px after 4 seconds * setTimeout(async () => { * const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder(); * const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync(); diff --git a/packages/sheets-find-replace/src/facade/f-univer.ts b/packages/sheets-find-replace/src/facade/f-univer.ts index b328742aed..69761da7f1 100644 --- a/packages/sheets-find-replace/src/facade/f-univer.ts +++ b/packages/sheets-find-replace/src/facade/f-univer.ts @@ -31,6 +31,8 @@ export interface IFUniverFindReplaceMixin { * // Assume the current sheet is empty sheet. * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); + * + * // Set some values to the range A1:D10. * const fRange = fWorksheet.getRange('A1:D10'); * fRange.setValues([ * [1, 2, 3, 4], diff --git a/packages/sheets-hyper-link/src/facade/f-range.ts b/packages/sheets-hyper-link/src/facade/f-range.ts index 3b03cffc47..3c0457fc26 100644 --- a/packages/sheets-hyper-link/src/facade/f-range.ts +++ b/packages/sheets-hyper-link/src/facade/f-range.ts @@ -37,6 +37,8 @@ export interface IFRangeHyperlinkMixin { * ```ts * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); + * + * // Create a hyperlink to Univer on cell A1 * const fRange = fWorksheet.getRange('A1'); * const richText = univerAPI.newRichText().insertLink('Univer', 'https://univer.ai/'); * fRange.setRichTextValueForCell(richText); @@ -50,11 +52,13 @@ export interface IFRangeHyperlinkMixin { * ```ts * const fWorkbook = univerAPI.getActiveWorkbook(); * const fWorksheet = fWorkbook.getActiveSheet(); + * + * // Create a hyperlink to Univer on cell A1 * const fRange = fWorksheet.getRange('A1'); * const richText = univerAPI.newRichText().insertLink('Univer', 'https://univer.ai/'); * fRange.setRichTextValueForCell(richText); * - * // Get hyperlinks + * // Get hyperlinks from cell A1 * console.log(fRange.getValue(true).getLinks()); * ``` */ @@ -75,7 +79,7 @@ export interface IFRangeHyperlinkMixin { * const cellValue = fRange.getValue(true); * const hyperlinks = cellValue.getLinks(); * const id = hyperlinks[0].rangeId; - * const newUrl = 'https://go.univer.ai/'; + * const newUrl = 'https://insight.univer.ai/'; * const newRichText = cellValue.copy().updateLink(id, newUrl); * fRange.setRichTextValueForCell(newRichText); * }, 3000); diff --git a/packages/sheets-thread-comment/src/facade/f-range.ts b/packages/sheets-thread-comment/src/facade/f-range.ts index e61eb7ac44..44990ee7d9 100644 --- a/packages/sheets-thread-comment/src/facade/f-range.ts +++ b/packages/sheets-thread-comment/src/facade/f-range.ts @@ -54,23 +54,30 @@ export interface IFRangeCommentMixin { * ``` */ getComments(): FThreadComment[]; + /** * @deprecated use `addCommentAsync` as instead. */ addComment(content: IDocumentBody | FTheadCommentBuilder): Promise; + /** * Add a comment to the start cell in the current range. * @param content The content of the comment. * @returns Whether the comment is added successfully. * @example * ```ts - * const range = univerAPI.getActiveWorkbook() - * .getActiveSheet() - * .getActiveRange(); + * // Create a new comment + * const richText = univerAPI.newRichText().insertText('hello univer'); + * const commentBuilder = univerAPI.newTheadComment() + * .setContent(richText); + * console.log(commentBuilder.content.toPlainText()); * - * const comment = univerAPI.newTheadComment() - * .setContent(univerAPI.newRichText().insertText('hello zhangsan')); - * const success = await range.addCommentAsync(comment); + * // Add the comment to the cell A1 + * const fWorkbook = univerAPI.getActiveWorkbook(); + * const fWorksheet = fWorkbook.getActiveSheet(); + * const cell = fWorksheet.getRange('A1'); + * const result = await cell.addCommentAsync(commentBuilder); + * console.log(result); * ``` */ addCommentAsync(content: IDocumentBody | FTheadCommentBuilder): Promise; @@ -79,15 +86,18 @@ export interface IFRangeCommentMixin { * @deprecated use `clearCommentAsync` as instead. */ clearComment(): Promise; + /** * Clear the comment of the start cell in the current range. * @returns Whether the comment is cleared successfully. */ clearCommentAsync(): Promise; + /** - * @deprecated use `clearComments` as instead. + * @deprecated use `clearCommentsAsync` as instead. */ clearComments(): Promise; + /** * Clear all of the comments in the current range. * @returns Whether the comments are cleared successfully. diff --git a/packages/sheets-zen-editor/src/facade/f-workbook.ts b/packages/sheets-zen-editor/src/facade/f-workbook.ts index fb10e29009..9868ec4c62 100644 --- a/packages/sheets-zen-editor/src/facade/f-workbook.ts +++ b/packages/sheets-zen-editor/src/facade/f-workbook.ts @@ -23,7 +23,7 @@ import { FWorkbook } from '@univerjs/sheets/facade'; */ export interface IFWorkbookSheetsZenEditorMixin { /** - * Start the zen editing process + * Enter the zen editing process on the active cell * @returns {Promise} A promise that resolves to a boolean indicating whether the zen editing process was started successfully. * @example * ```ts @@ -35,7 +35,7 @@ export interface IFWorkbookSheetsZenEditorMixin { startZenEditingAsync(): Promise; /** - * End the zen editing process + * End the zen editing process on the active cell and optionally save the changes * @async * @param {boolean} save - Whether to save the changes, default is true * @returns {Promise} A promise that resolves to a boolean indicating whether the zen editing process was ended successfully. diff --git a/packages/sheets/src/facade/f-worksheet.ts b/packages/sheets/src/facade/f-worksheet.ts index 91050a3e4f..deea8c2dfb 100644 --- a/packages/sheets/src/facade/f-worksheet.ts +++ b/packages/sheets/src/facade/f-worksheet.ts @@ -2009,7 +2009,7 @@ export class FWorksheet extends FBaseInitialable { // eslint-disable-next-line /** - * @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {})` instead + * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => {})` instead */ onBeforeCellDataChange(callback: (cellValue: ObjectMatrix>) => void): IDisposable { const commandService = this._injector.get(ICommandService);