Skip to content

Commit

Permalink
feat(facade): make facade api sync and chainable (#4329)
Browse files Browse the repository at this point in the history
  • Loading branch information
@weird94
weird94 authored Dec 31, 2024
1 parent 61fff64 commit c5fcf3e
Show file tree
Hide file tree
Showing 54 changed files with 704 additions and 439 deletions.
15 changes: 15 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,21 @@ npm create @univerjs/cli init <project-name>

```

### How to Contribute to Facade API
#### Synchronous API Priority
* For asynchronous APIs, consider the following: Can a synchronous sub-API be extracted, separating logic such as secondary confirmation.
* For APIs that must be asynchronous, indicate this in the method name, such as `addCommentAsync`.

#### Chaining Principle
*. APIs must adhere to the chaining principle.
*. APIs with `modify` semantics should return `this`.
*. APIs with `create` semantics should return the created instance.
*. APIs with `delete` semantics should return `true/false`.

#### Easy to Get
*. All APIs/constants/enums should be accessible from the `univerAPI` variable.


## Links

* [How to Contribute to Facade API](./packages/facade/docs/CONTRIBUTING.md)
4 changes: 2 additions & 2 deletions packages/core/src/services/undoredo/undoredo.service.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ export const UndoCommand = new (class extends MultiImplementationCommand impleme

readonly id = UndoCommandId;

async handler(accessor: IAccessor) {
handler(accessor: IAccessor) {
const undoRedoService = accessor.get(IUndoRedoService);
const element = undoRedoService.pitchTopUndoElement();

Expand All @@ -136,7 +136,7 @@ export const RedoCommand = new (class extends MultiImplementationCommand impleme

readonly id = RedoCommandId;

async handler(accessor: IAccessor) {
handler(accessor: IAccessor) {
const undoRedoService = accessor.get(IUndoRedoService);
const element = undoRedoService.pitchTopRedoElement();
if (!element) {
Expand Down
11 changes: 10 additions & 1 deletion packages/facade/src/apis/sheets/__tests__/f-worksheet.spec.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@

import type { FUniver, Injector, Workbook } from '@univerjs/core';
import { ICommandService, IUniverInstanceService, RANGE_TYPE, UniverInstanceType } from '@univerjs/core';
import { AddWorksheetMergeCommand, AddWorksheetMergeMutation, CancelFrozenCommand, InsertColCommand, InsertColMutation, InsertRowCommand, InsertRowMutation, MoveColsCommand, MoveColsMutation, MoveRowsCommand, MoveRowsMutation, RemoveColCommand, RemoveColMutation, RemoveRowCommand, RemoveRowMutation, RemoveWorksheetMergeCommand, RemoveWorksheetMergeMutation, SetColDataCommand, SetColDataMutation, SetColHiddenCommand, SetColHiddenMutation, SetColVisibleMutation, SetColWidthCommand, SetFrozenCommand, SetFrozenMutation, SetHorizontalTextAlignCommand, SetRangeValuesCommand, SetRangeValuesMutation, SetRowDataCommand, SetRowDataMutation, SetRowHeightCommand, SetRowHiddenCommand, SetRowHiddenMutation, SetRowVisibleMutation, SetSelectionsOperation, SetSpecificColsVisibleCommand, SetSpecificRowsVisibleCommand, SetStyleCommand, SetTextWrapCommand, SetVerticalTextAlignCommand, SetWorksheetColWidthMutation, SetWorksheetRowHeightMutation, SetWorksheetRowIsAutoHeightCommand, SetWorksheetRowIsAutoHeightMutation, SheetsSelectionsService } from '@univerjs/sheets';
import { AddWorksheetMergeCommand, AddWorksheetMergeMutation, CancelFrozenCommand, InsertColByRangeCommand, InsertColCommand, InsertColMutation, InsertRowByRangeCommand, InsertRowCommand, InsertRowMutation, MoveColsCommand, MoveColsMutation, MoveRowsCommand, MoveRowsMutation, RemoveColByRangeCommand, RemoveColCommand, RemoveColMutation, RemoveRowByRangeCommand, RemoveRowCommand, RemoveRowMutation, RemoveWorksheetMergeCommand, RemoveWorksheetMergeMutation, SetColDataCommand, SetColDataMutation, SetColHiddenCommand, SetColHiddenMutation, SetColVisibleMutation, SetColWidthCommand, SetFrozenCommand, SetFrozenMutation, SetHorizontalTextAlignCommand, SetRangeValuesCommand, SetRangeValuesMutation, SetRowDataCommand, SetRowDataMutation, SetRowHeightCommand, SetRowHiddenCommand, SetRowHiddenMutation, SetRowVisibleMutation, SetSelectionsOperation, SetSpecificColsVisibleCommand, SetSpecificRowsVisibleCommand, SetStyleCommand, SetTextWrapCommand, SetVerticalTextAlignCommand, SetWorksheetColWidthMutation, SetWorksheetRowHeightMutation, SetWorksheetRowIsAutoHeightCommand, SetWorksheetRowIsAutoHeightMutation, SheetsSelectionsService } from '@univerjs/sheets';

import { beforeEach, describe, expect, it } from 'vitest';
import { createWorksheetTestBed } from './create-worksheet-test-bed';
Expand Down Expand Up @@ -89,6 +89,15 @@ describe('Test FWorksheet', () => {
commandService.registerCommand(SetFrozenMutation);
commandService.registerCommand(CancelFrozenCommand);

[
RemoveColByRangeCommand,
RemoveRowByRangeCommand,
InsertRowByRangeCommand,
InsertColByRangeCommand,
].forEach((command) => {
commandService.registerCommand(command);
});

setSelection = (startRow: number, endRow: number, startColumn: number, endColumn: number, rangeType: RANGE_TYPE = RANGE_TYPE.NORMAL) => {
const selectionManagerService = get(SheetsSelectionsService);
selectionManagerService.addSelections([
Expand Down
43 changes: 24 additions & 19 deletions packages/sheets-conditional-formatting/src/facade/f-range.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,17 +74,17 @@ export interface IFRangeConditionalFormattingMixin {
/**
* Add a new conditional format
* @param {IConditionFormattingRule} rule
* @return {*} {Promise<boolean>}
* @memberof IFWorksheetConditionalFormattingMixin
* @returns {FRange} Returns the current range instance for method chaining
* @memberof IFRangeConditionalFormattingMixin
*/
addConditionalFormattingRule(rule: IConditionFormattingRule): Promise<boolean>;
addConditionalFormattingRule(rule: IConditionFormattingRule): FRange;

/**
* Delete conditional format according to `cfId`
*
* @param {string} cfId
* @return {*} {Promise<boolean>}
* @memberof IFWorksheetConditionalFormattingMixin
* @returns {FRange} Returns the current range instance for method chaining
* @memberof IFRangeConditionalFormattingMixin
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
Expand All @@ -93,14 +93,15 @@ export interface IFRangeConditionalFormattingMixin {
* worksheet?.deleteConditionalFormattingRule(rules![0].cfId);
* ```
*/
deleteConditionalFormattingRule(cfId: string): Promise<boolean>;
deleteConditionalFormattingRule(cfId: string): FRange;

/**
* Modify the priority of the conditional format
* @param {string} cfId Rules that need to be moved
* @param {string} toCfId Target rule
* @param {IAnchor['type']} [type] After the default move to the destination rule, if type = before moves to the front, the default value is after
* @memberof FWorksheetConditionalFormattingMixin
* @returns {FRange} Returns the current range instance for method chaining
* @memberof FRangeConditionalFormattingMixin
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
Expand All @@ -111,14 +112,14 @@ export interface IFRangeConditionalFormattingMixin {
* worksheet?.moveConditionalFormattingRule(rule.cfId, targetRule.cfId, 'before');
* ```
*/
moveConditionalFormattingRule(cfId: string, toCfId: string, type?: IAnchor['type']): Promise<boolean>;
moveConditionalFormattingRule(cfId: string, toCfId: string, type?: IAnchor['type']): FRange;

/**
* Set the conditional format according to `cfId`
* @param {string} cfId
* @param {IConditionFormattingRule} rule
* @return {*} {Promise<boolean>}
* @memberof IFWorksheetConditionalFormattingMixin
* @returns {FRange} Returns the current range instance for method chaining
* @memberof IFRangeConditionalFormattingMixin
* @example
* ```ts
* const workbook = univerAPI.getActiveWorkbook();
Expand All @@ -128,7 +129,7 @@ export interface IFRangeConditionalFormattingMixin {
* worksheet?.setConditionalFormattingRule(rule.cfId, { ...rule, ranges: [] });
* ```
*/
setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): Promise<boolean>;
setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): FRange;
}

