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.

docs(facade): supplement notes and example (#4653)

wpxp123456b900a15e06cd
diff --git a/packages/core/src/facade/f-blob.ts b/packages/core/src/facade/f-blob.ts
index 13397ddb70..8865858439 100644
--- a/packages/core/src/facade/f-blob.ts
+++ b/packages/core/src/facade/f-blob.ts
@@ -47,7 +47,7 @@ export class FBlob extends FBase {
* @returns a new blob by copying the current blob
* @example
* ```ts
- * const blob = univerAPI.newBlob(blob);
+ * const blob = univerAPI.newBlob();
* const newBlob = blob.copyBlob();
* console.log(newBlob);
* ```
@@ -62,8 +62,9 @@ export class FBlob extends FBase {
* @returns a new blob by converting the current blob to the specified content type
* @example
* ```ts
- * const blob = univerAPI.newBlob(blob);
- * const newBlob = blob.getBlob();
+ * const blob = univerAPI.newBlob();
+ * const newBlob = blob.getAs('text/plain');
+ * console.log(newBlob);
* ```
*/
getAs(contentType: string): FBlob {
@@ -77,9 +78,9 @@ export class FBlob extends FBase {
* @returns
* @example
* ```ts
- * const blob = univerAPI.newBlob(blob);
- * const newBlob = blob.getDataAsString();
- * console.log(newBlob);
+ * const blob = univerAPI.newBlob();
+ * const data = await blob.getDataAsString();
+ * console.log(data);
* ```
*/
getDataAsString(): Promise<string>;
@@ -89,9 +90,9 @@ export class FBlob extends FBase {
* @returns the blob content as a string
* @example
* ```ts
- * const blob = univerAPI.newBlob(blob);
- * const newBlob = blob.getDataAsString('iso-8859-1');
- * console.log(newBlob);
+ * const blob = univerAPI.newBlob();
+ * const data = await blob.getDataAsString('iso-8859-1');
+ * console.log(data);
* ```
*/
getDataAsString(charset?: string): Promise<string>;
@@ -118,9 +119,9 @@ export class FBlob extends FBase {
* @returns the blob content as a byte array
* @example
* ```ts
- * const blob = univerAPI.newBlob(blob);
- * const newBlob = blob.getBytes();
- * console.log(newBlob);
+ * const blob = univerAPI.newBlob();
+ * const bytes = await blob.getBytes();
+ * console.log(bytes);
* ```
*/
getBytes(): Promise<Uint8Array> {
@@ -181,9 +182,9 @@ export class FBlob extends FBase {
* @returns the content type
* @example
* ```ts
- * const blob = univerAPI.newBlob(blob);
- * const newBlob = blob.getContentType();
- * console.log(newBlob);
+ * const blob = univerAPI.newBlob();
+ * const contentType = blob.getContentType();
+ * console.log(contentType);
* ```
*/
getContentType(): string | undefined {
@@ -196,9 +197,8 @@ export class FBlob extends FBase {
* @returns the blob object
* @example
* ```ts
- * const blob = univerAPI.newBlob(blob);
- * const newBlob = blob.setContentType('text/plain');
- * console.log(newBlob);
+ * const blob = univerAPI.newBlob();
+ * blob.setContentType('text/plain');
* ```
*/
setContentType(contentType: string): FBlob {
diff --git a/packages/core/src/facade/f-enum.ts b/packages/core/src/facade/f-enum.ts
index 20ae2dac93..bf722b1bf4 100644
--- a/packages/core/src/facade/f-enum.ts
+++ b/packages/core/src/facade/f-enum.ts
@@ -16,7 +16,7 @@
/* eslint-disable ts/explicit-function-return-type */
-import { AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, HorizontalAlign, InterpolationPointType, LifecycleStages, LocaleType, MentionType, ProtectionType, RelativeDate, SheetTypes, TextDecoration, TextDirection, ThemeColorType, UniverInstanceType, VerticalAlign } from '@univerjs/core';
+import { AutoFillSeries, BaselineOffset, BooleanNumber, BorderStyleTypes, BorderType, ColorType, CommandType, CommonHideTypes, CopyPasteType, DataValidationErrorStyle, DataValidationOperator, DataValidationRenderMode, DataValidationStatus, DataValidationType, DeleteDirection, DeveloperMetadataVisibility, Dimension, Direction, HorizontalAlign, InterpolationPointType, LifecycleStages, LocaleType, MentionType, ProtectionType, RelativeDate, SheetTypes, TextDecoration, TextDirection, ThemeColorType, UniverInstanceType, VerticalAlign, WrapStrategy } from '@univerjs/core';
/**
* @hideconstructor
@@ -64,7 +64,12 @@ export class FEnum {
}
/**
- * Defines different types of Univer instances
+ * Defines different types of Univer instances
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.UniverInstanceType.UNIVER_SHEET);
+ * ```
*/
get UniverInstanceType() {
return UniverInstanceType;
@@ -72,6 +77,11 @@ export class FEnum {
/**
* Represents different stages in the lifecycle
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.LifecycleStages.Rendered);
+ * ```
*/
get LifecycleStages() {
return LifecycleStages;
@@ -79,6 +89,11 @@ export class FEnum {
/**
* Different types of data validation
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.DataValidationType.LIST);
+ * ```
*/
get DataValidationType() {
return DataValidationType;
@@ -86,6 +101,11 @@ export class FEnum {
/**
* Different error display styles
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.DataValidationErrorStyle.WARNING);
+ * ```
*/
get DataValidationErrorStyle() {
return DataValidationErrorStyle;
@@ -93,6 +113,11 @@ export class FEnum {
/**
* Different validation rendering modes
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.DataValidationRenderMode.TEXT);
+ * ```
*/
get DataValidationRenderMode() {
return DataValidationRenderMode;
@@ -100,6 +125,11 @@ export class FEnum {
/**
* Different validation operators
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.DataValidationOperator.BETWEEN);
+ * ```
*/
get DataValidationOperator() {
return DataValidationOperator;
@@ -107,6 +137,11 @@ export class FEnum {
/**
* Different validation states
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.DataValidationStatus.VALID);
+ * ```
*/
get DataValidationStatus() {
return DataValidationStatus;
@@ -114,6 +149,11 @@ export class FEnum {
/**
* Different types of commands
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.CommandType.COMMAND);
+ * ```
*/
get CommandType() {
return CommandType;
@@ -121,6 +161,11 @@ export class FEnum {
/**
* Different baseline offsets for text baseline positioning
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.BaselineOffset.SUPERSCRIPT);
+ * ```
*/
get BaselineOffset() {
return BaselineOffset;
@@ -128,6 +173,11 @@ export class FEnum {
/**
* Boolean number representations
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.BooleanNumber.TRUE);
+ * ```
*/
get BooleanNumber() {
return BooleanNumber;
@@ -135,6 +185,11 @@ export class FEnum {
/**
* Different horizontal text alignment options
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.HorizontalAlign.CENTER);
+ * ```
*/
get HorizontalAlign() {
return HorizontalAlign;
@@ -142,6 +197,11 @@ export class FEnum {
/**
* Different text decoration styles
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.TextDecoration.DOUBLE);
+ * ```
*/
get TextDecoration() {
return TextDecoration;
@@ -149,6 +209,11 @@ export class FEnum {
/**
* Different text direction options
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.TextDirection.LEFT_TO_RIGHT);
+ * ```
*/
get TextDirection() {
return TextDirection;
@@ -156,13 +221,35 @@ export class FEnum {
/**
* Different vertical text alignment options
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.VerticalAlign.MIDDLE);
+ * ```
*/
get VerticalAlign() {
return VerticalAlign;
}
+ /**
+ * Different wrap strategy options
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.WrapStrategy.WRAP);
+ * ```
+ */
+ get WrapStrategy() {
+ return WrapStrategy;
+ }
+
/**
* Different border types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.BorderType.OUTSIDE);
+ * ```
*/
get BorderType() {
return BorderType;
@@ -170,6 +257,11 @@ export class FEnum {
/**
* Different border style types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.BorderStyleTypes.NONE);
+ * ```
*/
get BorderStyleTypes() {
return BorderStyleTypes;
@@ -177,6 +269,11 @@ export class FEnum {
/**
* Auto fill series types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.AutoFillSeries.ALTERNATE_SERIES);
+ * ```
*/
get AutoFillSeries() {
return AutoFillSeries;
@@ -184,6 +281,11 @@ export class FEnum {
/**
* Color types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.ColorType.RGB);
+ * ```
*/
get ColorType() {
return ColorType;
@@ -191,6 +293,11 @@ export class FEnum {
/**
* Common hide types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.CommonHideTypes.ON);
+ * ```
*/
get CommonHideTypes() {
return CommonHideTypes;
@@ -198,6 +305,11 @@ export class FEnum {
/**
* Copy paste types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.CopyPasteType.PASTE_VALUES);
+ * ```
*/
get CopyPasteType() {
return CopyPasteType;
@@ -205,6 +317,11 @@ export class FEnum {
/**
* Delete direction types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.DeleteDirection.LEFT);
+ * ```
*/
get DeleteDirection() {
return DeleteDirection;
@@ -212,6 +329,11 @@ export class FEnum {
/**
* Developer metadata visibility types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.DeveloperMetadataVisibility.DOCUMENT);
+ * ```
*/
get DeveloperMetadataVisibility() {
return DeveloperMetadataVisibility;
@@ -219,6 +341,11 @@ export class FEnum {
/**
* Dimension types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.Dimension.ROWS);
+ * ```
*/
get Dimension() {
return Dimension;
@@ -226,6 +353,11 @@ export class FEnum {
/**
* Direction types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.Direction.UP);
+ * ```
*/
get Direction() {
return Direction;
@@ -233,6 +365,11 @@ export class FEnum {
/**
* Interpolation point types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.InterpolationPointType.NUMBER);
+ * ```
*/
get InterpolationPointType() {
return InterpolationPointType;
@@ -240,6 +377,11 @@ export class FEnum {
/**
* Locale types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.LocaleType.EN_US);
+ * ```
*/
get LocaleType() {
return LocaleType;
@@ -247,6 +389,11 @@ export class FEnum {
/**
* Mention types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.MentionType.PERSON);
+ * ```
*/
get MentionType() {
return MentionType;
@@ -254,6 +401,11 @@ export class FEnum {
/**
* Protection types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.ProtectionType.RANGE);
+ * ```
*/
get ProtectionType() {
return ProtectionType;
@@ -261,6 +413,11 @@ export class FEnum {
/**
* Relative date types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.RelativeDate.TODAY);
+ * ```
*/
get RelativeDate() {
return RelativeDate;
@@ -268,6 +425,11 @@ export class FEnum {
/**
* Sheet types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.SheetTypes.GRID);
+ * ```
*/
get SheetTypes() {
return SheetTypes;
@@ -275,6 +437,11 @@ export class FEnum {
/**
* Theme color types
+ *
+ * @example
+ * ```ts
+ * console.log(univerAPI.Enum.ThemeColorType.ACCENT1);
+ * ```
*/
get ThemeColorType() {
return ThemeColorType;
diff --git a/packages/core/src/facade/f-event-registry.ts b/packages/core/src/facade/f-event-registry.ts
index c7df0ac8e0..7e5591faab 100644
--- a/packages/core/src/facade/f-event-registry.ts
+++ b/packages/core/src/facade/f-event-registry.ts
@@ -83,8 +83,9 @@ export class FEventRegistry {
* @returns {Disposable} The Disposable instance, for remove the listener
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.UnitCreated, (params) => {
- * console.log('unit created', params);
+ * univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, (params) => {
+ * const { stage } = params;
+ * console.log('life cycle changed', params);
* });
* ```
*/
@@ -101,7 +102,7 @@ export class FEventRegistry {
* @returns {boolean} should cancel
* @example
* ```ts
- * this.fireEvent(univerAPI.event.UnitCreated, params);
+ * this.fireEvent(univerAPI.Event.LifeCycleChanged, params);
* ```
*/
fireEvent<T extends keyof IEventParamConfig>(event: T, params: IEventParamConfig[T]): boolean | undefined {
diff --git a/packages/core/src/facade/f-event.ts b/packages/core/src/facade/f-event.ts
index c2fbe4e4cc..a1b7380a31 100644
--- a/packages/core/src/facade/f-event.ts
+++ b/packages/core/src/facade/f-event.ts
@@ -133,7 +133,7 @@ export class FEventName {
* @see {@link IDocCreatedParam}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.DocCreated, (params) => {
+ * univerAPI.addEvent(univerAPI.Event.DocCreated, (params) => {
* const { unitId, type, doc, unit } = params;
* console.log('doc created', params);
* });
@@ -148,7 +148,7 @@ export class FEventName {
* @see {@link IDocDisposedEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.DocDisposed, (params) => {
+ * univerAPI.addEvent(univerAPI.Event.DocDisposed, (params) => {
* const { unitId, unitType, snapshot } = params;
* console.log('doc disposed', params);
* });
@@ -163,7 +163,7 @@ export class FEventName {
* @see {@link ILifeCycleChangedEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.LifeCycleChanged, (params) => {
+ * univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, (params) => {
* const { stage } = params;
* console.log('life cycle changed', params);
* });
@@ -178,9 +178,9 @@ export class FEventName {
* @see {@link ICommandEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.Redo, (event) => {
+ * univerAPI.addEvent(univerAPI.Event.Redo, (event) => {
* const { params, id, type } = event;
- * console.log('command executed', event);
+ * console.log('redo command executed', event);
* });
* ```
*/
@@ -193,9 +193,9 @@ export class FEventName {
* @see {@link ICommandEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.Undo, (event) => {
+ * univerAPI.addEvent(univerAPI.Event.Undo, (event) => {
* const { params, id, type } = event;
- * console.log('command executed', event);
+ * console.log('undo command executed', event);
* });
* ```
*/
@@ -208,9 +208,9 @@ export class FEventName {
* @see {@link ICommandEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.BeforeRedo, (event) => {
+ * univerAPI.addEvent(univerAPI.Event.BeforeRedo, (event) => {
* const { params, id, type } = event;
- * console.log('command executed', event);
+ * console.log('before redo command executed', event);
* });
* ```
*/
@@ -223,9 +223,9 @@ export class FEventName {
* @see {@link ICommandEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.BeforeUndo, (event) => {
+ * univerAPI.addEvent(univerAPI.Event.BeforeUndo, (event) => {
* const { params, id, type } = event;
- * console.log('command executed', event);
+ * console.log('before undo command executed', event);
* });
* ```
*/
@@ -238,7 +238,7 @@ export class FEventName {
* @see {@link ICommandEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.CommandExecuted, (event) => {
+ * univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {
* const { params, id, type } = event;
* console.log('command executed', event);
* });
@@ -253,9 +253,9 @@ export class FEventName {
* @see {@link ICommandEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.BeforeCommandExecute, (event) => {
+ * univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {
* const { params, id, type } = event;
- * console.log('command executed', event);
+ * console.log('before command executed', event);
* });
* ```
*/
diff --git a/packages/core/src/facade/f-hooks.ts b/packages/core/src/facade/f-hooks.ts
index 6243267a0a..1b7b6f68fa 100644
--- a/packages/core/src/facade/f-hooks.ts
+++ b/packages/core/src/facade/f-hooks.ts
@@ -32,7 +32,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifecycleChanged)` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
*/
onStarting(callback: () => void): IDisposable {
return toDisposable(this._lifecycleService.lifecycle$.pipe(filter((lifecycle) => lifecycle === LifecycleStages.Starting)).subscribe(callback));
@@ -40,7 +40,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifecycleChanged)` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
*/
onReady(callback: () => void): IDisposable {
return toDisposable(this._lifecycleService.lifecycle$.pipe(filter((lifecycle) => lifecycle === LifecycleStages.Ready)).subscribe(callback));
@@ -48,7 +48,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifecycleChanged, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
*/
onRendered(callback: () => void): IDisposable {
return toDisposable(this._lifecycleService.lifecycle$.pipe(filter((lifecycle) => lifecycle === LifecycleStages.Rendered)).subscribe(callback));
@@ -56,7 +56,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifecycleChanged, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {})` as instead
*/
onSteady(callback: () => void): IDisposable {
return toDisposable(this._lifecycleService.lifecycle$.pipe(filter((lifecycle) => lifecycle === LifecycleStages.Steady)).subscribe(callback));
@@ -64,7 +64,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeUndo, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeUndo, (event) => {})` as instead
*/
onBeforeUndo(callback: (action: IUndoRedoItem) => void): IDisposable {
const commandService = this._injector.get(ICommandService);
@@ -82,7 +82,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.Undo, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.Undo, (event) => {})` as instead
*/
onUndo(callback: (action: IUndoRedoItem) => void): IDisposable {
const commandService = this._injector.get(ICommandService);
@@ -100,7 +100,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeRedo, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeRedo, (event) => {})` as instead
*/
onBeforeRedo(callback: (action: IUndoRedoItem) => void): IDisposable {
const commandService = this._injector.get(ICommandService);
@@ -118,7 +118,7 @@ export class FHooks extends FBase {
/**
* @param callback
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.Redo, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.Redo, (event) => {})` as instead
*/
onRedo(callback: (action: IUndoRedoItem) => void): IDisposable {
const commandService = this._injector.get(ICommandService);
diff --git a/packages/core/src/facade/f-univer.ts b/packages/core/src/facade/f-univer.ts
index 42fd345f37..4d76795fad 100644
--- a/packages/core/src/facade/f-univer.ts
+++ b/packages/core/src/facade/f-univer.ts
@@ -49,6 +49,11 @@ export class FUniver extends Disposable {
* @static
* @param {Univer | Injector} wrapped - The Univer instance or injector instance.
* @returns {FUniver} - The FUniver instance.
+ *
+ * @example
+ * ```ts
+ * const univerAPI = FUniver.newAPI(univer);
+ * ```
*/
static newAPI(wrapped: Univer | Injector): FUniver {
const injector = wrapped instanceof Univer ? wrapped.__getInjector() : wrapped;
@@ -261,6 +266,16 @@ export class FUniver extends Disposable {
* Dispose the UniverSheet by the `unitId`. The UniverSheet would be unload from the application.
* @param unitId The unit id of the UniverSheet.
* @returns Whether the Univer instance is disposed successfully.
+ *
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const unitId = fWorkbook?.getId();
+ *
+ * if (unitId) {
+ * univerAPI.disposeUnit(unitId);
+ * }
+ * ```
*/
disposeUnit(unitId: string): boolean {
return this._univerInstanceService.disposeUnit(unitId);
@@ -269,6 +284,12 @@ export class FUniver extends Disposable {
/**
* Get the current lifecycle stage.
* @returns {LifecycleStages} - The current lifecycle stage.
+ *
+ * @example
+ * ```ts
+ * const stage = univerAPI.getCurrentLifecycleStage();
+ * console.log(stage);
+ * ```
*/
getCurrentLifecycleStage(): LifecycleStages {
const lifecycleService = this._injector.get(LifecycleService);
@@ -278,6 +299,11 @@ export class FUniver extends Disposable {
/**
* Undo an editing on the currently focused document.
* @returns {Promise<boolean>} undo result
+ *
+ * @example
+ * ```ts
+ * univerAPI.undo();
+ * ```
*/
undo(): Promise<boolean> {
return this._commandService.executeCommand(UndoCommand.id);
@@ -286,6 +312,11 @@ export class FUniver extends Disposable {
/**
* Redo an editing on the currently focused document.
* @returns {Promise<boolean>} redo result
+ *
+ * @example
+ * ```ts
+ * univerAPI.redo();
+ * ```
*/
redo(): Promise<boolean> {
return this._commandService.executeCommand(RedoCommand.id);
@@ -293,7 +324,7 @@ export class FUniver extends Disposable {
/**
* Register a callback that will be triggered before invoking a command.
- * @deprecated use `addEvent(univerAPI.event.BeforeCommandExecute, () => {})` instead.
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {})` instead.
* @param {CommandListener} callback The callback.
* @returns {IDisposable} The disposable instance.
*/
@@ -305,7 +336,7 @@ export class FUniver extends Disposable {
/**
* Register a callback that will be triggered when a command is invoked.
- * @deprecated use `addEvent(univerAPI.event.CommandExecuted, () => {})` instead.
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {})` instead.
* @param {CommandListener} callback The callback.
* @returns {IDisposable} The disposable instance.
*/
@@ -321,6 +352,14 @@ export class FUniver extends Disposable {
* @param params Parameters of this execution.
* @param options Options of this execution.
* @returns The result of the execution. It is a boolean value by default which indicates the command is executed.
+ *
+ * @example
+ * ```ts
+ * univerAPI.executeCommand('sheet.command.set-range-values', {
+ * value: { v: "Hello, Univer!" },
+ * range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 }
+ * });
+ * ```
*/
executeCommand<P extends object = object, R = boolean>(
id: string,
@@ -336,6 +375,14 @@ export class FUniver extends Disposable {
* @param params Parameters of this execution.
* @param options Options of this execution.
* @returns The result of the execution. It is a boolean value by default which indicates the command is executed.
+ *
+ * @example
+ * ```ts
+ * univerAPI.syncExecuteCommand('sheet.command.set-range-values', {
+ * value: { v: "Hello, Univer!" },
+ * range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 }
+ * });
+ * ```
*/
syncExecuteCommand<P extends object = object, R = boolean>(
id: string,
@@ -373,8 +420,9 @@ export class FUniver extends Disposable {
* @returns {Disposable} The Disposable instance, for remove the listener
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.UnitCreated, (params) => {
- * console.log('unit created', params);
+ * univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, (params) => {
+ * const { stage } = params;
+ * console.log('life cycle changed', params);
* });
* ```
*/
@@ -390,7 +438,7 @@ export class FUniver extends Disposable {
* @returns {boolean} should cancel
* @example
* ```ts
- * this.fireEvent(univerAPI.event.UnitCreated, params);
+ * this.fireEvent(univerAPI.Event.LifeCycleChanged, params);
* ```
*/
protected fireEvent<T extends keyof IEventParamConfig>(event: T, params: IEventParamConfig[T]): boolean | undefined {
@@ -431,7 +479,9 @@ export class FUniver extends Disposable {
* @returns {RichTextBuilder} The new rich text instance
* @example
* ```ts
- * const richText = univerAPI.newRichText();
+ * const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } });
+ * const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1');
+ * range.setRichTextValueForCell(richText);
* ```
*/
newRichText(data?: IDocumentData): RichTextBuilder {
@@ -444,7 +494,9 @@ export class FUniver extends Disposable {
* @returns {RichTextValue} The new rich text value instance
* @example
* ```ts
- * const richTextValue = univerAPI.newRichTextValue();
+ * const richTextValue = univerAPI.newRichTextValue({ body: { dataStream: 'Hello World\r\n' } });
+ * const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1');
+ * range.setRichTextValueForCell(richTextValue);
* ```
*/
newRichTextValue(data: IDocumentData): RichTextValue {
@@ -457,7 +509,11 @@ export class FUniver extends Disposable {
* @returns {ParagraphStyleBuilder} The new paragraph style instance
* @example
* ```ts
- * const paragraphStyle = univerAPI.newParagraphStyle();
+ * const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } });
+ * const paragraphStyle = univerAPI.newParagraphStyle({ textStyle: { ff: 'Arial', fs: 12, it: univerAPI.Enum.BooleanNumber.TRUE, bl: univerAPI.Enum.BooleanNumber.TRUE } });
+ * richText.insertParagraph(paragraphStyle);
+ * const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1');
+ * range.setRichTextValueForCell(richText);
* ```
*/
newParagraphStyle(style?: IParagraphStyle): ParagraphStyleBuilder {
diff --git a/packages/core/src/facade/f-util.ts b/packages/core/src/facade/f-util.ts
index 53e034e044..7dcf8d7022 100644
--- a/packages/core/src/facade/f-util.ts
+++ b/packages/core/src/facade/f-util.ts
@@ -57,6 +57,16 @@ export class FUtil {
/**
* Rectangle utils, including range operations likes merge, subtract, split
+ *
+ * @example
+ * ```ts
+ * const ranges = [
+ * { startRow: 0, startColumn: 0, endRow: 1, endColumn: 1 },
+ * { startRow: 1, startColumn: 1, endRow: 2, endColumn: 2 }
+ * ];
+ * const merged = univerAPI.Util.rectangle.mergeRanges(ranges);
+ * console.log(merged);
+ * ```
*/
get rectangle(): typeof Rectangle {
return Rectangle;
@@ -64,6 +74,12 @@ export class FUtil {
/**
* Number format utils, including parse and strigify about date, price, etc
+ *
+ * @example
+ * ```ts
+ * const text = univerAPI.Util.numfmt.format('#,##0.00', 1234.567);
+ * console.log(text);
+ * ```
*/
get numfmt(): INumfmt {
return numfmt;
@@ -71,6 +87,12 @@ export class FUtil {
/**
* common tools
+ *
+ * @example
+ * ```ts
+ * const key = univerAPI.Util.tools.generateRandomId(6);
+ * console.log(key);
+ * ```
*/
get tools(): typeof Tools {
return Tools;
diff --git a/packages/core/src/shared/rectangle.ts b/packages/core/src/shared/rectangle.ts
index 3690143150..4735485f5a 100644
--- a/packages/core/src/shared/rectangle.ts
+++ b/packages/core/src/shared/rectangle.ts
@@ -14,8 +14,9 @@
* limitations under the License.
*/
+import type { IRange, IRectLTRB } from '../sheets/typedef';
import type { Nullable } from './types';
-import { AbsoluteRefType, type IRange, type IRectLTRB, RANGE_TYPE } from '../sheets/typedef';
+import { AbsoluteRefType, RANGE_TYPE } from '../sheets/typedef';
import { mergeRanges, multiSubtractSingleRange, splitIntoGrid } from './range';
/**
@@ -612,18 +613,18 @@ export class Rectangle {
* ```
*/
static getIntersectionBetweenTwoRect(rect1: IRectLTRB, rect2: IRectLTRB) {
- // 计算两个矩形的交集部分的坐标
+ // Calculating the coordinates of the intersection part of the two rectangles
const left = Math.max(rect1.left, rect2.left);
const right = Math.min(rect1.right, rect2.right);
const top = Math.max(rect1.top, rect2.top);
const bottom = Math.min(rect1.bottom, rect2.bottom);
- // 如果交集部分的宽度或高度小于等于 0,说明两个矩形不相交
+ // If the width or height of the intersection part is less than or equal to 0, it means that the two rectangles do not intersect
if (right <= left || bottom <= top) {
return null;
}
- // 返回交集部分的矩形
+ // Return the rectangle of the intersection part
return {
left,
right,
diff --git a/packages/engine-formula/src/facade/f-formula.ts b/packages/engine-formula/src/facade/f-formula.ts
index 849a517a30..4effa49c59 100644
--- a/packages/engine-formula/src/facade/f-formula.ts
+++ b/packages/engine-formula/src/facade/f-formula.ts
@@ -53,13 +53,18 @@ export class FFormula extends FBase {
/**
* Offsets the formula
- * @param {string} formulaString
- * @param {number} refOffsetX
- * @param {number} refOffsetY
- * @param {boolean} [ignoreAbsolute] default is false
+ * @param {string} formulaString - The formula string to offset
+ * @param {number} refOffsetX - The offset column
+ * @param {number} refOffsetY - The offset row
+ * @param {boolean} [ignoreAbsolute] - Whether to ignore the absolute reference
+ * @returns {string} The offset formula string
+ *
* @example
- * const result = moveFormulaRefOffset('sum(a1,b2)',1,1)
- * // result is 'sum(b2,c3)'
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * const result = formulaEngine.moveFormulaRefOffset('=SUM(A1,B2)', 1, 1);
+ * console.log(result);
+ * ```
*/
moveFormulaRefOffset(formulaString: string, refOffsetX: number, refOffsetY: number, ignoreAbsolute?: boolean): string {
return this._lexerTreeBuilder.moveFormulaRefOffset(formulaString, refOffsetX, refOffsetY, ignoreAbsolute);
@@ -67,9 +72,15 @@ export class FFormula extends FBase {
/**
* Resolves the formula string to a 'node' node
- * @param {string} formulaString
- * @returns {*} {((string | ISequenceNode)[])}
- * @memberof FFormula
+ * @param {string} formulaString - The formula string to resolve
+ * @returns {Array<ISequenceNode | string>} The nodes of the formula string
+ *
+ * @example
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * const nodes = formulaEngine.sequenceNodesBuilder('=SUM(A1,B2)');
+ * console.log(nodes);
+ * ```
*/
sequenceNodesBuilder(formulaString: string): (string | ISequenceNode)[] {
return this._lexerTreeBuilder.sequenceNodesBuilder(formulaString) || [];
@@ -77,6 +88,12 @@ export class FFormula extends FBase {
/**
* Start the calculation of the formula.
+ *
+ * @example
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * formulaEngine.executeCalculation();
+ * ```
*/
executeCalculation(): void {
this._commandService.executeCommand(SetFormulaCalculationStartMutation.id, { commands: [], forceCalculation: true }, { onlyLocal: true });
@@ -84,6 +101,12 @@ export class FFormula extends FBase {
/**
* Stop the calculation of the formula.
+ *
+ * @example
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * formulaEngine.stopCalculation();
+ * ```
*/
stopCalculation(): void {
this._commandService.executeCommand(SetFormulaCalculationStopMutation.id, {});
@@ -91,7 +114,16 @@ export class FFormula extends FBase {
/**
* Listening calculation starts.
- * @param callback
+ * @param {Function} callback - The callback function to be called when the formula calculation starts.
+ * @returns {IDisposable} The disposable instance.
+ *
+ * @example
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * formulaEngine.calculationStart((forceCalculation) => {
+ * console.log('Calculation start', forceCalculation);
+ * });
+ * ```
*/
calculationStart(callback: (forceCalculation: boolean) => void): IDisposable {
return this._commandService.onCommandExecuted((command: ICommandInfo) => {
@@ -104,7 +136,16 @@ export class FFormula extends FBase {
/**
* Listening calculation ends.
- * @param callback
+ * @param {Function} callback - The callback function to be called when the formula calculation ends.
+ * @returns {IDisposable} The disposable instance.
+ *
+ * @example
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * formulaEngine.calculationEnd((functionsExecutedState) => {
+ * console.log('Calculation end', functionsExecutedState);
+ * });
+ * ```
*/
calculationEnd(callback: (functionsExecutedState: FormulaExecutedStateType) => void): IDisposable {
return this._commandService.onCommandExecuted((command: ICommandInfo) => {
@@ -127,6 +168,14 @@ export class FFormula extends FBase {
* value is 30,000 milliseconds.
* @returns {Promise<boolean>} This method returns `true` if the computing is complete. If the timeout is reached, this
* method returns `false`.
+ *
+ * @example
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * formulaEngine.whenComputingCompleteAsync(3000).then((isComplete) => {
+ * console.log('Computing complete:', isComplete);
+ * });
+ * ```
*/
whenComputingCompleteAsync(timeout?: number): Promise<boolean> {
const gcss = this._injector.get(GlobalComputingStatusService);
@@ -159,7 +208,16 @@ export class FFormula extends FBase {
/**
* Listening calculation processing.
- * @param callback
+ * @param {Function} callback - The callback function to be called when the formula calculation is in progress.
+ * @returns {IDisposable} The disposable instance.
+ *
+ * @example
+ * ```ts
+ * const formulaEngine = univerAPI.getFormula();
+ * formulaEngine.calculationProcessing((stageInfo) => {
+ * console.log('Calculation processing', stageInfo);
+ * });
+ * ```
*/
calculationProcessing(callback: (stageInfo: IExecutionInProgressParams) => void): IDisposable {
return this._commandService.onCommandExecuted((command: ICommandInfo) => {
@@ -177,7 +235,8 @@ export class FFormula extends FBase {
/**
* When a formula contains a circular reference, set the maximum number of iterations for the formula calculation.
- * @param maxIteration The maximum number of iterations. The default value is 1.
+ * @param {number} maxIteration The maximum number of iterations. The default value is 1.
+ *
* @example
* ```ts
* // Set the maximum number of iterations for the formula calculation to 5.
diff --git a/packages/sheets-formula-ui/src/controllers/formula-clipboard.controller.ts b/packages/sheets-formula-ui/src/controllers/formula-clipboard.controller.ts
index 136210cd77..e03126b5ce 100644
--- a/packages/sheets-formula-ui/src/controllers/formula-clipboard.controller.ts
+++ b/packages/sheets-formula-ui/src/controllers/formula-clipboard.controller.ts
@@ -148,6 +148,13 @@ export function getSetCellFormulaMutations(
const valueMatrix = getValueMatrix(unitId, subUnitId, range, matrix, copyInfo, lexerTreeBuilder, formulaDataModel, pasteFrom);
+ if (!valueMatrix.hasValue()) {
+ return {
+ undos: [],
+ redos: [],
+ };
+ }
+
// set cell value and style
const setValuesMutation: ISetRangeValuesMutationParams = {
unitId,
diff --git a/packages/sheets-thread-comment/src/facade/f-univer.ts b/packages/sheets-thread-comment/src/facade/f-univer.ts
index d2da527a8c..3d64057b83 100644
--- a/packages/sheets-thread-comment/src/facade/f-univer.ts
+++ b/packages/sheets-thread-comment/src/facade/f-univer.ts
@@ -27,22 +27,22 @@ import { FTheadCommentBuilder, FTheadCommentItem } from './f-thread-comment';
*/
export interface IFUniverCommentMixin {
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentAdded, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentAdded, () => {})` as instead
*/
onCommentAdded(callback: (event: ISheetCommentAddEvent) => void): IDisposable;
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentUpdated, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentUpdated, () => {})` as instead
*/
onCommentUpdated(callback: (event: ISheetCommentUpdateEvent) => void): IDisposable;
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentDeleted, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentDeleted, () => {})` as instead
*/
onCommentDeleted(callback: (event: ISheetCommentDeleteEvent) => void): IDisposable;
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentResolved, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentResolved, () => {})` as instead
*/
onCommentResolved(callback: (event: ISheetCommentResolveEvent) => void): IDisposable;
diff --git a/packages/sheets-thread-comment/src/facade/f-workbook.ts b/packages/sheets-thread-comment/src/facade/f-workbook.ts
index b28ce8988f..25f852317f 100644
--- a/packages/sheets-thread-comment/src/facade/f-workbook.ts
+++ b/packages/sheets-thread-comment/src/facade/f-workbook.ts
@@ -52,20 +52,20 @@ export interface IFWorkbookThreadCommentMixin {
clearComments(): Promise<boolean>;
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.CommentUpdated, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.CommentUpdated, () => {})` as instead
*/
onThreadCommentChange(callback: (commentUpdate: CommentUpdate) => void | false): IDisposable;
- /**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.BeforeCommentAdd, () => {})` as instead
- */
+ /**
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentAdd, () => {})` as instead
+ */
onBeforeAddThreadComment(
this: FWorkbook,
callback: (params: IAddCommentCommandParams, options: IExecutionOptions | undefined) => void | false
): IDisposable;
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.BeforeCommentUpdate, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentUpdate, () => {})` as instead
*/
onBeforeUpdateThreadComment(
this: FWorkbook,
@@ -73,7 +73,7 @@ export interface IFWorkbookThreadCommentMixin {
): IDisposable;
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.event.BeforeCommentDelete, () => {})` as instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.BeforeCommentDelete, () => {})` as instead
*/
onBeforeDeleteThreadComment(
this: FWorkbook,
diff --git a/packages/sheets/src/facade/f-defined-name.ts b/packages/sheets/src/facade/f-defined-name.ts
index bac42e711b..27ddf708fd 100644
--- a/packages/sheets/src/facade/f-defined-name.ts
+++ b/packages/sheets/src/facade/f-defined-name.ts
@@ -55,6 +55,7 @@ function getDefinedNameFieldName(unitId: string, localeService: LocaleService, d
*/
export class FDefinedNameBuilder {
private _definedNameParam: ISetDefinedNameMutationParam;
+
constructor() {
this._definedNameParam = {
id: generateRandomId(10),
@@ -67,7 +68,7 @@ export class FDefinedNameBuilder {
/**
* Sets the name of the defined name builder.
* @param {string} name The name of the defined name.
- * @returns {FDefinedNameBuilder} The defined name builder.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
@@ -85,7 +86,7 @@ export class FDefinedNameBuilder {
/**
* Sets the formula of the defined name builder.
* @param {string }formula The formula of the defined name.
- * @returns {FDefinedNameBuilder} The defined name builder.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
@@ -104,7 +105,7 @@ export class FDefinedNameBuilder {
/**
* Sets the reference of the defined name builder.
* @param {string} a1Notation The reference of the defined name.
- * @returns {FDefinedNameBuilder} The defined name builder.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
@@ -125,7 +126,7 @@ export class FDefinedNameBuilder {
* @param {number} column The start column of the range.
* @param {number} numRows The number of rows in the range.
* @param {number} numColumns The number of columns in the range.
- * @returns {FDefinedNameBuilder} The defined name builder.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
@@ -148,7 +149,7 @@ export class FDefinedNameBuilder {
/**
* Sets the comment of the defined name builder.
* @param {string} comment The comment of the defined name.
- * @returns {FDefinedNameBuilder} The defined name builder.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
@@ -166,7 +167,7 @@ export class FDefinedNameBuilder {
/**
* Sets the hidden status of the defined name builder.
* @param {boolean} hidden The hidden status of the defined name.
- * @returns {FDefinedNameBuilder} The defined name builder.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
@@ -182,14 +183,15 @@ export class FDefinedNameBuilder {
}
/**
- * Builds the defined name.
- * @returns {FDefinedNameBuilder} The defined name mutation parameter.
+ * Builds the defined name parameter.
+ * @returns {ISetDefinedNameMutationParam} The defined name mutation parameter.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
* .setRef('Sheet1!$A$1')
* .setName('MyDefinedName')
+ * .setComment('This is a comment')
* .build();
* workbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
@@ -198,6 +200,25 @@ export class FDefinedNameBuilder {
return this._definedNameParam;
}
+ /**
+ * Loads the defined name mutation parameter.
+ * @param {ISetDefinedNameMutationParam} param - defined name mutation parameter
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
+ * @example
+ * ```ts
+ * const workbook = univerAPI.getActiveWorkbook();
+ * const definedNameParam = {
+ * id: '4TMPceoqg8',
+ * unitId: workbook.getId(),
+ * name: 'MyDefinedName',
+ * formulaOrRefString: 'Sheet1!$A$1',
+ * }
+ * const definedNameBuilder = univerAPI.newDefinedName()
+ * .load(definedNameParam)
+ * .build();
+ * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * ```
+ */
load(param: ISetDefinedNameMutationParam): FDefinedNameBuilder {
this._definedNameParam = param;
return this;
@@ -236,8 +257,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * console.log(definedName.getName());
+ * const definedName = workbook.getDefinedNames()[0];
+ * console.log(definedName?.getName());
* ```
*/
getName(): string {
@@ -250,8 +271,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedName('MyDefinedName');
- * definedName.setName('NewDefinedName');
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setName('NewDefinedName');
* ```
*/
setName(name: string): void {
@@ -265,8 +286,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedName('MyDefinedName');
- * definedName.setFormula('SUM(Sheet1!$A$1)');
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setFormula('SUM(Sheet1!$A$1)');
* ```
*/
setFormula(formula: string): void {
@@ -280,8 +301,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * definedName.setRef('Sheet1!$A$1');
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setRef('Sheet1!$A$1');
* ```
*/
setRef(refString: string): void {
@@ -290,13 +311,13 @@ export class FDefinedName extends FBase {
}
/**
- * Gets the reference of the defined name.
- * @returns {string} The reference of the defined name.
+ * Gets the formula or reference string of the defined name.
+ * @returns {string} The formula or reference string of the defined name.
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * console.log(definedName.getFormulaOrRefString());
+ * const definedName = workbook.getDefinedNames()[0];
+ * console.log(definedName?.getFormulaOrRefString());
* ```
*/
getFormulaOrRefString(): string {
@@ -312,8 +333,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * definedName.setRefByRange(1, 3, 2, 5);
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setRefByRange(1, 3, 2, 5);
* ```
*/
setRefByRange(row: number, column: number, numRows: number, numColumns: number): void {
@@ -332,8 +353,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * console.log(definedName.getComment());
+ * const definedName = workbook.getDefinedNames()[0];
+ * console.log(definedName?.getComment());
* ```
*/
getComment(): string | undefined {
@@ -346,8 +367,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * definedName.setComment('This is a comment');
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setComment('This is a comment');
* ```
*/
setComment(comment: string): void {
@@ -361,9 +382,9 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getWorksheets[0];
- * const definedName = workbook.getDefinedNames[0];
- * definedName.setScopeToWorksheet(worksheet);
+ * const worksheet = workbook.getSheets()[0];
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setScopeToWorksheet(worksheet);
* ```
*/
setScopeToWorksheet(worksheet: FWorksheet): void {
@@ -376,8 +397,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * definedName.setScopeToWorkbook();
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setScopeToWorkbook();
* ```
*/
setScopeToWorkbook(): void {
@@ -391,8 +412,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * definedName.setHidden(true);
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.setHidden(true);
* ```
*/
setHidden(hidden: boolean): void {
@@ -405,8 +426,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * definedName.delete();
+ * const definedName = workbook.getDefinedNames()[0];
+ * definedName?.delete();
* ```
*/
delete(): void {
@@ -419,8 +440,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * console.log(definedName.getLocalSheetId());
+ * const definedName = workbook.getDefinedNames()[0];
+ * console.log(definedName?.getLocalSheetId());
* ```
*/
getLocalSheetId(): string | undefined {
@@ -433,8 +454,8 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * console.log(definedName.isWorkbookScope());
+ * const definedName = workbook.getDefinedNames()[0];
+ * console.log(definedName?.isWorkbookScope());
* ```
*/
isWorkbookScope(): boolean {
@@ -447,10 +468,14 @@ export class FDefinedName extends FBase {
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames[0];
- * const definedNameBuilder = definedName.toBuilder();
- * const param definedNameBuilder.setName('NewDefinedName').setFormula('SUM(Sheet1!$A$1)').build();
- * workbook.updateDefinedNameBuilder(param);
+ * const definedName = workbook.getDefinedNames()[0];
+ * if (!definedName) return;
+ * const definedNameBuilder = definedName
+ * .toBuilder()
+ * .setName('NewDefinedName')
+ * .setFormula('SUM(Sheet1!$A$1)')
+ * .build();
+ * workbook.updateDefinedNameBuilder(definedNameBuilder);
* ```
*/
toBuilder(): FDefinedNameBuilder {
diff --git a/packages/sheets/src/facade/f-enum.ts b/packages/sheets/src/facade/f-enum.ts
index 228c438ae4..28c90abdba 100644
--- a/packages/sheets/src/facade/f-enum.ts
+++ b/packages/sheets/src/facade/f-enum.ts
@@ -15,7 +15,7 @@
*/
import { FEnum } from '@univerjs/core/facade';
-import { SheetSkeletonChangeType, SheetValueChangeType } from '@univerjs/sheets';
+import { SheetSkeletonChangeType, SheetValueChangeType, SplitDelimiterEnum } from '@univerjs/sheets';
/**
* @ignore
@@ -32,6 +32,11 @@ export interface IFSheetsEnum {
* Includes operations like changing row/column dimensions, visibility, and grid properties.
*/
SheetSkeletonChangeType: typeof SheetSkeletonChangeType;
+
+ /**
+ * Split delimiter types.
+ */
+ SplitDelimiterType: typeof SplitDelimiterEnum;
}
export class FSheetsEnum implements IFSheetsEnum {
@@ -42,6 +47,10 @@ export class FSheetsEnum implements IFSheetsEnum {
get SheetSkeletonChangeType(): typeof SheetSkeletonChangeType {
return SheetSkeletonChangeType;
}
+
+ get SplitDelimiterType(): typeof SplitDelimiterEnum {
+ return SplitDelimiterEnum;
+ }
}
FEnum.extend(FSheetsEnum);
diff --git a/packages/sheets/src/facade/f-event.ts b/packages/sheets/src/facade/f-event.ts
index 0fa6a42582..e7fbc79831 100644
--- a/packages/sheets/src/facade/f-event.ts
+++ b/packages/sheets/src/facade/f-event.ts
@@ -39,7 +39,8 @@ export interface IFSheetEventMixin {
* });
* ```
*/
- get SheetCreated(): 'SheetCreated' ;
+ get SheetCreated(): 'SheetCreated';
+
/**
* Event fired before a sheet is created
* @see {@link IBeforeSheetCreateEventParams}
@@ -52,18 +53,20 @@ export interface IFSheetEventMixin {
* ```
*/
get BeforeSheetCreate(): 'BeforeSheetCreate';
+
/**
* Event fired before the active sheet changes
- * @see {@link IActiveSheetChangedEvent}
+ * @see {@link IBeforeActiveSheetChangeEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.Event.ActiveSheetChanged, (params) => {
+ * univerAPI.addEvent(univerAPI.Event.BeforeActiveSheetChange, (params) => {
* const { workbook, activeSheet, oldActiveSheet } = params;
- * console.log('before active sheet changed', params);
+ * console.log('before active sheet change', params);
* });
* ```
*/
get BeforeActiveSheetChange(): 'BeforeActiveSheetChange';
+
/**
* Event fired after the active sheet changes
* @see {@link IActiveSheetChangedEvent}
@@ -76,18 +79,20 @@ export interface IFSheetEventMixin {
* ```
*/
get ActiveSheetChanged(): 'ActiveSheetChanged';
+
/**
- * Event fired before a sheet is deleted
- * @see {@link IBeforeSheetDeleteEvent}
+ * Event fired after a sheet is deleted
+ * @see {@link ISheetDeletedEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.Event.BeforeSheetDelete, (params) => {
- * const { workbook, worksheetId } = params;
- * console.log('before sheet delete', params);
+ * univerAPI.addEvent(univerAPI.Event.SheetDeleted, (params) => {
+ * const { workbook, sheetId } = params;
+ * console.log('sheet deleted', params);
* });
* ```
*/
get SheetDeleted(): 'SheetDeleted';
+
/**
* Event fired before a sheet is deleted
* @see {@link IBeforeSheetDeleteEvent}
@@ -100,6 +105,7 @@ export interface IFSheetEventMixin {
* ```
*/
get BeforeSheetDelete(): 'BeforeSheetDelete';
+
/**
* Event fired after a sheet is moved
* @see {@link ISheetMovedEvent}
@@ -112,6 +118,7 @@ export interface IFSheetEventMixin {
* ```
*/
get SheetMoved(): 'SheetMoved';
+
/**
* Event fired before a sheet is moved
* @see {@link IBeforeSheetMoveEvent}
@@ -124,6 +131,7 @@ export interface IFSheetEventMixin {
* ```
*/
get BeforeSheetMove(): 'BeforeSheetMove';
+
/**
* Event fired after a sheet name is changed
* @see {@link ISheetNameChangedEvent}
@@ -136,6 +144,7 @@ export interface IFSheetEventMixin {
* ```
*/
get SheetNameChanged(): 'SheetNameChanged';
+
/**
* Event fired before a sheet name is changed
* @see {@link IBeforeSheetNameChangeEvent}
@@ -143,59 +152,64 @@ export interface IFSheetEventMixin {
* ```ts
* univerAPI.addEvent(univerAPI.Event.BeforeSheetNameChange, (params) => {
* const { workbook, worksheet, newName, oldName } = params;
- * console.log('before sheet name changed', params);
+ * console.log('before sheet name change', params);
* });
* ```
*/
get BeforeSheetNameChange(): 'BeforeSheetNameChange';
+
/**
* Event fired after a sheet tab color is changed
* @see {@link ISheetTabColorChangedEvent}
* @example
* ```ts
* univerAPI.addEvent(univerAPI.Event.SheetTabColorChanged, (params) => {
- * const { workbook, worksheet, color } = params;
+ * const { workbook, worksheet, newColor } = params;
* console.log('sheet tab color changed', params);
* });
* ```
*/
get SheetTabColorChanged(): 'SheetTabColorChanged';
+
/**
* Event fired before a sheet tab color is changed
* @see {@link IBeforeSheetTabColorChangeEvent}
* @example
* ```ts
* univerAPI.addEvent(univerAPI.Event.BeforeSheetTabColorChange, (params) => {
- * const { workbook, worksheet, color, oldColor } = params;
- * console.log('before sheet tab color changed', params);
+ * const { workbook, worksheet, newColor, oldColor } = params;
+ * console.log('before sheet tab color change', params);
* });
* ```
*/
get BeforeSheetTabColorChange(): 'BeforeSheetTabColorChange';
+
/**
* Event fired after a sheet is hidden
* @see {@link ISheetHideChangedEvent}
* @example
* ```ts
* univerAPI.addEvent(univerAPI.Event.SheetHideChanged, (params) => {
- * const { workbook, worksheet } = params;
+ * const { workbook, worksheet, hidden } = params;
* console.log('sheet hide changed', params);
* });
* ```
*/
get SheetHideChanged(): 'SheetHideChanged';
+
/**
* Event fired before a sheet is hidden
* @see {@link IBeforeSheetHideChangeEvent}
* @example
* ```ts
* univerAPI.addEvent(univerAPI.Event.BeforeSheetHideChange, (params) => {
- * const { workbook, worksheet, hide } = params;
- * console.log('before sheet hide changed', params);
+ * const { workbook, worksheet, hidden } = params;
+ * console.log('before sheet hide change', params);
* });
* ```
*/
get BeforeSheetHideChange(): 'BeforeSheetHideChange';
+
/**
* Event fired after a workbook is created
* @see {@link IWorkbookCreateParam}
@@ -208,6 +222,7 @@ export interface IFSheetEventMixin {
* ```
*/
get WorkbookCreated(): 'WorkbookCreated';
+
/**
* Event fired after a workbook is disposed
* @see {@link IWorkbookDisposedEvent}
@@ -215,7 +230,7 @@ export interface IFSheetEventMixin {
* ```ts
* univerAPI.addEvent(univerAPI.Event.WorkbookDisposed, (params) => {
* const { unitId, unitType, snapshot } = params;
- * console.log('unit disposed', params);
+ * console.log('workbook disposed', params);
* });
* ```
*/
@@ -241,7 +256,7 @@ export interface IFSheetEventMixin {
* ```ts
* univerAPI.addEvent(univerAPI.Event.BeforeGridlineEnableChange, (params) => {
* const { workbook, worksheet, enabled } = params;
- * console.log('gridline changed', params);
+ * console.log('before gridline enable change', params);
* });
* ```
*/
@@ -254,7 +269,7 @@ export interface IFSheetEventMixin {
* ```ts
* univerAPI.addEvent(univerAPI.Event.BeforeGridlineColorChange, (params) => {
* const { workbook, worksheet, color } = params;
- * console.log('gridline changed', params);
+ * console.log('before gridline color change', params);
* });
* ```
*/
@@ -262,10 +277,12 @@ export interface IFSheetEventMixin {
/**
* Event fired when sheet value changed
+ * @see {@link ISheetValueChangedEvent}
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (p)=> {
- * const { workbook, effectedRanges, payload } = p;
+ * univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params)=> {
+ * const { effectedRanges, payload } = params;
+ * console.log('sheet value changed', params);
* });
* ```
*/
diff --git a/packages/sheets/src/facade/f-permission.ts b/packages/sheets/src/facade/f-permission.ts
index 7cad62dc6a..2e60af3dd7 100644
--- a/packages/sheets/src/facade/f-permission.ts
+++ b/packages/sheets/src/facade/f-permission.ts
@@ -195,6 +195,7 @@ export class FPermission extends FBase {
* const permissionId = await permission.addWorksheetBasePermission(unitId, subUnitId)
* // After this line of code , the worksheet will no longer be editable
* permission.setWorksheetPermissionPoint(unitId, subUnitId, permission.permissionPointsDefinition.WorksheetEditPermission, false);
+ * ```
*/
async setWorksheetPermissionPoint(unitId: string, subUnitId: string, FPointClass: WorkSheetPermissionPointConstructor, value: boolean): Promise<string | undefined> {
const hasBasePermission = this._worksheetProtectionRuleModel.getRule(unitId, subUnitId);
@@ -249,12 +250,12 @@ export class FPermission extends FBase {
*
* @example
* ```typescript
- *const workbook = univerAPI.getActiveWorkbook();
+ * const workbook = univerAPI.getActiveWorkbook();
* const permission = workbook.getPermission();
* const unitId = workbook.getId();
* const worksheet = workbook.getActiveSheet();
* const subUnitId = worksheet.getSheetId();
- * const range = worksheet.getRange(0,0,2,2);
+ * const range = worksheet.getRange('A1:B2');
* const ranges = [];
* ranges.push(range);
* // Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
@@ -326,7 +327,7 @@ export class FPermission extends FBase {
* const unitId = workbook.getId();
* const worksheet = workbook.getActiveSheet();
* const subUnitId = worksheet.getSheetId();
- * const range = worksheet.getRange(0,0,2,2);
+ * const range = worksheet.getRange('A1:B2');
* const ranges = [];
* ranges.push(range);
* const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
@@ -369,7 +370,7 @@ export class FPermission extends FBase {
* const unitId = workbook.getId();
* const worksheet = workbook.getActiveSheet();
* const subUnitId = worksheet.getSheetId();
- * const range = worksheet.getRange(0, 0, 2, 2);
+ * const range = worksheet.getRange('A1:B2');
* const ranges = [];
* ranges.push(range);
* // Note that there will be no permission changes after this step is completed. It only returns an ID for subsequent permission changes.
@@ -398,7 +399,7 @@ export class FPermission extends FBase {
* @param {string} unitId - The unique identifier of the workbook.
* @param {string} subUnitId - The unique identifier of the worksheet within the workbook.
* @param {string} ruleId - The ruleId of the range protection rule that is being updated.
- * @param {IRange[]} ranges - The array of new ranges to be set for the range protection rule.
+ * @param {FRange[]} ranges - The array of new ranges to be set for the range protection rule.
*
* @example
* ```typescript
@@ -407,12 +408,12 @@ export class FPermission extends FBase {
* const unitId = workbook.getId();
* const worksheet = workbook.getActiveSheet();
* const subUnitId = worksheet.getSheetId();
- * const range = worksheet.getRange(0, 0, 2, 2);
+ * const range = worksheet.getRange('A1:B2');
* const ranges = [];
* ranges.push(range);
* const res = await permission.addRangeBaseProtection(unitId, subUnitId, ranges);
* const {permissionId, ruleId} = res;
- * const newRange = worksheet.getRange(3, 3, 2, 2);
+ * const newRange = worksheet.getRange('C1:D2');
* permission.setRangeProtectionRanges(unitId, subUnitId, ruleId, [newRange]);
* ```
*/
diff --git a/packages/sheets/src/facade/f-range.ts b/packages/sheets/src/facade/f-range.ts
index b15ba1a756..adb87d2ade 100644
--- a/packages/sheets/src/facade/f-range.ts
+++ b/packages/sheets/src/facade/f-range.ts
@@ -51,10 +51,10 @@ export class FRange extends FBaseInitialable {
* @returns {string} The unit ID of the workbook
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getUnitId()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getUnitId());
* ```
*/
getUnitId(): string {
@@ -66,10 +66,10 @@ export class FRange extends FBaseInitialable {
* @returns {string} The name of the worksheet
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getSheetName()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getSheetName());
* ```
*/
getSheetName(): string {
@@ -81,10 +81,10 @@ export class FRange extends FBaseInitialable {
* @returns {string} The ID of the worksheet
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getSheetId()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getSheetId());
* ```
*/
getSheetId(): string {
@@ -96,10 +96,12 @@ export class FRange extends FBaseInitialable {
* @returns {IRange} The area where the statement is applied
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getRange()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * const range = fRange.getRange();
+ * const { startRow, startColumn, endRow, endColumn } = range;
+ * console.log(range);
* ```
*/
getRange(): IRange {
@@ -111,10 +113,10 @@ export class FRange extends FBaseInitialable {
* @returns {number} The starting row number of the area
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getRow()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getRow());
* ```
*/
getRow(): number {
@@ -126,10 +128,10 @@ export class FRange extends FBaseInitialable {
* @returns {number} The starting column number of the area
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getColumn()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getColumn());
* ```
*/
getColumn(): number {
@@ -141,10 +143,10 @@ export class FRange extends FBaseInitialable {
* @returns {number} The width of the area
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getWidth()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getWidth());
* ```
*/
getWidth(): number {
@@ -156,10 +158,10 @@ export class FRange extends FBaseInitialable {
* @returns {number} The height of the area
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getHeight()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getHeight());
* ```
*/
getHeight(): number {
@@ -171,10 +173,13 @@ export class FRange extends FBaseInitialable {
* @returns {boolean} if true is merged
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .isMerged()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.isMerged());
+ * // merge cells A1:B2
+ * fRange.merge();
+ * console.log(fRange.isMerged());
* ```
*/
isMerged(): boolean {
@@ -188,10 +193,10 @@ export class FRange extends FBaseInitialable {
* @returns {IStyleData | null} The cell style data
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCellStyleData()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCellStyleData());
* ```
*/
getCellStyleData(): IStyleData | null {
@@ -209,10 +214,10 @@ export class FRange extends FBaseInitialable {
* @returns {TextStyleValue | null} The cell style
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCellStyle()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCellStyle());
* ```
*/
getCellStyle(): TextStyleValue | null {
@@ -225,10 +230,10 @@ export class FRange extends FBaseInitialable {
* @returns {Array<Array<TextStyleValue | null>>} A two-dimensional array of cell styles.
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCellStyles()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCellStyles());
* ```
*/
getCellStyles(): Array<Array<TextStyleValue | null>> {
@@ -246,10 +251,14 @@ export class FRange extends FBaseInitialable {
* @returns {CellValue | null} The cell value
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getValue()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getValue());
+ *
+ * // set the first cell value to 123
+ * fRange.setValueForCell(123);
+ * console.log(fRange.getValue()); // 123
* ```
*/
getValue(): CellValue | null;
@@ -260,10 +269,17 @@ export class FRange extends FBaseInitialable {
* @returns {CellValue | RichTextValue | null} The cell value
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getValue(true)
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * 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' } })
+ * .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
+ * .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
+ * fRange.setRichTextValueForCell(richText);
+ * console.log(fRange.getValue(true).toPlainText()); // Hello World
* ```
*/
getValue(includeRichText: true): Nullable<CellValue | RichTextValue>;
@@ -281,7 +297,10 @@ export class FRange extends FBaseInitialable {
* @example
* ```ts
* // Get plain values
- * const values = range.getValues();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getValues());
* ```
*/
getValues(): Nullable<CellValue>[][];
@@ -293,16 +312,16 @@ export class FRange extends FBaseInitialable {
* @example
* ```ts
* // Get values with rich text if available
- * const richTextValues = univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getValues(true)
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getValues(true));
* ```
*/
getValues(includeRichText: true): (Nullable<RichTextValue | CellValue>)[][];
getValues(includeRichText?: true): (Nullable<RichTextValue | CellValue>)[][] {
if (includeRichText) {
- this.getValueAndRichTextValues();
+ return this.getValueAndRichTextValues();
}
const { startRow, endRow, startColumn, endColumn } = this._range;
@@ -325,10 +344,10 @@ export class FRange extends FBaseInitialable {
* @returns {ICellData | null} The cell model data
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCellData()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCellData());
* ```
*/
getCellData(): ICellData | null {
@@ -340,10 +359,10 @@ export class FRange extends FBaseInitialable {
* @returns {Nullable<ICellData>[][]} A two-dimensional array of cell data.
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCellDatas()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCellDatas());
* ```
*/
getCellDatas(): Nullable<ICellData>[][] {
@@ -355,10 +374,10 @@ export class FRange extends FBaseInitialable {
* @returns {Nullable<ICellData>[][]} A two-dimensional array of cell data.
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCellDataGrid()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCellDataGrid());
* ```
*/
getCellDataGrid(): Nullable<ICellData>[][] {
@@ -382,10 +401,10 @@ export class FRange extends FBaseInitialable {
* @beta
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getRichTextValue()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getRichTextValue());
* ```
*/
private getRichTextValue(): Nullable<RichTextValue> {
@@ -404,10 +423,10 @@ export class FRange extends FBaseInitialable {
* @beta
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getRichTextValues()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getRichTextValues());
* ```
*/
private getRichTextValues(): Nullable<RichTextValue>[][] {
@@ -422,10 +441,10 @@ export class FRange extends FBaseInitialable {
* @beta
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getValueAndRichTextValue()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getValueAndRichTextValue());
* ```
*/
private getValueAndRichTextValue(): Nullable<CellValue | RichTextValue> {
@@ -438,10 +457,10 @@ export class FRange extends FBaseInitialable {
* @returns {Nullable<CellValue | RichTextValue>[][]} A two-dimensional array of value and rich text value
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getValueAndRichTextValues()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getValueAndRichTextValues());
* ```
*/
getValueAndRichTextValues(): Nullable<CellValue | RichTextValue>[][] {
@@ -454,10 +473,10 @@ export class FRange extends FBaseInitialable {
* @returns {string[][]} A two-dimensional array of formulas in string format.
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getFormulas()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getFormulas());
* ```
*/
getFormulas(): string[][] {
@@ -482,14 +501,14 @@ export class FRange extends FBaseInitialable {
}
/**
- * Returns true if the cell wrap is enabled
+ * Returns true if the cell wrap is enabled for the top left cell of the range.
* @returns {boolean} True if the cell wrap is enabled
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getWrap()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getWrap());
* ```
*/
getWrap(): boolean {
@@ -501,10 +520,10 @@ export class FRange extends FBaseInitialable {
* @returns {WrapStrategy} The text wrapping strategy
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getWrapStrategy()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getWrapStrategy());
* ```
*/
getWrapStrategy(): WrapStrategy {
@@ -516,10 +535,10 @@ export class FRange extends FBaseInitialable {
* @returns {string} The horizontal alignment
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getHorizontalAlignment()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getHorizontalAlignment());
* ```
*/
getHorizontalAlignment(): string {
@@ -531,10 +550,10 @@ export class FRange extends FBaseInitialable {
* @returns {string} The vertical alignment
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getVerticalAlignment()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getVerticalAlignment());
* ```
*/
getVerticalAlignment(): string {
@@ -546,10 +565,11 @@ export class FRange extends FBaseInitialable {
* @param {CustomData} data The custom meta data
* @returns {FRange} This range, for chaining
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setCustomMetaData({ key: 'value' });
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setCustomMetaData({ key: 'value' });
+ * console.log(fRange.getCustomMetaData());
* ```
*/
setCustomMetaData(data: CustomData): FRange {
@@ -563,10 +583,14 @@ export class FRange extends FBaseInitialable {
* @param {CustomData[][]} datas The custom meta data
* @returns {FRange} This range, for chaining
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setCustomMetaDatas([[{ key: 'value' }]]);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setCustomMetaDatas([
+ * [{ key: 'value' }, { key: 'value2' }],
+ * [{ key: 'value3' }, { key: 'value4' }],
+ * ]);
+ * console.log(fRange.getCustomMetaDatas());
* ```
*/
setCustomMetaDatas(datas: CustomData[][]): FRange {
@@ -578,10 +602,10 @@ export class FRange extends FBaseInitialable {
* @returns {CustomData | null} The custom meta data
* @example
* ```
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCustomMetaData()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCustomMetaData());
* ```
*/
getCustomMetaData(): CustomData | null {
@@ -594,10 +618,10 @@ export class FRange extends FBaseInitialable {
* @returns {CustomData[][]} A two-dimensional array of custom meta data
* @example
* ```
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .getCustomMetaDatas()
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * console.log(fRange.getCustomMetaDatas());
* ```
*/
getCustomMetaDatas(): Nullable<CustomData>[][] {
@@ -613,10 +637,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setBorder(BorderType.ALL, BorderStyleType.THIN, '#ff0000');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setBorder(univerAPI.Enum.BorderType.ALL, univerAPI.Enum.BorderStyleTypes.THIN, '#ff0000');
* ```
*/
setBorder(type: BorderType, style: BorderStyleTypes, color?: string): FRange {
@@ -641,10 +665,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setBackgroundColor('red')
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setBackgroundColor('red');
* ```
*/
setBackgroundColor(color: string): FRange {
@@ -668,7 +692,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```typescript
- * univerAPI.getActiveWorkbook().getActiveSheet().getActiveRange().setBackground('red')
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setBackground('red');
* ```
*/
setBackground(color: string): FRange {
@@ -677,14 +704,17 @@ export class FRange extends FBaseInitialable {
}
/**
- * Set new value for current cell, first cell in this range.
+ * Sets the value of the range.
* @param {CellValue | ICellData} value The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
* @returns {FRange} This range, for chaining
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setValue(1);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('B2');
+ * fRange.setValue(123);
+ *
+ * // or
+ * fRange.setValue({ v: 234, s: { bg: { rgb: '#ff0000' } } });
* ```
*/
setValue(value: CellValue | ICellData): FRange {
@@ -709,10 +739,13 @@ export class FRange extends FBaseInitialable {
* @param {CellValue | ICellData} value The value can be a number, string, boolean, or standard cell format. If it begins with `=`, it is interpreted as a formula. The value is tiled to all cells in the range.
* @returns {FRange} This range, for chaining
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setValueForCell(1);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setValueForCell(123);
+ *
+ * // or
+ * fRange.setValueForCell({ v: 234, s: { bg: { rgb: '#ff0000' } } });
* ```
*/
setValueForCell(value: CellValue | ICellData): FRange {
@@ -728,8 +761,8 @@ export class FRange extends FBaseInitialable {
range: {
startColumn: this._range.startColumn,
startRow: this._range.startRow,
- endColumn: this._range.endColumn,
- endRow: this._range.endRow,
+ endColumn: this._range.startColumn,
+ endRow: this._range.startRow,
},
value: realValue,
});
@@ -743,10 +776,17 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} The range
* @example
* ```
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setRichTextValueForCell(new RichTextValue().insertText('Hello'));
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * 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' } })
+ * .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
+ * .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
+ * fRange.setRichTextValueForCell(richText);
+ * console.log(fRange.getValue(true).toPlainText()); // Hello World
* ```
*/
setRichTextValueForCell(value: RichTextValue | IDocumentData): FRange {
@@ -757,8 +797,8 @@ export class FRange extends FBaseInitialable {
range: {
startColumn: this._range.startColumn,
startRow: this._range.startRow,
- endColumn: this._range.endColumn,
- endRow: this._range.endRow,
+ endColumn: this._range.startColumn,
+ endRow: this._range.startRow,
},
value: { p },
};
@@ -772,11 +812,20 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} The range
* @example
* ```ts
- * univerAPI
- * .getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setRichTextValues([[new RichTextValue().insertText('Hello')]]);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * 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' } })
+ * .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
+ * .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } });
+ * fRange.setRichTextValues([
+ * [richText, richText],
+ * [null, null]
+ * ]);
+ * console.log(fRange.getValue(true).toPlainText()); // Hello World
* ```
*/
setRichTextValues(values: (RichTextValue | IDocumentData)[][]): FRange {
@@ -800,10 +849,11 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} this range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setWrap(true);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setWrap(true);
+ * console.log(fRange.getWrap());
* ```
*/
setWrap(isWrapEnabled: boolean): FRange {
@@ -823,10 +873,11 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} this range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setWrapStrategy(WrapStrategy.WRAP);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setWrapStrategy(univerAPI.Enum.WrapStrategy.WRAP);
+ * console.log(fRange.getWrapStrategy());
* ```
*/
setWrapStrategy(strategy: WrapStrategy): FRange {
@@ -846,10 +897,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} this range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setVerticalAlignment('top');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setVerticalAlignment('top');
* ```
*/
setVerticalAlignment(alignment: FVerticalAlignment): FRange {
@@ -869,10 +920,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} this range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setHorizontalAlignment('left');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setHorizontalAlignment('left');
* ```
*/
setHorizontalAlignment(alignment: FHorizontalAlignment): FRange {
@@ -892,10 +943,13 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setValues([[1, 2], [3, 4]]);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setValues([
+ * [1, { v: 2, s: { bg: { rgb: '#ff0000' } } }],
+ * [3, 4]
+ * ]);
* ```
*/
setValues(
@@ -923,10 +977,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setFontWeight('bold');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setFontWeight('bold');
* ```
*/
setFontWeight(fontWeight: FontWeight | null): this {
@@ -964,10 +1018,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setFontStyle('italic');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setFontStyle('italic');
* ```
*/
setFontStyle(fontStyle: FontStyle | null): this {
@@ -1005,10 +1059,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setFontLine('underline');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setFontLine('underline');
* ```
*/
setFontLine(fontLine: FontLine | null): this {
@@ -1040,13 +1094,6 @@ export class FRange extends FBaseInitialable {
* Sets the font underline style of the given ITextDecoration
* @param {ITextDecoration|null} value The font underline style of the given ITextDecoration; a null value resets the font underline style
* @returns {void}
- * @example
- * ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setFontLine('underline');
- * ```
*/
private _setFontUnderline(value: ITextDecoration | null): void {
const style: IStyleTypeValue<ITextDecoration | null> = {
@@ -1089,10 +1136,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setFontFamily('Arial');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setFontFamily('Arial');
* ```
*/
setFontFamily(fontFamily: string | null): this {
@@ -1118,10 +1165,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setFontSize(12);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setFontSize(24);
* ```
*/
setFontSize(size: number | null): this {
@@ -1147,10 +1194,10 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * univerAPI.getActiveWorkbook()
- * .getActiveSheet()
- * .getActiveRange()
- * .setFontColor('#ff0000');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.setFontColor('#ff0000');
* ```
*/
setFontColor(color: string | null): this {
@@ -1182,12 +1229,11 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getActiveSheet();
- * const range = worksheet.getRange(0, 0, 2, 2);
- * const merge = range.merge();
- * const isMerged = merge.isMerged();
- * console.log('debugger', isMerged);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.merge();
+ * console.log(fRange.isMerged());
* ```
*/
merge(defaultMerge: boolean = true): FRange {
@@ -1205,12 +1251,16 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getActiveSheet();
- * const range = worksheet.getRange(2, 2, 2, 2);
- * const merge = range.mergeAcross();
- * const allMerge = worksheet.getMergeData();
- * console.log(allMerge.length); // There will be two merged cells.
+ * // Assume the active sheet is a new sheet with no merged cells.
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.mergeAcross();
+ * // There will be two merged cells. A1:B1 and A2:B2.
+ * const mergeData = fWorksheet.getMergeData();
+ * mergeData.forEach((item) => {
+ * console.log(item.getA1Notation());
+ * });
* ```
*/
mergeAcross(defaultMerge: boolean = true): FRange {
@@ -1229,12 +1279,16 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getActiveSheet();
- * const range = worksheet.getRange(4, 4, 2, 2);
- * const merge = range.mergeVertically();
- * const allMerge = worksheet.getMergeData();
- * console.log(allMerge.length); // There will be two merged cells.
+ * // Assume the active sheet is a new sheet with no merged cells.
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.mergeVertically();
+ * // There will be two merged cells. A1:A2 and B1:B2.
+ * const mergeData = fWorksheet.getMergeData();
+ * mergeData.forEach((item) => {
+ * console.log(item.getA1Notation());
+ * });
* ```
*/
mergeVertically(defaultMerge: boolean = true): FRange {
@@ -1252,13 +1306,12 @@ export class FRange extends FBaseInitialable {
* @returns {boolean} is overlap with a merged cell
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getActiveSheet();
- * const range = worksheet.getRange(0,0,2,2);
- * const merge = range.merge();
- * const anchor = worksheet.getRange(0,0);
- * const isPartOfMerge = anchor.isPartOfMerge();
- * console.log('debugger', isPartOfMerge); // true
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.merge();
+ * const anchor = fWorksheet.getRange('A1');
+ * console.log(anchor.isPartOfMerge()); // true
* ```
*/
isPartOfMerge(): boolean {
@@ -1271,16 +1324,14 @@ export class FRange extends FBaseInitialable {
* @returns {FRange} This range, for chaining
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getActiveSheet();
- * const range = worksheet.getRange(0,0,2,2);
- * const merge = range.merge();
- * const anchor = worksheet.getRange(0,0);
- * const isPartOfMergeFirst = anchor.isPartOfMerge();
- * console.log('debugger' isPartOfMergeFirst) // true
- * range.breakApart();
- * const isPartOfMergeSecond = anchor.isPartOfMerge();
- * console.log('debugger' isPartOfMergeSecond) // false
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.merge();
+ * const anchor = fWorksheet.getRange('A1');
+ * console.log(anchor.isPartOfMerge()); // true
+ * fRange.breakApart();
+ * console.log(anchor.isPartOfMerge()); // false
* ```
*/
breakApart(): FRange {
@@ -1353,6 +1404,16 @@ export class FRange extends FBaseInitialable {
* If the specified cell is not part of an existing range, then a new range is created with the cell as the active range and the current cell.
* @returns {FRange} This range, for chaining.
* @description If the range is not a single cell, an error will be thrown.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.activate();
+ * const cell = fWorksheet.getRange('B2');
+ * cell.activateAsCurrentCell(); // the active cell will be B2
+ * console.log(fWorksheet.getActiveRange().getA1Notation()); // B2
+ * ```
*/
activateAsCurrentCell(): FRange {
const mergeInfo = this._worksheet.getMergedCell(this._range.startRow, this._range.startColumn);
@@ -1371,58 +1432,102 @@ export class FRange extends FBaseInitialable {
* Splits a column of text into multiple columns based on an auto-detected delimiter.
* @param {boolean} [treatMultipleDelimitersAsOne] Whether to treat multiple continuous delimiters as one. The default value is false.
* @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
* // A1:A3 has following values:
- * // A | B | C
- * // 1,2,3 | |
+ * // A | B | C
+ * // 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]
+ * ]);
+ *
* // After calling splitTextToColumns(true), the range will be:
- * // A | B | C
+ * // A | |
* // 1 | 2 | 3
* // 4 | 5 | 6
+ * fRange.splitTextToColumns(true);
+ *
* // After calling splitTextToColumns(false), the range will be:
- * // A | B | C | D
+ * // A | | |
* // 1 | 2 | 3 |
* // 4 | | 5 | 6
+ * fRange.splitTextToColumns(false);
+ * ```
*/
splitTextToColumns(treatMultipleDelimitersAsOne?: boolean): void;
/**
* Splits a column of text into multiple columns based on a specified delimiter.
* @param {boolean} [treatMultipleDelimitersAsOne] Whether to treat multiple continuous delimiters as one. The default value is false.
* @param {SplitDelimiterEnum} [delimiter] The delimiter to use to split the text. The default delimiter is Tab(1)、Comma(2)、Semicolon(4)、Space(8)、Custom(16).A delimiter like 6 (SplitDelimiterEnum.Comma|SplitDelimiterEnum.Semicolon) means using Comma and Semicolon to split the text.
- * @returns {void}
- */
- splitTextToColumns(treatMultipleDelimitersAsOne?: boolean, delimiter?: SplitDelimiterEnum): void;
- /**
- * Splits a column of text into multiple columns based on a custom specified delimiter.
- * @param {boolean} [treatMultipleDelimitersAsOne] Whether to treat multiple continuous delimiters as one. The default value is false.
- * @param {SplitDelimiterEnum} [delimiter] The delimiter to use to split the text. The default delimiter is Tab(1)、Comma(2)、Semicolon(4)、Space(8)、Custom(16).A delimiter like 6 (SplitDelimiterEnum.Comma|SplitDelimiterEnum.Semicolon) means using Comma and Semicolon to split the text.
- * @param {string} [customDelimiter] The custom delimiter to split the text. An error will be thrown if custom delimiter is set but the customDelimiter is not a character.
* @example Show how to split text to columns with combined delimiter. The bit operations are used to combine the delimiters.
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
* // A1:A3 has following values:
* // A | B | C
* // 1;;2;3 | |
* // 1;,2;3 | |
- * // After calling splitTextToColumns(false, SplitDelimiterEnum.Semicolon|SplitDelimiterEnum.Comma), the range will be:
- * // A | B | C | D
+ * const fRange = fWorksheet.getRange('A1:A3');
+ * fRange.setValues([
+ * ['A', 'B', 'C'],
+ * ['1;;2;3', null, null],
+ * ['1;,2;3', null, null]
+ * ]);
+ *
+ * // After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma), the range will be:
+ * // A | | |
* // 1 | | 2 | 3
* // 1 | | 2 | 3
- * // After calling splitTextToColumns(true, SplitDelimiterEnum.Semicolon|SplitDelimiterEnum.Comma), the range will be:
- * // A | B | C
+ * fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma);
+ *
+ * // After calling splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma), the range will be:
+ * // A | |
* // 1 | 2 | 3
* // 1 | 2 | 3
+ * fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Semicolon|univerAPI.Enum.SplitDelimiterType.Comma);
+ * ```
+ */
+ splitTextToColumns(treatMultipleDelimitersAsOne?: boolean, delimiter?: SplitDelimiterEnum): void;
+ /**
+ * Splits a column of text into multiple columns based on a custom specified delimiter.
+ * @param {boolean} [treatMultipleDelimitersAsOne] Whether to treat multiple continuous delimiters as one. The default value is false.
+ * @param {SplitDelimiterEnum} [delimiter] The delimiter to use to split the text. The default delimiter is Tab(1)、Comma(2)、Semicolon(4)、Space(8)、Custom(16).A delimiter like 6 (SplitDelimiterEnum.Comma|SplitDelimiterEnum.Semicolon) means using Comma and Semicolon to split the text.
+ * @param {string} [customDelimiter] The custom delimiter to split the text. An error will be thrown if custom delimiter is set but the customDelimiter is not a character.
* @example Show how to split text to columns with custom delimiter
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ *
* // A1:A3 has following values:
* // A | B | C
* // 1#2#3 | |
* // 4##5#6 | |
- * // After calling splitTextToColumns(false, SplitDelimiterEnum.Custom, '#'), the range will be:
- * // A | B | C | D
+ * const fRange = fWorksheet.getRange('A1:A3');
+ * fRange.setValues([
+ * ['A', 'B', 'C'],
+ * ['1#2#3', null, null],
+ * ['4##5#6', null, null]
+ * ]);
+ *
+ * // After calling splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be:
+ * // A | | |
* // 1 | 2 | 3 |
* // 4 | | 5 | 6
- * // After calling splitTextToColumns(true, SplitDelimiterEnum.Custom, '#'), the range will be:
- * // A | B | C
+ * fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#');
+ *
+ * // After calling splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#'), the range will be:
+ * // A | |
* // 1 | 2 | 3
* // 4 | 5 | 6
+ * fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#');
+ * ```
*/
splitTextToColumns(treatMultipleDelimitersAsOne?: boolean, delimiter?: SplitDelimiterEnum, customDelimiter?: string): void {
this._commandService.syncExecuteCommand(SplitTextToColumnsCommand.id, {
@@ -1490,9 +1595,9 @@ export class FRange extends FBaseInitialable {
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
* const fRange = fWorksheet.getRange('A1:E20');
+ * console.log(fRange.getUsedThemeStyle()); // undefined
* fRange.useThemeStyle('default');
- * const themeStyle = fRange.getUsedThemeStyle();
- * console.log(themeStyle); // 'default'
+ * console.log(fRange.getUsedThemeStyle()); // 'default'
* ```
*/
getUsedThemeStyle(): string | undefined {
diff --git a/packages/sheets/src/facade/f-selection.ts b/packages/sheets/src/facade/f-selection.ts
index f4328599de..09d7fd26fe 100644
--- a/packages/sheets/src/facade/f-selection.ts
+++ b/packages/sheets/src/facade/f-selection.ts
@@ -53,9 +53,10 @@ export class FSelection {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A10:B11');
+ * fRange.activate();
* const fSelection = fWorksheet.getSelection();
- * const activeRange = fSelection.getActiveRange();
- * console.log(activeRange);
+ * console.log(fSelection.getActiveRange().getA1Notation()); // A10:B11
* ```
*/
getActiveRange(): FRange | null {
@@ -76,7 +77,9 @@ export class FSelection {
* const fWorksheet = fWorkbook.getActiveSheet();
* const fSelection = fWorksheet.getSelection();
* const activeRangeList = fSelection.getActiveRangeList();
- * console.log(activeRangeList);
+ * activeRangeList.forEach((range) => {
+ * console.log(range.getA1Notation());
+ * });
* ```
*/
getActiveRangeList(): FRange[] {
@@ -92,9 +95,13 @@ export class FSelection {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
+ * const fRange = fWorksheet.getRange('A10:B11');
+ * fRange.activate();
* const fSelection = fWorksheet.getSelection();
* const currentCell = fSelection.getCurrentCell();
+ * const { actualRow, actualColumn } = currentCell;
* console.log(currentCell);
+ * console.log(`actualRow: ${actualRow}, actualColumn: ${actualColumn}`); // actualRow: 9, actualColumn: 0
* ```
*/
getCurrentCell(): Nullable<ISelectionCell> {
@@ -131,10 +138,18 @@ export class FSelection {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
- * const fSelection = fWorksheet.getSelection();
- * const cell = fWorksheet.getCell('A1');
- * const newSelection = fSelection.updatePrimaryCell(cell);
- * console.log(newSelection.getActiveRange().getA1Notation()); // A1
+ * const fRange = fWorksheet.getRange('A10:B11');
+ * fRange.activate();
+ * const cell = fWorksheet.getRange('B11');
+ *
+ * let fSelection = fWorksheet.getSelection();
+ * fSelection.updatePrimaryCell(cell);
+ * fSelection = fWorksheet.getSelection();
+ *
+ * const currentCell = fSelection.getCurrentCell();
+ * const { actualRow, actualColumn } = currentCell;
+ * console.log(currentCell);
+ * console.log(`actualRow: ${actualRow}, actualColumn: ${actualColumn}`); // actualRow: 10, actualColumn: 1
* ```
*/
updatePrimaryCell(cell: FRange): FSelection {
@@ -178,18 +193,28 @@ export class FSelection {
}
/**
- *Get the next primary cell in the specified direction. If the primary cell not exists in selections, return null.
+ * Get the next primary cell in the specified direction. If the primary cell not exists in selections, return null.
+ * The next primary cell in the specified direction is the next cell only within the current selection range.
+ * For example, if the current selection is A1:B2, and the primary cell is B1, the next cell in the right direction is A2 instead of C1.
* @param {Direction} direction The direction to move the primary cell.The enum value is maybe one of the following: UP(0),RIGHT(1), DOWN(2), LEFT(3).
* @returns {FRange | null} The next primary cell in the specified direction.
* @example
* ```ts
- * // import { Direction } from '@univerjs/core';
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
- * // make sure the active cell is A1 and selection is A1:C3
- * const fSelection = fWorksheet.getSelection();
- * const nextCell = fSelection.getNextDataRange(Direction.RIGHT);
+ * // make sure the active cell is A1 and selection is A1:B2
+ * const fRange = fWorksheet.getRange('A1:B2');
+ * fRange.activate();
+ *
+ * // get the next cell in the right direction, and update the primary cell to the next cell, now the active cell is B1
+ * let fSelection = fWorksheet.getSelection();
+ * const nextCell = fSelection.getNextDataRange(univerAPI.Enum.Direction.RIGHT);
* console.log(nextCell?.getA1Notation()); // B1
+ * fSelection = fSelection.updatePrimaryCell(nextCell);
+ *
+ * // get the next cell in the right direction, the next cell is A2
+ * const nextCell2 = fSelection.getNextDataRange(univerAPI.Enum.Direction.RIGHT);
+ * console.log(nextCell2?.getA1Notation()); // A2
* ```
*/
getNextDataRange(direction: Direction): FRange | null {
diff --git a/packages/sheets/src/facade/f-univer.ts b/packages/sheets/src/facade/f-univer.ts
index c7bb2362ed..c86f3410c0 100644
--- a/packages/sheets/src/facade/f-univer.ts
+++ b/packages/sheets/src/facade/f-univer.ts
@@ -21,7 +21,7 @@ import type { FRange } from './f-range';
import type { FWorksheet } from './f-worksheet';
import { CanceledError, ICommandService, IUniverInstanceService, toDisposable, UniverInstanceType } from '@univerjs/core';
import { FUniver } from '@univerjs/core/facade';
-import { COMMAND_LISTENER_VALUE_CHANGE, getValueChangedEffectedRange, InsertSheetCommand, RemoveSheetCommand, SetGridlinesColorCommand, SetTabColorCommand, SetWorksheetActiveOperation, SetWorksheetHideCommand, SetWorksheetNameCommand, SetWorksheetOrderCommand, ToggleGridlinesCommand } from '@univerjs/sheets';
+import { COMMAND_LISTENER_VALUE_CHANGE, getValueChangedEffectedRange, InsertSheetCommand, RemoveSheetCommand, SetGridlinesColorCommand, SetTabColorMutation, SetWorksheetActiveOperation, SetWorksheetHideMutation, SetWorksheetNameCommand, SetWorksheetOrderMutation, ToggleGridlinesCommand } from '@univerjs/sheets';
import { FDefinedNameBuilder } from './f-defined-name';
import { FPermission } from './f-permission';
import { FWorkbook } from './f-workbook';
@@ -42,12 +42,14 @@ export interface IFUniverSheetsMixin {
* @returns {FWorkbook} FWorkbook API instance.
* @example
* ```ts
- * univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' });
+ * const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' });
+ * console.log(fWorkbook);
* ```
*
* Add you can make the workbook not as the active workbook by setting options:
* ```ts
- * univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' }, { makeCurrent: false });
+ * const fWorkbook = univerAPI.createWorkbook({ id: 'Sheet1', name: 'Sheet1' }, { makeCurrent: false });
+ * console.log(fWorkbook);
* ```
*/
createWorkbook(data: Partial<IWorkbookData>, options?: ICreateUnitOptions): FWorkbook;
@@ -57,7 +59,8 @@ export interface IFUniverSheetsMixin {
* @returns {FWorkbook | null} The currently focused Univer spreadsheet.
* @example
* ```ts
- * univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * console.log(fWorkbook);
* ```
*/
getActiveWorkbook(): FWorkbook | null;
@@ -71,10 +74,20 @@ export interface IFUniverSheetsMixin {
* Get the spreadsheet API handler by the spreadsheet id.
* @param {string} id The spreadsheet id.
* @returns {FWorkbook | null} The spreadsheet API instance.
+ *
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getUniverSheet('Sheet1');
+ * console.log(fWorkbook);
+ *
+ * const fWorkbook = univerAPI.getWorkbook('Sheet1');
+ * console.log(fWorkbook);
+ * ```
*/
getUniverSheet(id: string): FWorkbook | null;
getWorkbook(id: string): FWorkbook | null;
+
/**
* Get the PermissionInstance.
* @deprecated This function is deprecated and will be removed in version 0.6.0. Please use the function with the same name on the `FWorkbook` instance instead.
@@ -91,7 +104,13 @@ export interface IFUniverSheetsMixin {
* @returns {FDefinedNameBuilder} - The defined name builder.
* @example
* ```ts
- * univerAPI.newDefinedName();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedNameBuilder = univerAPI.newDefinedName()
+ * .setRef('Sheet1!$A$1')
+ * .setName('MyDefinedName')
+ * .setComment('This is a comment');
+ * console.log(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder.build());
* ```
*/
newDefinedName(): FDefinedNameBuilder;
@@ -103,7 +122,12 @@ export interface IFUniverSheetsMixin {
* @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} - The target of the sheet.
* @example
* ```ts
- * univerAPI.getSheetTarget('unitId', 'subUnitId');
+ * const unitId = 'workbook-01';
+ * const subUnitId = 'sheet-0001';
+ * const target = univerAPI.getSheetTarget(unitId, subUnitId);
+ * if (!target) return;
+ * const { workbook, worksheet } = target;
+ * console.log(workbook, worksheet);
* ```
*/
getSheetTarget(unitId: string, subUnitId: string): Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>;
@@ -114,10 +138,11 @@ export interface IFUniverSheetsMixin {
* @returns {Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>} - The target of the sheet.
* @example
* ```ts
- * univerAPI.addEvent(univerAPI.event.CommandExecuted, (commandInfo) => {
+ * univerAPI.addEvent(univerAPI.Event.CommandExecuted, (commandInfo) => {
* const target = univerAPI.getCommandSheetTarget(commandInfo);
* if (!target) return;
* const { workbook, worksheet } = target;
+ * console.log(workbook, worksheet);
* });
* ```
*/
@@ -131,6 +156,7 @@ export interface IFUniverSheetsMixin {
* const target = univerAPI.getActiveSheet();
* if (!target) return;
* const { workbook, worksheet } = target;
+ * console.log(workbook, worksheet);
* ```
*/
getActiveSheet(): Nullable<{ workbook: FWorkbook; worksheet: FWorksheet }>;
@@ -270,7 +296,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
this.registerEventHandler(
this.Event.BeforeSheetMove,
() => commandService.beforeCommandExecuted((commandInfo) => {
- if (commandInfo.id === SetWorksheetOrderCommand.id) {
+ if (commandInfo.id === SetWorksheetOrderMutation.id) {
const { fromOrder, toOrder } = commandInfo.params as ISetWorksheetOrderMutationParams;
const target = this.getCommandSheetTarget(commandInfo);
if (!target) return;
@@ -294,7 +320,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
this.registerEventHandler(
this.Event.BeforeSheetTabColorChange,
() => commandService.beforeCommandExecuted((commandInfo) => {
- if (commandInfo.id === SetTabColorCommand.id) {
+ if (commandInfo.id === SetTabColorMutation.id) {
const { color } = commandInfo.params as ISetTabColorMutationParams;
const target = this.getCommandSheetTarget(commandInfo);
if (!target) return;
@@ -306,7 +332,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
this.registerEventHandler(
this.Event.BeforeSheetHideChange,
() => commandService.beforeCommandExecuted((commandInfo) => {
- if (commandInfo.id === SetWorksheetHideCommand.id) {
+ if (commandInfo.id === SetWorksheetHideMutation.id) {
const { hidden } = commandInfo.params as ISetWorksheetHideMutationParams;
const target = this.getCommandSheetTarget(commandInfo);
if (!target) return;
@@ -418,7 +444,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
this.registerEventHandler(
this.Event.SheetMoved,
() => commandService.onCommandExecuted((commandInfo) => {
- if (commandInfo.id === SetWorksheetOrderCommand.id) {
+ if (commandInfo.id === SetWorksheetOrderMutation.id) {
const { toOrder: toIndex } = commandInfo.params as ISetWorksheetOrderMutationParams;
const target = this.getCommandSheetTarget(commandInfo);
if (!target) return;
@@ -442,7 +468,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
this.registerEventHandler(
this.Event.SheetTabColorChanged,
() => commandService.onCommandExecuted((commandInfo) => {
- if (commandInfo.id === SetTabColorCommand.id) {
+ if (commandInfo.id === SetTabColorMutation.id) {
const { color } = commandInfo.params as ISetTabColorMutationParams;
const target = this.getCommandSheetTarget(commandInfo);
if (!target) return;
@@ -454,7 +480,7 @@ export class FUniverSheetsMixin extends FUniver implements IFUniverSheetsMixin {
this.registerEventHandler(
this.Event.SheetHideChanged,
() => commandService.onCommandExecuted((commandInfo) => {
- if (commandInfo.id === SetWorksheetHideCommand.id) {
+ if (commandInfo.id === SetWorksheetHideMutation.id) {
const { hidden } = commandInfo.params as ISetWorksheetHideMutationParams;
const target = this.getCommandSheetTarget(commandInfo);
if (!target) return;
diff --git a/packages/sheets/src/facade/f-workbook.ts b/packages/sheets/src/facade/f-workbook.ts
index 7dfabd6c17..8085278781 100644
--- a/packages/sheets/src/facade/f-workbook.ts
+++ b/packages/sheets/src/facade/f-workbook.ts
@@ -57,8 +57,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the Workbook instance
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const workbook = activeSpreadsheet.getWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const workbook = fWorkbook.getWorkbook();
+ * console.log(workbook);
* ```
*/
getWorkbook(): Workbook {
@@ -71,8 +72,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the id of the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const id = activeSpreadsheet.getId();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const unitId = fWorkbook.getId();
+ * console.log(unitId);
* ```
*/
getId(): string {
@@ -85,8 +87,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the name of the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const name = activeSpreadsheet.getName();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const name = fWorkbook.getName();
+ * console.log(name);
* ```
*/
getName(): string {
@@ -96,12 +99,11 @@ export class FWorkbook extends FBaseInitialable {
/**
* Set the name of the workbook.
* @param {string} name The new name of the workbook.
- * @returns {void}
* @example
* ```ts
* // The code below sets the name of the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.setName('MyWorkbook');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.setName('MyWorkbook');
* ```
*/
setName(name: string): void {
@@ -114,8 +116,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below saves the workbook snapshot data
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const snapshot = activeSpreadsheet.save();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const snapshot = fWorkbook.save();
+ * console.log(snapshot);
* ```
*/
save(): IWorkbookData {
@@ -145,8 +148,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the active sheet of the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const activeSheet = activeSpreadsheet.getActiveSheet();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getActiveSheet();
+ * console.log(fWorksheet);
* ```
*/
getActiveSheet(): FWorksheet {
@@ -160,8 +164,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets all the worksheets in the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheets = activeSpreadsheet.getSheets();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheets = fWorkbook.getSheets();
+ * console.log(sheets);
* ```
*/
getSheets(): FWorksheet[] {
@@ -179,8 +184,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below creates a new sheet
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const newSheet = activeSpreadsheet.create('MyNewSheet', 10, 10);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const newSheet = fWorkbook.create('MyNewSheet', 10, 10);
+ * console.log(newSheet);
* ```
*/
create(name: string, rows: number, column: number): FWorksheet {
@@ -216,8 +222,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets a worksheet by sheet id
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheet = activeSpreadsheet.getSheetBySheetId('sheetId');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheet = fWorkbook.getSheetBySheetId('sheetId');
+ * console.log(sheet);
* ```
*/
getSheetBySheetId(sheetId: string): FWorksheet | null {
@@ -236,8 +243,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets a worksheet by sheet name
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheet = fWorkbook.getSheetByName('Sheet1');
+ * console.log(sheet);
* ```
*/
getSheetByName(name: string): FWorksheet | null {
@@ -256,9 +264,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below sets the given worksheet to be the active worksheet
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
- * activeSpreadsheet.setActiveSheet(sheet);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheet = fWorkbook.getSheets()[1];
+ * fWorkbook.setActiveSheet(sheet);
* ```
*/
setActiveSheet(sheet: FWorksheet | string): FWorksheet {
@@ -278,12 +286,12 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below inserts a new sheet into the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.insertSheet();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.insertSheet();
*
* // The code below inserts a new sheet into the workbook, using a custom name
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.insertSheet('MyNewSheet');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.insertSheet('MyNewSheet');
* ```
*/
insertSheet(sheetName?: string): FWorksheet {
@@ -315,9 +323,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below deletes the specified worksheet
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheet = activeSpreadsheet.getSheetByName('Sheet1');
- * activeSpreadsheet.deleteSheet(sheet);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheet = fWorkbook.getSheets()[1];
+ * fWorkbook.deleteSheet(sheet);
* ```
*/
deleteSheet(sheet: FWorksheet | string): boolean {
@@ -336,8 +344,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below undoes the last action
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.undo();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.undo();
* ```
*/
undo(): FWorkbook {
@@ -352,8 +360,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below redoes the last undone action
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.redo();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.redo();
* ```
*/
redo(): FWorkbook {
@@ -375,9 +383,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below registers a callback that will be triggered before invoking a command targeting the Univer sheet
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.onBeforeCommandExecute((command) => {
- * console.log('Command executed:', command);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.onBeforeCommandExecute((command) => {
+ * console.log('Before command execute:', command);
* });
* ```
*/
@@ -404,8 +412,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below registers a callback that will be triggered when a command is invoked targeting the Univer sheet
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.onCommandExecuted((command) => {
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.onCommandExecuted((command) => {
* console.log('Command executed:', command);
* });
* ```
@@ -430,6 +438,14 @@ export class FWorkbook extends FBaseInitialable {
* Register a callback that will be triggered when the selection changes.
* @param {onSelectionChangeCallback} callback The callback.
* @returns {IDisposable} A function to dispose the listening
+ * @example
+ * ```ts
+ * // The code below registers a callback that will be triggered when the selection changes
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.onSelectionChange((selections) => {
+ * console.log('Selection changed:', selections);
+ * });
+ * ```
*/
onSelectionChange(callback: (selections: IRange[]) => void): IDisposable {
return toDisposable(
@@ -452,6 +468,12 @@ export class FWorkbook extends FBaseInitialable {
* Used to modify the editing permissions of the workbook. When the value is false, editing is not allowed.
* @param {boolean} value editable value want to set
* @returns {FWorkbook} FWorkbook instance
+ * @example
+ * ```ts
+ * // The code below sets the editing permissions of the workbook
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.setEditable(false);
+ * ```
*/
setEditable(value: boolean): FWorkbook {
const instance = new WorkbookEditablePermission(this._workbook.getUnitId());
@@ -468,6 +490,12 @@ export class FWorkbook extends FBaseInitialable {
* Sets the selection region for active sheet.
* @param {FRange} range The range to set as the active selection.
* @returns {FWorkbook} FWorkbook instance
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const range = fWorkbook.getActiveSheet().getRange('A10:B10');
+ * fWorkbook.setActiveRange(range);
+ * ```
*/
setActiveRange(range: FRange): FWorkbook {
// In theory, FRange should belong to a specific context, rather than getting the currently active sheet
@@ -499,6 +527,12 @@ export class FWorkbook extends FBaseInitialable {
/**
* Returns the selected range in the active sheet, or null if there is no active range.
* @returns {FRange | null} The active range
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const activeRange = fWorkbook.getActiveRange();
+ * console.log(activeRange);
+ * ```
*/
// could sheet have no active range ?
getActiveRange(): FRange | null {
@@ -517,9 +551,8 @@ export class FWorkbook extends FBaseInitialable {
* @returns {boolean} true if the sheet was deleted, false otherwise
* @example
* ```ts
- * // The code below deletes the currently active sheet and stores the new active
- * // sheet in a variable
- * const sheet = univerAPI.getActiveWorkbook().deleteActiveSheet();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.deleteActiveSheet();
* ```
*/
deleteActiveSheet(): boolean {
@@ -534,9 +567,10 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below duplicates the given worksheet
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const activeSheet = activeSpreadsheet.getActiveSheet();
- * activeSpreadsheet.duplicateSheet(activeSheet);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const activeSheet = fWorkbook.getActiveSheet();
+ * const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet);
+ * console.log(duplicatedSheet);
* ```
*/
duplicateSheet(sheet: FWorksheet): FWorksheet {
@@ -553,8 +587,9 @@ export class FWorkbook extends FBaseInitialable {
* @returns {FWorksheet} The duplicated worksheet
* @example
* ```ts
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.duplicateActiveSheet();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const duplicatedSheet = fWorkbook.duplicateActiveSheet();
+ * console.log(duplicatedSheet);
* ```
*/
duplicateActiveSheet(): FWorksheet {
@@ -568,8 +603,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the number of sheets in the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const numSheets = activeSpreadsheet.getNumSheets();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * console.log(fWorkbook.getNumSheets());
* ```
*/
getNumSheets(): number {
@@ -582,8 +617,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the locale of the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const locale = activeSpreadsheet.getLocale();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * console.log(fWorkbook.getLocale());
* ```
*/
getLocale(): LocaleType {
@@ -591,7 +626,7 @@ export class FWorkbook extends FBaseInitialable {
}
/**
- * @deprecated use setSpreadsheetLocale instead.
+ * @deprecated use `setSpreadsheetLocale` instead.
* @param {LocaleType} locale - The locale to set
*/
setLocale(locale: LocaleType): void {
@@ -605,8 +640,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below sets the locale of the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.setLocale(LocaleType.EN_US);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.setSpreadsheetLocale(univerAPI.Enum.LocaleType.EN_US);
+ * console.log(fWorkbook.getLocale());
* ```
*/
setSpreadsheetLocale(locale: LocaleType): FWorkbook {
@@ -620,8 +656,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the URL of the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const url = activeSpreadsheet.getUrl();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const url = fWorkbook.getUrl();
+ * console.log(url);
* ```
*/
getUrl(): string {
@@ -636,9 +673,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below moves the sheet to the specified index
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheet = activeSpreadsheet.getActiveSheet();
- * activeSpreadsheet.moveSheet(sheet, 1);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheet = fWorkbook.getActiveSheet();
+ * fWorkbook.moveSheet(sheet, 1);
* ```
*/
moveSheet(sheet: FWorksheet, index: number): FWorkbook {
@@ -663,8 +700,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below moves the active sheet to the specified index
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.moveActiveSheet(1);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.moveActiveSheet(1);
* ```
*/
moveActiveSheet(index: number): FWorkbook {
@@ -675,6 +712,12 @@ export class FWorkbook extends FBaseInitialable {
/**
* Get the PermissionInstance.
* @returns {FPermission} - The PermissionInstance.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const permission = fWorkbook.getPermission();
+ * console.log(permission);
+ * ```
*/
getPermission(): FPermission {
return this._injector.createInstance(FPermission);
@@ -687,8 +730,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the defined name by name
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const definedName = activeSpreadsheet.getDefinedName('MyDefinedName');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedName('MyDefinedName');
+ * console.log(definedName);
* ```
*/
getDefinedName(name: string): FDefinedName | null {
@@ -706,8 +750,9 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets all the defined names in the workbook
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const definedNames = activeSpreadsheet.getDefinedNames();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedNames = fWorkbook.getDefinedNames();
+ * console.log(definedNames);
* ```
*/
getDefinedNames(): FDefinedName[] {
@@ -728,8 +773,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below inserts a defined name
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * activeSpreadsheet.insertDefinedName('MyDefinedName', 'Sheet1!A1');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!A1');
* ```
*/
insertDefinedName(name: string, formulaOrRefString: string): FWorkbook {
@@ -747,8 +792,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below deletes the defined name with the given name
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const deleted = activeSpreadsheet.deleteDefinedName('MyDefinedName');
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * fWorkbook.deleteDefinedName('MyDefinedName');
* ```
*/
deleteDefinedName(name: string): boolean {
@@ -768,10 +813,13 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below inserts a defined name by builder param
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const builder = univerAPI.newDefinedName();
- * const param = builder.setName('MyDefinedName').setRef('Sheet1!A1').build();
- * activeSpreadsheet.insertDefinedNameBuilder(param);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedNameBuilder = univerAPI.newDefinedName()
+ * .setRef('Sheet1!$A$1')
+ * .setName('MyDefinedName')
+ * .setComment('This is a comment')
+ * .build();
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
insertDefinedNameBuilder(param: ISetDefinedNameMutationParam): void {
@@ -786,10 +834,12 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below updates the defined name with the given name
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const builder = activeSpreadsheet.getDefinedName('MyDefinedName').toBuilder();
- * builder.setRef('Sheet1!A2').setName('MyDefinedName1').build();
- * activeSpreadsheet.updateDefinedNameBuilder(param);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedNameBuilder = fWorkbook.getDefinedName('MyDefinedName').toBuilder();
+ * const param = definedNameBuilder.setRef('Sheet1!A2')
+ * .setName('NewDefinedName')
+ * .build();
+ * fWorkbook.updateDefinedNameBuilder(param);
* ```
*/
updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): void {
@@ -802,8 +852,8 @@ export class FWorkbook extends FBaseInitialable {
* @example
* ```ts
* // The code below gets the registered range themes
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const themes = activeSpreadsheet.getRegisteredRangeThemes();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const themes = fWorkbook.getRegisteredRangeThemes();
* console.log(themes);
* ```
*/
@@ -819,10 +869,11 @@ export class FWorkbook extends FBaseInitialable {
* ```ts
* // import {RangeThemeStyle} from '@univerjs/sheets';
* const fWorkbook = univerAPI.getActiveWorkbook();
- * const rangeThemeStyle = new RangeThemeStyle('MyTheme');
- * rangeThemeStyle.setSecondRowStyle({
- * bg: {
- * rgb: 'rgb(214,231,241)',
+ * const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
+ * secondRowStyle: {
+ * bg: {
+ * rgb: 'rgb(214,231,241)',
+ * },
* },
* });
* fWorkbook.registerRangeTheme(rangeThemeStyle);
@@ -852,6 +903,24 @@ export class FWorkbook extends FBaseInitialable {
});
}
+ /**
+ * Create a range theme style.
+ * @param {string} themeName - The name of the theme to register
+ * @param {Omit<IRangeThemeStyleJSON, 'name'>} themeStyleJson - The theme style json to register
+ * @returns {RangeThemeStyle} - The created range theme style
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
+ * secondRowStyle: {
+ * bg: {
+ * rgb: 'rgb(214,231,241)',
+ * },
+ * },
+ * });
+ * console.log(rangeThemeStyle);
+ * ```
+ */
createRangeThemeStyle(themeName: string, themeStyleJson?: Omit<IRangeThemeStyleJSON, 'name'>): RangeThemeStyle {
return new RangeThemeStyle(themeName, themeStyleJson);
}
@@ -878,6 +947,7 @@ export class FWorkbook extends FBaseInitialable {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const custom = fWorkbook.getCustomMetadata();
+ * console.log(custom);
* ```
*/
getCustomMetadata(): CustomData | undefined {
diff --git a/packages/sheets/src/facade/f-worksheet.ts b/packages/sheets/src/facade/f-worksheet.ts
index 87beda6130..28a496d698 100644
--- a/packages/sheets/src/facade/f-worksheet.ts
+++ b/packages/sheets/src/facade/f-worksheet.ts
@@ -60,11 +60,13 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the worksheet
+ * Get the worksheet instance.
* @returns {Worksheet} The worksheet instance.
* @example
* ```typescript
- * const sheet = univerAPI.getActiveWorkbook().getActiveSheet().getSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const sheet = fWorksheet.getSheet();
+ * console.log(sheet);
* ```
*/
getSheet(): Worksheet {
@@ -72,11 +74,13 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the injector
- * @returns {Injector} The injector
+ * Get the injector instance.
+ * @returns {Injector} The injector instance.
* @example
* ```typescript
- * const injector = univerAPI.getActiveWorkbook().getActiveSheet().getInject();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const injector = fWorksheet.getInject();
+ * console.log(injector);
* ```
*/
getInject(): Injector {
@@ -84,11 +88,13 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the workbook
+ * Get the workbook instance.
* @returns {Workbook} The workbook instance.
* @example
* ```typescript
- * const workbook = univerAPI.getActiveWorkbook().getWorkbook();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const workbook = fWorksheet.getWorkbook();
+ * console.log(workbook);
* ```
*/
getWorkbook(): Workbook {
@@ -96,12 +102,13 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the worksheet id.
+ * Get the worksheet id.
* @returns {string} The id of the worksheet.
* @example
* ```typescript
- * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
- * const id = sheet.getSheetId();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const sheetId = fWorksheet.getSheetId();
+ * console.log(sheetId);
* ```
*/
getSheetId(): string {
@@ -109,12 +116,13 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the worksheet name.
+ * Get the worksheet name.
* @returns {string} The name of the worksheet.
* @example
* ```typescript
- * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
- * const name = sheet.getSheetName();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const sheetName = fWorksheet.getSheetName();
+ * console.log(sheetName);
* ```
*/
getSheetName(): string {
@@ -122,12 +130,13 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Represents the selection ranges info of the worksheet.
+ * Get the current selection of the worksheet.
* @returns {FSelection} return the current selections of the worksheet or null if there is no selection.
* @example
* ```typescript
- * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
- * const selections = sheet.getSelection();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const selection = fWorksheet.getSelection();
+ * console.log(selection);
* ```
*/
getSelection(): FSelection | null {
@@ -144,12 +153,13 @@ export class FWorksheet extends FBaseInitialable {
// #region default style
/**
- * Get the default style of the worksheet
+ * Get the default style of the worksheet.
* @returns {IStyleData} Default style of the worksheet.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * const defaultStyle = sheet.getDefaultStyle();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const defaultStyle = fWorksheet.getDefaultStyle();
+ * console.log(defaultStyle);
* ```
*/
getDefaultStyle(): Nullable<IStyleData> | string {
@@ -163,11 +173,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {(Nullable<IStyleData> | string)} The default style of the worksheet row name or style data
* @example
* ```typescript
- * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get default style for row 0 (1)
- * const rowStyle = sheet.getRowDefaultStyle(0);
+ * const rowStyle = fWorksheet.getRowDefaultStyle(0);
+ * console.log(rowStyle);
* // Get raw style data for row 0
- * const rawRowStyle = sheet.getRowDefaultStyle(0, true);
+ * const rawRowStyle = fWorksheet.getRowDefaultStyle(0, true);
+ * console.log(rawRowStyle);
* ```
*/
getRowDefaultStyle(index: number, keepRaw: boolean = false): Nullable<IStyleData> | string {
@@ -181,11 +193,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {(Nullable<IStyleData> | string)} The default style of the worksheet column name or style data
* @example
* ```typescript
- * const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get default style for column 0 (A)
- * const colStyle = sheet.getColumnDefaultStyle(0);
+ * const colStyle = fWorksheet.getColumnDefaultStyle(0);
+ * console.log(colStyle);
* // Get raw style data for column 0
- * const rawColStyle = sheet.getColumnDefaultStyle(0, true);
+ * const rawColStyle = fWorksheet.getColumnDefaultStyle(0, true);
+ * console.log(rawColStyle);
* ```
*/
getColumnDefaultStyle(index: number, keepRaw: boolean = false): Nullable<IStyleData> | string {
@@ -198,8 +212,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorksheet = fWorkbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorksheet.setDefaultStyle('default');
* // or
* // fWorksheet.setDefaultStyle({fs: 12, ff: 'Arial'});
@@ -226,9 +239,9 @@ export class FWorksheet extends FBaseInitialable {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
- * fWorksheet.setRowDefaultStyle(0, 'default');
+ * fWorksheet.setColumnDefaultStyle(0, 'default');
* // or
- * // fWorksheet.setRowDefaultStyle(0, {fs: 12, ff: 'Arial'});
+ * // fWorksheet.setColumnDefaultStyle(0, {fs: 12, ff: 'Arial'});
* ```
*/
setColumnDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet {
@@ -258,9 +271,9 @@ export class FWorksheet extends FBaseInitialable {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorksheet = fWorkbook.getActiveSheet();
- * fWorksheet.setColumnDefaultStyle(0, 'default');
+ * fWorksheet.setRowDefaultStyle(0, 'default');
* // or
- * // fWorksheet.setColumnDefaultStyle(0, {fs: 12, ff: 'Arial'});
+ * // fWorksheet.setRowDefaultStyle(0, {fs: 12, ff: 'Arial'});
* ```
*/
setRowDefaultStyle(index: number, style: string | Nullable<IStyleData>): FWorksheet {
@@ -290,9 +303,10 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FRange} A Range object representing the specified cell.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get range for cell at row 0, column 0 (A1)
- * const range = sheet.getRange(0, 0);
+ * const range = fWorksheet.getRange(0, 0);
+ * console.log(range);
* ```
*/
getRange(row: number, column: number): FRange;
@@ -311,6 +325,13 @@ export class FWorksheet extends FBaseInitialable {
* @param {number} numRows - The number of rows in the range.
* @param {number} numColumns - The number of columns in the range.
* @returns {FRange} A Range object representing the specified range.
+ * @example
+ * ```typescript
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Get range for cells A1:C3
+ * const range = fWorksheet.getRange(0, 0, 3, 3);
+ * console.log(range);
+ * ```
*/
getRange(row: number, column: number, numRows: number, numColumns: number): FRange;
/**
@@ -319,13 +340,17 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FRange} A Range object representing the specified range.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get range for cells A1:C3
- * const range = sheet.getRange("A1:C3");
+ * const range = fWorksheet.getRange("A1:C3");
+ * console.log(range);
* // Get range for a single cell
- * const cell = sheet.getRange("B2");
+ * const cell = fWorksheet.getRange("B2");
+ * console.log(cell);
* // Get range with sheet name
- * const rangeWithSheet = sheet.getRange("Sheet1!A1:C3");
+ * const sheetName = fWorksheet.getSheetName();
+ * const rangeWithSheet = fWorksheet.getRange(`${sheetName}!A1:C3`);
+ * console.log(rangeWithSheet);
* ```
*/
getRange(a1Notation: string): FRange;
@@ -387,8 +412,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns {number} The maximum columns count of the sheet
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * const totalColumns = sheet.getMaxColumns();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const totalColumns = fWorksheet.getMaxColumns();
* console.log(`Sheet has ${totalColumns} columns`);
* ```
*/
@@ -401,8 +426,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns {number}The maximum rows count of the sheet
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * const totalRows = sheet.getMaxRows();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const totalRows = fWorksheet.getMaxRows();
* console.log(`Sheet has ${totalRows} rows`);
* ```
*/
@@ -416,11 +441,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 rows at row index 2 (before the third row)
- * sheet.insertRowAfter(2);
- * // Insert 1 row at row index 0 (before the first row)
- * sheet.insertRowAfter(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert a row after the third row
+ * fWorksheet.insertRowAfter(2);
+ * // Insert a row after the first row
+ * fWorksheet.insertRowAfter(0);
* ```
*/
insertRowAfter(afterPosition: number): FWorksheet {
@@ -433,11 +458,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 rows at row index 2 (before the third row)
- * sheet.insertRowBefore(2);
- * // Insert 1 row at row index 0 (before the first row)
- * sheet.insertRowBefore(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert a row before the third row
+ * fWorksheet.insertRowBefore(2);
+ * // Insert a row before the first row
+ * fWorksheet.insertRowBefore(0);
* ```
*/
insertRowBefore(beforePosition: number): FWorksheet {
@@ -451,11 +476,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 rows at row index 2 (before the third row)
- * sheet.insertRows(2, 3);
- * // Insert 1 row at row index 0 (before the first row)
- * sheet.insertRows(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert 3 rows before the third row
+ * fWorksheet.insertRows(2, 3);
+ * // Insert 1 row before the first row
+ * fWorksheet.insertRows(0);
* ```
*/
insertRows(rowIndex: number, numRows: number = 1): FWorksheet {
@@ -469,11 +494,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 rows at row index 2 (before the third row)
- * sheet.insertRowsAfter(2, 3);
- * // Insert 1 row at row index 0 (before the first row)
- * sheet.insertRowsAfter(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert 3 rows after the third row
+ * fWorksheet.insertRowsAfter(2, 3);
+ * // Insert 1 row after the first row
+ * fWorksheet.insertRowsAfter(0, 1);
* ```
*/
insertRowsAfter(afterPosition: number, howMany: number): FWorksheet {
@@ -512,11 +537,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 rows at row index 2 (before the third row)
- * sheet.insertRowsBefore(2, 3);
- * // Insert 1 row at row index 0 (before the first row)
- * sheet.insertRowsBefore(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert 3 rows before the third row
+ * fWorksheet.insertRowsBefore(2, 3);
+ * // Insert 1 row before the first row
+ * fWorksheet.insertRowsBefore(0, 1);
* ```
*/
insertRowsBefore(beforePosition: number, howMany: number): FWorksheet {
@@ -554,11 +579,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Delete 3 rows at row index 2 (rows 3-5)
- * sheet.deleteRow(2);
- * // Delete 1 row at row index 0 (first row)
- * sheet.deleteRow(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Delete the third row
+ * fWorksheet.deleteRow(2);
+ * // Delete the first row
+ * fWorksheet.deleteRow(0);
* ```
*/
deleteRow(rowPosition: number): FWorksheet {
@@ -572,11 +597,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete 3 rows at row index 2 (rows 3-5)
- * sheet.deleteRows(2, 3);
+ * fWorksheet.deleteRows(2, 3);
* // Delete 1 row at row index 0 (first row)
- * sheet.deleteRows(0);
+ * fWorksheet.deleteRows(0, 1);
* ```
*/
deleteRows(rowPosition: number, howMany: number): FWorksheet {
@@ -603,11 +628,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Move 3 rows at row index 2 (rows 3-5) to row index 0
- * sheet.moveRows(rowSpec, 0);
+ * const rowSpec1 = fWorksheet.getRange('3:5');
+ * fWorksheet.moveRows(rowSpec1, 0);
* // Move 1 row at row index 0 (first row) to row index 2
- * sheet.moveRows(rowSpec, 2);
+ * const rowSpec2 = fWorksheet.getRange('1:1');
+ * fWorksheet.moveRows(rowSpec2, 2);
* ```
*/
moveRows(rowSpec: FRange, destinationIndex: number): FWorksheet {
@@ -639,11 +666,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide 3 rows starting from row index 1 (rows 2-4)
- * sheet.hideRow(1);
+ * const row1 = fWorksheet.getRange('2:4');
+ * fWorksheet.hideRow(row1);
* // Hide single row at index 0 (first row)
- * sheet.hideRow(0);
+ * const row2 = fWorksheet.getRange('1:1');
+ * fWorksheet.hideRow(row2);
* ```
*/
hideRow(row: FRange): FWorksheet {
@@ -667,11 +696,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide 3 rows starting from row index 1 (rows 2-4)
- * sheet.hideRows(1, 3);
+ * fWorksheet.hideRows(1, 3);
* // Hide single row at index 0 (first row)
- * sheet.hideRows(0);
+ * fWorksheet.hideRows(0);
* ```
*/
hideRows(rowIndex: number, numRow: number = 1): FWorksheet {
@@ -699,11 +728,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining.
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Unhide 3 rows starting from row index 1 (rows 2-4)
- * sheet.unhideRow(1);
+ * const row1 = fWorksheet.getRange('2:4');
+ * fWorksheet.unhideRow(row1);
* // Unhide single row at index 0 (first row)
- * sheet.unhideRow(0);
+ * const row2 = fWorksheet.getRange('1:1');
+ * fWorksheet.unhideRow(row2);
* ```
*/
unhideRow(row: FRange): FWorksheet {
@@ -727,11 +758,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Show 3 rows starting from row index 1 (rows 2-4)
- * sheet.showRows(1);
+ * fWorksheet.showRows(1, 3);
* // Show single row at index 0 (first row)
- * sheet.showRows(0);
+ * fWorksheet.showRows(0);
* ```
*/
showRows(rowIndex: number, numRow: number = 1): FWorksheet {
@@ -761,11 +792,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Set the height of the second row to 30 pixels
- * sheet.setRowHeight(1, 30);
+ * fWorksheet.setRowHeight(1, 30);
* // Set the height of the first row to 20 pixels
- * sheet.setRowHeight(0, 20);
+ * fWorksheet.setRowHeight(0, 20);
* ```
*/
setRowHeight(rowPosition: number, height: number): FWorksheet {
@@ -774,14 +805,13 @@ export class FWorksheet extends FBaseInitialable {
/**
* Make certain row wrap and auto height.
- * @param rowPosition
- * @param auto
- * @returns {FWorksheet} this
+ * @param {number} rowPosition - The row position to change.
+ * @param {BooleanNumber} auto - Whether to auto fit the row height.
+ * @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```ts
- const fWorkbook = univerAPI.getActiveWorkbook();
- const fWorkSheet = fWorkbook.getActiveSheet();
- fWorkSheet.autoFitRow(24);
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorkSheet.autoFitRow(24);
* ```
*/
autoFitRow(rowPosition: number, auto: BooleanNumber = BooleanNumber.TRUE): FWorksheet {
@@ -818,8 +848,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * sheet.setRowHeights(1, 10, 30);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorksheet.setRowHeights(1, 10, 30);
* ```
*/
setRowHeights(startRow: number, numRows: number, height: number): FWorksheet {
@@ -874,8 +904,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * sheet.setRowAutoHeight(1, 10);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorksheet.setRowAutoHeight(1, 10);
* ```
*/
setRowAutoHeight(startRow: number, numRows: number): FWorksheet {
@@ -907,8 +937,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * sheet.setRowHeightsForced(1, 10, 30);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorksheet.setRowHeightsForced(1, 10, 30);
* ```
*/
setRowHeightsForced(startRow: number, numRows: number, height: number): FWorksheet {
@@ -941,9 +971,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
- * fWorkSheet.setRowCustom({ key: 'value' });
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorkSheet.setRowCustom({ 0: { key: 'value' } });
* ```
*/
setRowCustom(custom: IObjectArrayPrimitiveType<CustomData>): FWorksheet {
@@ -976,11 +1005,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 columns at column index 2 (before column C)
- * sheet.insertColumnAfter(2);
- * // Insert 1 column at column index 0 (before column A)
- * sheet.insertColumnAfter(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert a column after column C
+ * fWorksheet.insertColumnAfter(2);
+ * // Insert a column after column A
+ * fWorksheet.insertColumnAfter(0);
* ```
*/
insertColumnAfter(afterPosition: number): FWorksheet {
@@ -993,11 +1022,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 columns at column index 2 (before column C)
- * sheet.insertColumnBefore(2);
- * // Insert 1 column at column index 0 (before column A)
- * sheet.insertColumnBefore(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert a column before column C
+ * fWorksheet.insertColumnBefore(2);
+ * // Insert a column before column A
+ * fWorksheet.insertColumnBefore(0);
* ```
*/
insertColumnBefore(beforePosition: number): FWorksheet {
@@ -1011,11 +1040,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 columns at column index 2 (before column C)
- * sheet.insertColumns(2, 3);
- * // Insert 1 column at column index 0 (before column A)
- * sheet.insertColumns(0);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert 3 columns before column C
+ * fWorksheet.insertColumns(2, 3);
+ * // Insert 1 column before column A
+ * fWorksheet.insertColumns(0);
* ```
*/
insertColumns(columnIndex: number, numColumns: number = 1): FWorksheet {
@@ -1029,11 +1058,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 columns at column index 2 (before column C)
- * sheet.insertColumnsAfter(2, 3);
- * // Insert 1 column at column index 0 (before column A)
- * sheet.insertColumnsAfter(0, 1);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert 3 columns after column C
+ * fWorksheet.insertColumnsAfter(2, 3);
+ * // Insert 1 column after column A
+ * fWorksheet.insertColumnsAfter(0, 1);
* ```
*/
insertColumnsAfter(afterPosition: number, howMany: number): FWorksheet {
@@ -1072,11 +1101,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
- * // Insert 3 columns at column index 2 (before column C)
- * sheet.insertColumnsBefore(2, 3);
- * // Insert 1 column at column index 0 (before column A)
- * sheet.insertColumnsBefore(0, 1);
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Insert 3 columns before column C
+ * fWorksheet.insertColumnsBefore(2, 3);
+ * // Insert 1 column before column A
+ * fWorksheet.insertColumnsBefore(0, 1);
* ```
*/
insertColumnsBefore(beforePosition: number, howMany: number): FWorksheet {
@@ -1114,11 +1143,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete column C
- * sheet.deleteColumn(2);
+ * fWorksheet.deleteColumn(2);
* // Delete column A
- * sheet.deleteColumn(0);
+ * fWorksheet.deleteColumn(0);
* ```
*/
deleteColumn(columnPosition: number): FWorksheet {
@@ -1132,11 +1161,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Delete 3 columns at column index 2 (columns C, D, E)
- * sheet.deleteColumns(2, 3);
+ * fWorksheet.deleteColumns(2, 3);
* // Delete 1 column at column index 0 (column A)
- * sheet.deleteColumns(0, 1);
+ * fWorksheet.deleteColumns(0, 1);
* ```
*/
deleteColumns(columnPosition: number, howMany: number): FWorksheet {
@@ -1163,11 +1192,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Move columns C, D, E to column index 2 (columns B, C, D)
- * sheet.moveColumns({ startColumn: 2, endColumn: 4 }, 1);
- * // Move column A to column index 0 (column A)
- * sheet.moveColumns({ startColumn: 0, endColumn: 0 }, 0);
+ * const columnSpec1 = fWorksheet.getRange('C:E');
+ * fWorksheet.moveColumns(columnSpec1, 1);
+ * // Move column F to column index 0 (column A)
+ * const columnSpec2 = fWorksheet.getRange('F:F');
+ * fWorksheet.moveColumns(columnSpec2, 0);
* ```
*/
moveColumns(columnSpec: FRange, destinationIndex: number): FWorksheet {
@@ -1199,11 +1230,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide columns C, D, E
- * sheet.hideColumn({ startColumn: 2, endColumn: 4 });
+ * const column1 = fWorksheet.getRange('C:E');
+ * fWorksheet.hideColumn(column1);
* // Hide column A
- * sheet.hideColumn({ startColumn: 0, endColumn: 0 });
+ * const column2 = fWorksheet.getRange('A:A');
+ * fWorksheet.hideColumn(column2);
* ```
*/
hideColumn(column: FRange): FWorksheet {
@@ -1227,11 +1260,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Hide columns C, D, E
- * sheet.hideColumns(2, 3);
+ * fWorksheet.hideColumns(2, 3);
* // Hide column A
- * sheet.hideColumns(0, 1);
+ * fWorksheet.hideColumns(0, 1);
* ```
*/
hideColumns(columnIndex: number, numColumn: number = 1): FWorksheet {
@@ -1260,11 +1293,13 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Unhide columns C, D, E
- * sheet.unhideColumn({ startColumn: 2, endColumn: 4 });
+ * const column1 = fWorksheet.getRange('C:E');
+ * fWorksheet.unhideColumn(column1);
* // Unhide column A
- * sheet.unhideColumn({ startColumn: 0, endColumn: 0 });
+ * const column2 = fWorksheet.getRange('A:A');
+ * fWorksheet.unhideColumn(column2);
* ```
*/
unhideColumn(column: FRange): FWorksheet {
@@ -1288,11 +1323,11 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Unhide columns C, D, E
- * sheet.unhideColumns(2, 3);
+ * fWorksheet.showColumns(2, 3);
* // Unhide column A
- * sheet.unhideColumns(0, 1);
+ * fWorksheet.showColumns(0, 1);
* ```
*/
showColumns(columnIndex: number, numColumn: number = 1): FWorksheet {
@@ -1322,9 +1357,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Set width of column B to 100 pixels
- * sheet.setColumnWidth(1, 100);
+ * fWorksheet.setColumnWidth(1, 100);
* ```
*/
setColumnWidth(columnPosition: number, width: number): FWorksheet {
@@ -1339,9 +1374,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Set width of columns B-D (index 1-3) to 100 pixels
- * sheet.setColumnWidths(1, 3, 100);
+ * fWorksheet.setColumnWidths(1, 3, 100);
* ```
*/
setColumnWidths(startColumn: number, numColumn: number, width: number): FWorksheet {
@@ -1374,8 +1409,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* fWorkSheet.setColumnCustom({ 0: { key: 'value' } });
* ```
*/
@@ -1403,14 +1437,32 @@ export class FWorksheet extends FBaseInitialable {
// #region merge cells
+ /**
+ * Get all merged cells in the current worksheet
+ * @returns {FRange[]} All the merged cells in the worksheet
+ * @example
+ * ```ts
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // Get all merged ranges in the sheet
+ * const mergedData = fWorksheet.getMergeData();
+ * // Process each merged range
+ * mergedData.forEach(range => {
+ * console.log(range.getA1Notation());
+ * });
+ * ```
+ */
+ getMergeData(): FRange[] {
+ return this._worksheet.getMergeData().map((merge) => this._injector.createInstance(FRange, this._workbook, this._worksheet, merge));
+ }
+
/**
* Get all merged cells in the current sheet
* @returns {FRange[]} all merged cells
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get all merged ranges in the sheet
- * const mergedRanges = sheet.getMergedRanges();
+ * const mergedRanges = fWorksheet.getMergedRanges();
* // Process each merged range
* mergedRanges.forEach(range => {
* console.log(range.getA1Notation());
@@ -1429,8 +1481,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FRange|undefined} The merged cell data, or undefined if the cell is not merged
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const merge = fWorkSheet.getCellMergeData(0, 0);
* if (merge) {
* console.log('Merged range:', merge.getA1Notation());
@@ -1452,9 +1503,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FRange | null} the active range
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the currently active range
- * const activeRange = sheet.getActiveRange();
+ * const activeRange = fWorksheet.getActiveRange();
* if (activeRange) {
* console.log('Active range:', activeRange.getA1Notation());
* }
@@ -1470,9 +1521,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This sheet, for chaining
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
- * fWorkSheet.setActiveRange(fWorkSheet.getRange('A1'));
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorkSheet.setActiveRange(fWorkSheet.getRange('A10:B10'));
* ```
*/
setActiveRange(range: FRange): FWorksheet {
@@ -1492,9 +1542,8 @@ export class FWorksheet extends FBaseInitialable {
* @returns This sheet, for chaining
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
- * fWorkSheet.setActiveRange(fWorkSheet.getRange('A1'));
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorkSheet.setActiveSelection(fWorkSheet.getRange('A10:B10'));
* ```
*/
setActiveSelection = this.setActiveRange;
@@ -1507,9 +1556,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Freeze first 3 rows and 2 columns
- * sheet.setFreeze({
+ * fWorksheet.setFreeze({
* startRow: 3,
* startColumn: 2,
* xSplit: 2,
@@ -1532,9 +1581,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This worksheet instance for chaining
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Cancel freeze
- * sheet.cancelFreeze();
+ * fWorksheet.cancelFreeze();
* ```
*/
cancelFreeze(): FWorksheet {
@@ -1551,9 +1600,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {IFreeze} The freeze state of the current sheet
* @example
* ```typescript
- * const sheet = workbook.getActiveSheet();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the freeze state of the current sheet
- * const freeze = sheet.getFreeze();
+ * const freeze = fWorksheet.getFreeze();
* console.log(freeze);
* ```
*/
@@ -1568,8 +1617,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This FWorksheet instance.
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // freeze the first 3 columns.
* fWorkSheet.setFrozenColumns(3);
* ```
@@ -1585,10 +1633,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This FWorksheet instance.
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
- * // freeze the first too columns.
- * fWorkSheet.setFrozenColumns(0, 2);
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // freeze the column B and C, and column A will be invisible.
+ * fWorkSheet.setFrozenColumns(1, 2);
* ```
*/
setFrozenColumns(startColumn: number, endColumn: number): FWorksheet;
@@ -1625,8 +1672,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This FWorksheet instance.
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // freeze the first 3 rows.
* fWorkSheet.setFrozenRows(3);
* ```
@@ -1642,10 +1688,9 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} This FWorksheet instance.
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
- * // freeze the first too rows.
- * fWorkSheet.setFrozenRows(0, 2);
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * // freeze the second and third rows, and the first row will be invisible.
+ * fWorkSheet.setFrozenRows(1, 2);
* ```
*/
setFrozenRows(startRow: number, endRow: number): FWorksheet;
@@ -1680,8 +1725,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {number} The number of frozen columns, returns 0 if no columns are frozen.
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the number of frozen columns
* const frozenColumns = fWorkSheet.getFrozenColumns();
* console.log(frozenColumns);
@@ -1700,8 +1744,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {number} The number of frozen rows. returns 0 if no rows are frozen.
* @example
* ```typescript
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the number of frozen rows
* const frozenRows = fWorkSheet.getFrozenRows();
* console.log(frozenRows);
@@ -1720,8 +1763,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {IRowRange} The range of the frozen rows.
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the range of the frozen rows
* const frozenRows = fWorkSheet.getFrozenRowRange();
* console.log(frozenRows);
@@ -1740,8 +1782,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {IColumnRange} The range of the frozen columns.
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // Get the range of the frozen columns
* const frozenColumns = fWorkSheet.getFrozenColumnRange();
* console.log(frozenColumns);
@@ -1760,8 +1801,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {boolean} True if the sheet's gridlines are hidden; otherwise false.
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // check if the gridlines are hidden
* if (fWorkSheet.hasHiddenGridLines()) {
* console.log('Gridlines are hidden');
@@ -1778,8 +1818,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @example
* ``` ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // hide the gridlines
* fWorkSheet.setHiddenGridlines(true);
* ```
@@ -1799,8 +1838,7 @@ export class FWorksheet extends FBaseInitialable {
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @example
* ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
+ * const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
* // set the gridlines color to red
* fWorkSheet.setGridLinesColor('#ff0000');
* ```
@@ -1845,7 +1883,7 @@ export class FWorksheet extends FBaseInitialable {
this._commandService.syncExecuteCommand(SetTabColorCommand.id, {
unitId: this._workbook.getUnitId(),
subUnitId: this._worksheet.getSheetId(),
- color,
+ value: color,
});
return this;
}
@@ -1868,7 +1906,7 @@ export class FWorksheet extends FBaseInitialable {
// eslint-disable-next-line
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetValueChanged, callback)` instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {})` instead
*/
onCellDataChange(callback: (cellValue: ObjectMatrix<Nullable<ICellData>>) => void): IDisposable {
const commandService = this._injector.get(ICommandService);
@@ -1888,7 +1926,7 @@ export class FWorksheet extends FBaseInitialable {
// eslint-disable-next-line
/**
- * @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetValueChanged, callback)` instead
+ * @deprecated use `univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {})` instead
*/
onBeforeCellDataChange(callback: (cellValue: ObjectMatrix<Nullable<ICellData>>) => void): IDisposable {
const commandService = this._injector.get(ICommandService);
@@ -1953,6 +1991,13 @@ export class FWorksheet extends FBaseInitialable {
/**
* Returns true if the sheet is currently hidden.
* @returns {boolean} True if the sheet is hidden; otherwise, false.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheets = fWorkbook.getSheets();
+ * // check if the last sheet is hidden
+ * console.log(fWorkSheets[fWorkSheets.length - 1].isSheetHidden());
+ * ```
*/
isSheetHidden(): boolean {
return Boolean(this._worksheet.isSheetHidden() === BooleanNumber.TRUE);
@@ -1967,7 +2012,7 @@ export class FWorksheet extends FBaseInitialable {
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
* // set the sheet name to 'Sheet1'
- * fWorkSheet.setName('Sheet1');
+ * fWorkSheet.setName('NewSheet1');
* ```
*/
setName(name: string): FWorksheet {
@@ -1983,6 +2028,13 @@ export class FWorksheet extends FBaseInitialable {
/**
* Activates this sheet. Does not alter the sheet itself, only the parent's notion of the active sheet.
* @returns {FWorksheet} Current sheet, for chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorkSheets = fWorkbook.getSheets();
+ * // activate the last sheet
+ * fWorkSheets[fWorkSheets.length - 1].activate();
+ * ```
*/
activate(): FWorksheet {
this._fWorkbook.setActiveSheet(this);
@@ -1998,7 +2050,7 @@ export class FWorksheet extends FBaseInitialable {
* const fWorkSheet = fWorkbook.getActiveSheet();
* // get the position of the active sheet
* const position = fWorkSheet.getIndex();
- * console.log(position); // 0
+ * console.log(position);
* ```
*/
getIndex(): number {
@@ -2023,11 +2075,11 @@ export class FWorksheet extends FBaseInitialable {
*/
clear(options?: IFacadeClearOptions): FWorksheet {
if (options && options.contentsOnly && !options.formatOnly) {
- this.clearContents();
+ return this.clearContents();
}
if (options && options.formatOnly && !options.contentsOnly) {
- this.clearFormats();
+ return this.clearFormats();
}
const unitId = this._workbook.getUnitId();
@@ -2121,10 +2173,10 @@ export class FWorksheet extends FBaseInitialable {
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
- * // the sheet is a empty sheet
- * const cellRange = fWorkSheet.getRange(200, 10, 1, 1);
+ * // Assume the sheet is a empty sheet
+ * const cellRange = fWorkSheet.getRange('J50');
* cellRange.setValue('Hello World');
- * console.log(fWorkSheet.getDataRange().getA1Notation()); // A1:J200
+ * console.log(fWorkSheet.getDataRange().getA1Notation()); // A1:J50
* ```
*/
getDataRange(): FRange {
@@ -2134,30 +2186,25 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * Returns the position of the last column that has content.
- * @returns {number} the last column of the sheet that contains content.
- * @example
- * ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
- * const fRange = fWorkSheet.getRange(100, 20, 1, 1);
- * console.log(fWorkSheet.getLastColumns()); // 20
- * ```
+ * @deprecated use `getLastColumn` instead.
+ * Returns the column index of the last column that contains content.
+ * @returns {number} the column index of the last column that contains content.
*/
getLastColumns(): number {
return this._worksheet.getLastColumnWithContent();
}
/**
- * @deprecated use getLastColumn instead.
- * Returns the position of the last column that has content. Same as getLastColumns.
- * @returns {number} the last column of the sheet that contains content.
+ * Returns the column index of the last column that contains content.
+ * @returns {number} the column index of the last column that contains content.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
- * const fRange = fWorkSheet.getRange(100, 20, 1, 1);
- * console.log(fWorkSheet.getLastColumn());
+ * // Assume the sheet is a empty sheet
+ * const cellRange = fWorkSheet.getRange('J50');
+ * cellRange.setValue('Hello World');
+ * console.log(fWorkSheet.getLastColumn()); // 9
* ```
*/
getLastColumn(): number {
@@ -2165,31 +2212,26 @@ export class FWorksheet extends FBaseInitialable {
}
/**
- * @deprecated use getLastRow instead.
- * Returns the position of the last row that has content.
- * @returns {number} the last row of the sheet that contains content.
- * @example
- * ```ts
- * const fWorkbook = univerAPI.getActiveWorkbook();
- * const fWorkSheet = fWorkbook.getActiveSheet();
- * const fRange = fWorkSheet.getRange(100,1,1,1);
- * fRange.setValue('Hello World');
- * console.log(fWorkSheet.getLastRows()); // 100
+ * @deprecated use `getLastRow` instead.
+ * Returns the row index of the last row that contains content.
+ * @returns {number} the row index of the last row that contains content.
*/
getLastRows(): number {
return this._worksheet.getLastRowWithContent();
}
/**
- * Returns the position of the last row that has content, same as getLastRows().
- * @returns {number} the last row of the sheet that contains content.
+ * Returns the row index of the last row that contains content.
+ * @returns {number} the row index of the last row that contains content.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
- * const fRange = fWorkSheet.getRange(100,1,1,1);
- * fRange.setValue('Hello World');
- * console.log(fWorkSheet.getLastRow());
+ * // Assume the sheet is a empty sheet
+ * const cellRange = fWorkSheet.getRange('J50');
+ * cellRange.setValue('Hello World');
+ * console.log(fWorkSheet.getLastRow()); // 49
+ * ```
*/
getLastRow(): number {
return this._worksheet.getLastRowWithContent();
@@ -2202,9 +2244,9 @@ export class FWorksheet extends FBaseInitialable {
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheets = fWorkbook.getSheets();
* const fWorkSheet = fWorkbook.getActiveSheet();
- * const fWorkSheet2 = fWorkbook.getSheetByName('Sheet1');
- * console.log(fWorkSheet.equals(fWorkSheet2)); // true, if the active sheet is 'Sheet1'
+ * console.log(fWorkSheet.equalTo(sheets[0])); // true, if the active sheet is the first sheet.
* ```
*/
equalTo(other: FWorksheet): boolean {
@@ -2214,16 +2256,15 @@ export class FWorksheet extends FBaseInitialable {
return false;
}
- /*
- * Insert a defined name for worksheet.
+ /**
+ * Insert a defined name for worksheet.
* @param {string} name - The name of the defined name to insert
* @param {string} formulaOrRefString - The formula(=sum(A2:b10)) or reference(A1) string of the defined name to insert
* @example
* ```ts
* // The code below inserts a defined name
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheet1 = activeSpreadsheet.getSheetByName('Sheet1');
- * sheet1.insertDefinedName('MyDefinedName', 'Sheet1!A1');
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * fWorksheet.insertDefinedName('MyDefinedName', 'Sheet1!A1');
* ```
*/
insertDefinedName(name: string, formulaOrRefString: string): void {
@@ -2239,9 +2280,9 @@ export class FWorksheet extends FBaseInitialable {
* @example
* ```ts
* // The code below gets all the defined names in the worksheet
- * const activeSpreadsheet = univerAPI.getActiveWorkbook();
- * const sheet1 = activeSpreadsheet.getSheetByName('Sheet1');
- * const definedNames = sheet1.getDefinedNames();
+ * const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
+ * const definedNames = fWorksheet.getDefinedNames();
+ * console.log(definedNames);
* ```
*/
getDefinedNames(): FDefinedName[] {
@@ -2252,7 +2293,7 @@ export class FWorksheet extends FBaseInitialable {
/**
* Set custom metadata of worksheet
* @param {CustomData | undefined} custom - custom metadata
- * @returns {FWorksheet}
+ * @returns {FWorksheet} Current worksheet, for chaining.
* @example
* ```ts
* const fWorkbook = univerAPI.getActiveWorkbook();
@@ -2308,6 +2349,7 @@ export class FWorksheet extends FBaseInitialable {
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
* const custom = fWorkSheet.getRowCustomMetadata(0);
+ * console.log(custom);
* ```
*/
getRowCustomMetadata(index: number): CustomData | undefined {
@@ -2323,28 +2365,10 @@ export class FWorksheet extends FBaseInitialable {
* const fWorkbook = univerAPI.getActiveWorkbook();
* const fWorkSheet = fWorkbook.getActiveSheet();
* const custom = fWorkSheet.getColumnCustomMetadata(0);
+ * console.log(custom);
* ```
*/
getColumnCustomMetadata(index: number): CustomData | undefined {
return this._worksheet.getColumnManager().getCustomMetadata(index);
}
-
- /**
- * Get all merged cells in the current worksheet
- * @returns {FRange[]} All the merged cells in the worksheet
- * @example
- * ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getActiveSheet();
- * const rangeFirst = worksheet.getRange(0, 0, 2, 2);
- * const mergeFirst = rangeFirst.merge();
- * const rangeSecond = worksheet.getRange(5, 0, 2, 2);
- * const mergeSecond = rangeSecond.merge();
- * const mergeData = worksheet.getMergeData();
- * console.log('debugger', mergeData);
- * ```
- */
- getMergeData(): FRange[] {
- return this._worksheet.getMergeData().map((merge) => this._injector.createInstance(FRange, this._workbook, this._worksheet, merge));
- }
}
diff --git a/packages/sheets/src/index.ts b/packages/sheets/src/index.ts
index 6a101dfdee..7b37d72bfc 100644
--- a/packages/sheets/src/index.ts
+++ b/packages/sheets/src/index.ts
@@ -102,8 +102,7 @@ export { AddMergeRedoSelectionsOperationFactory, AddMergeUndoSelectionsOperation
export type { FormatType } from './services/numfmt/type';
export { expandToContinuousRange } from './basics/expand-range';
-export { splitRangeText } from './basics/split-range-text';
-export type { SplitDelimiterEnum } from './basics/split-range-text';
+export { SplitDelimiterEnum, splitRangeText } from './basics/split-range-text';
export { getNextPrimaryCell } from './services/selections/move-active-cell-util';
export { checkCellValueType } from './basics/cell-type';