Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.
TypeScript boardcollaborationdocdocxexceloffce365officepdfpptpptxpresentationsdksheetslidesspreadsheetuniverwordwordprocessorworkspacexlsx
feat: supplement facade example (#4825)
wpxp1234563760ee82dc68
diff --git a/packages/sheets-conditional-formatting/src/facade/f-range.ts b/packages/sheets-conditional-formatting/src/facade/f-range.tsindex 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.tsindex 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.tsindex 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.tsindex 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<IFICanvasFloatDom>, domLayout: Partial<IDOMAnchor>, 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.tsindex 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.tsindex 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.tsindex 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<boolean>;+/*** 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<boolean>;@@ -79,15 +86,18 @@ export interface IFRangeCommentMixin {* @deprecated use `clearCommentAsync` as instead.*/clearComment(): Promise<boolean>;+/*** Clear the comment of the start cell in the current range.* @returns Whether the comment is cleared successfully.*/clearCommentAsync(): Promise<boolean>;+/**- * @deprecated use `clearComments` as instead.+ * @deprecated use `clearCommentsAsync` as instead.*/clearComments(): Promise<boolean>;+/*** 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.tsindex 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<boolean>} 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<boolean>;/**- * 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<boolean>} 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.tsindex 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<Nullable<ICellData>>) => void): IDisposable {const commandService = this._injector.get(ICommandService);