export class FRangeConditionalFormattingMixin extends FRange implements IFRangeConditionalFormattingMixin {
Expand All @@ -145,36 +146,40 @@ export class FRangeConditionalFormattingMixin extends FRange implements IFRangeC
return new FConditionalFormattingBuilder({ ranges: [this._range] });
}

override addConditionalFormattingRule(rule: IConditionFormattingRule): Promise<boolean> {
override addConditionalFormattingRule(rule: IConditionFormattingRule): FRange {
const params: IAddConditionalRuleMutationParams = {
rule, unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
};
return this._commandService.executeCommand(AddConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(AddConditionalRuleMutation.id, params);
return this;
}

override deleteConditionalFormattingRule(cfId: string): Promise<boolean> {
override deleteConditionalFormattingRule(cfId: string): FRange {
const params: IDeleteConditionalRuleMutationParams = {
unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
cfId,
};
return this._commandService.executeCommand(DeleteConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(DeleteConditionalRuleMutation.id, params);
return this;
}

override moveConditionalFormattingRule(cfId: string, toCfId: string, type: IAnchor['type'] = 'after'): Promise<boolean> {
override moveConditionalFormattingRule(cfId: string, toCfId: string, type: IAnchor['type'] = 'after'): FRange {
const params: IMoveConditionalRuleMutationParams = {
unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
start: { id: cfId, type: 'self' }, end: { id: toCfId, type },
};
return this._commandService.executeCommand(MoveConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(MoveConditionalRuleMutation.id, params);
return this;
}

override setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): Promise<boolean> {
override setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): FRange {
const params: ISetConditionalRuleMutationParams = {
unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
rule,
cfId,
};
return this._commandService.executeCommand(SetConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(SetConditionalRuleMutation.id, params);
return this;
}
}

Expand Down
35 changes: 20 additions & 15 deletions packages/sheets-conditional-formatting/src/facade/f-worksheet.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ export interface IFWorksheetConditionalFormattingMixin {
/**
* Add a new conditional format
* @param {IConditionFormattingRule} rule
* @return {*} {Promise<boolean>}
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @memberof IFWorksheetConditionalFormattingMixin
* @example
* ```ts
Expand All @@ -84,13 +84,13 @@ export interface IFWorksheetConditionalFormattingMixin {
* worksheet?.addConditionalFormattingRule(rule!);
* ```
*/
addConditionalFormattingRule(rule: IConditionFormattingRule): Promise<boolean>;
addConditionalFormattingRule(rule: IConditionFormattingRule): FWorksheet;

/**
* Delete conditional format according to `cfId`
*
* @param {string} cfId
* @return {*} {Promise<boolean>}
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @memberof IFWorksheetConditionalFormattingMixin
* @example
* ```ts
Expand All @@ -100,13 +100,14 @@ export interface IFWorksheetConditionalFormattingMixin {
* worksheet?.deleteConditionalFormattingRule(rules![0].cfId);
* ```
*/
deleteConditionalFormattingRule(cfId: string): Promise<boolean>;
deleteConditionalFormattingRule(cfId: string): FWorksheet;

/**
* Modify the priority of the conditional format
* @param {string} cfId Rules that need to be moved
* @param {string} toCfId Target rule
* @param {IAnchor['type']} [type] After the default move to the destination rule, if type = before moves to the front, the default value is after
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @memberof FWorksheetConditionalFormattingMixin
* @example
* ```ts
Expand All @@ -118,13 +119,13 @@ export interface IFWorksheetConditionalFormattingMixin {
* worksheet?.moveConditionalFormattingRule(rule.cfId, targetRule.cfId, 'before');
* ```
*/
moveConditionalFormattingRule(cfId: string, toCfId: string, type?: IAnchor['type']): Promise<boolean>;
moveConditionalFormattingRule(cfId: string, toCfId: string, type?: IAnchor['type']): FWorksheet;

/**
* Set the conditional format according to `cfId`
* @param {string} cfId
* @param {IConditionFormattingRule} rule
* @return {*} {Promise<boolean>}
* @returns {FWorksheet} Returns the current worksheet instance for method chaining
* @memberof IFWorksheetConditionalFormattingMixin
* @example
* ```ts
Expand All @@ -135,7 +136,7 @@ export interface IFWorksheetConditionalFormattingMixin {
* worksheet?.setConditionalFormattingRule(rule.cfId, { ...rule, ranges: [] });
* ```
*/
setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): Promise<boolean>;
setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): FWorksheet;
}

export class FWorksheetConditionalFormattingMixin extends FWorksheet implements IFWorksheetConditionalFormattingMixin {
Expand All @@ -152,36 +153,40 @@ export class FWorksheetConditionalFormattingMixin extends FWorksheet implements
return new FConditionalFormattingBuilder();
}

override addConditionalFormattingRule(rule: IConditionFormattingRule): Promise<boolean> {
override addConditionalFormattingRule(rule: IConditionFormattingRule): FWorksheet {
const params: IAddConditionalRuleMutationParams = {
rule, unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
};
return this._commandService.executeCommand(AddConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(AddConditionalRuleMutation.id, params);
return this;
}

override deleteConditionalFormattingRule(cfId: string): Promise<boolean> {
override deleteConditionalFormattingRule(cfId: string): FWorksheet {
const params: IDeleteConditionalRuleMutationParams = {
unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
cfId,
};
return this._commandService.executeCommand(DeleteConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(DeleteConditionalRuleMutation.id, params);
return this;
}

override moveConditionalFormattingRule(cfId: string, toCfId: string, type: IAnchor['type'] = 'after'): Promise<boolean> {
override moveConditionalFormattingRule(cfId: string, toCfId: string, type: IAnchor['type'] = 'after'): FWorksheet {
const params: IMoveConditionalRuleMutationParams = {
unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
start: { id: cfId, type: 'self' }, end: { id: toCfId, type },
};
return this._commandService.executeCommand(MoveConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(MoveConditionalRuleMutation.id, params);
return this;
}

override setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): Promise<boolean> {
override setConditionalFormattingRule(cfId: string, rule: IConditionFormattingRule): FWorksheet {
const params: ISetConditionalRuleMutationParams = {
unitId: this._workbook.getUnitId(), subUnitId: this._worksheet.getSheetId(),
rule,
cfId,
};
return this._commandService.executeCommand(SetConditionalRuleMutation.id, params);
this._commandService.syncExecuteCommand(SetConditionalRuleMutation.id, params);
return this;
}
}

Expand Down
17 changes: 10 additions & 7 deletions packages/sheets-crosshair-highlight/src/facade/f-univer.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,28 +23,31 @@ export interface IFUniverCrosshairHighlightMixin {
* Enable or disable crosshair highlight.
* @param {boolean} enabled if crosshair highlight should be enabled
*/
setCrosshairHighlightEnabled(enabled: boolean): void;
setCrosshairHighlightEnabled(enabled: boolean): FUniver;

/**
* Set the color of the crosshair highlight.
* @param {string} color the color of the crosshair highlight
*/
setCrosshairHighlightColor(color: string): void;
setCrosshairHighlightColor(color: string): FUniver;
}

export class FUniverCrosshairHighlightMixin extends FUniver implements IFUniverCrosshairHighlightMixin {
override setCrosshairHighlightEnabled(enabled: boolean): void {
override setCrosshairHighlightEnabled(enabled: boolean): FUniver {
if (enabled) {
this._commandService.executeCommand(EnableCrosshairHighlightOperation.id);
this._commandService.syncExecuteCommand(EnableCrosshairHighlightOperation.id);
} else {
this._commandService.executeCommand(DisableCrosshairHighlightOperation.id);
this._commandService.syncExecuteCommand(DisableCrosshairHighlightOperation.id);
}

return this;
}

override setCrosshairHighlightColor(color: string): void {
this._commandService.executeCommand(SetCrosshairHighlightColorOperation.id, {
override setCrosshairHighlightColor(color: string): FUniver {
this._commandService.syncExecuteCommand(SetCrosshairHighlightColorOperation.id, {
value: color,
} as ISetCrosshairHighlightColorOperationParams);
return this;
}
}

Expand Down
5 changes: 5 additions & 0 deletions packages/sheets-data-validation/src/facade/f-data-validation-builder.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,11 @@ export class FDataValidationBuilder {
return this;
}

setAllowBlank(allowBlank: boolean): FDataValidationBuilder {
this._rule.allowBlank = allowBlank;
return this;
}

/**
* Sets the options for the data validation rule.
* For details of options, please refer to https://univer.ai/typedoc/@univerjs/core/interfaces/IDataValidationRuleOptions
Expand Down
Loading

0 comments on commit c5fcf3e

Please sign in to comment.