Skip to content

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.

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.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<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.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<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.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<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.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<Nullable<ICellData>>) => void): IDisposable {
const commandService = this._injector.get(ICommandService);