Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat: supplement defined names facade example and notes (#4942)

wpxp123456791e4906b8cd
diff --git a/packages/sheets-formula/src/facade/f-enum.ts b/packages/sheets-formula/src/facade/f-enum.ts
new file mode 100644
index 0000000000..7372fe8e82
--- /dev/null
+++ b/packages/sheets-formula/src/facade/f-enum.ts
@@ -0,0 +1,41 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { FEnum } from '@univerjs/core/facade';
+import { CalculationMode } from '@univerjs/sheets-formula';
+
+/**
+ * @ignore
+ */
+export interface IFSheetsFormulaEnum {
+ /**
+ * Define the calculation mode during initialization
+ */
+ CalculationMode: typeof CalculationMode;
+}
+
+export class FSheetsFormulaEnum implements IFSheetsFormulaEnum {
+ get CalculationMode(): typeof CalculationMode {
+ return CalculationMode;
+ }
+}
+
+FEnum.extend(FSheetsFormulaEnum);
+declare module '@univerjs/core/facade' {
+ // eslint-disable-next-line ts/naming-convention
+ export interface FEnum extends IFSheetsFormulaEnum {
+ }
+}
diff --git a/packages/sheets-formula/src/facade/index.ts b/packages/sheets-formula/src/facade/index.ts
index b87daa3438..f291782684 100644
--- a/packages/sheets-formula/src/facade/index.ts
+++ b/packages/sheets-formula/src/facade/index.ts
@@ -16,6 +16,7 @@
import './f-univer';
import './f-formula';
+import './f-enum';
export type * from './f-formula';
export type * from './f-univer';
diff --git a/packages/sheets/src/facade/f-defined-name.ts b/packages/sheets/src/facade/f-defined-name.ts
index 27ddf708fd..2c34f17dc7 100644
--- a/packages/sheets/src/facade/f-defined-name.ts
+++ b/packages/sheets/src/facade/f-defined-name.ts
@@ -62,6 +62,7 @@ export class FDefinedNameBuilder {
unitId: '',
name: '',
formulaOrRefString: '',
+ localSheetId: SCOPE_WORKBOOK_VALUE_DEFINED_NAME,
};
}
@@ -71,11 +72,12 @@ export class FDefinedNameBuilder {
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
* .setName('MyDefinedName')
+ * .setRef('Sheet1!$A$1')
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
setName(name: string): FDefinedNameBuilder {
@@ -89,12 +91,12 @@ export class FDefinedNameBuilder {
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
- * .setFormula('SUM(Sheet1!$A$1)')
* .setName('MyDefinedName')
+ * .setFormula('SUM(Sheet1!$A$1)')
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
setFormula(formula: string): FDefinedNameBuilder {
@@ -108,11 +110,12 @@ export class FDefinedNameBuilder {
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
+ * .setName('MyDefinedName')
* .setRef('Sheet1!$A$1')
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
setRef(a1Notation: string): FDefinedNameBuilder {
@@ -122,18 +125,19 @@ export class FDefinedNameBuilder {
/**
* Sets the reference of the defined name builder by range .
- * @param {number} row The start row of the range.
- * @param {number} column The start column of the range.
+ * @param {number} row The start row index of the range. index start at 0.
+ * @param {number} column The start column index of the range. index start at 0.
* @param {number} numRows The number of rows in the range.
* @param {number} numColumns The number of columns in the range.
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
- * .setRefByRange(1, 3, 2, 5)
+ * .setName('MyDefinedName')
+ * .setRefByRange(1, 3, 2, 5) // D2:H3
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
setRefByRange(row: number, column: number, numRows: number, numColumns: number): FDefinedNameBuilder {
@@ -152,11 +156,13 @@ export class FDefinedNameBuilder {
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
- * .setComment('This is a comment')
+ * .setName('MyDefinedName')
+ * .setRef('Sheet1!$A$1')
+ * .setComment('A reference to A1 cell in Sheet1')
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
setComment(comment: string): FDefinedNameBuilder {
@@ -164,17 +170,63 @@ export class FDefinedNameBuilder {
return this;
}
+ /**
+ * Sets the scope of the defined name to the worksheet.
+ * @param {FWorksheet} worksheet The worksheet to set the scope to.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheets = fWorkbook.getSheets();
+ *
+ * // Create a defined name and make it available only in the second worksheet
+ * const definedNameBuilder = univerAPI.newDefinedName()
+ * .setName('MyDefinedName')
+ * .setRef('Sheet1!$A$1')
+ * .setScopeToWorksheet(sheets[1])
+ * .build();
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
+ * ```
+ */
+ setScopeToWorksheet(worksheet: FWorksheet): FDefinedNameBuilder {
+ this._definedNameParam.localSheetId = worksheet.getSheetId();
+ return this;
+ }
+
+ /**
+ * Sets the scope of the defined name to the workbook.
+ * @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
+ * @example
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ *
+ * // Create a defined name and make it available in the entire workbook
+ * const definedNameBuilder = univerAPI.newDefinedName()
+ * .setName('MyDefinedName')
+ * .setRef('Sheet1!$A$1')
+ * .setScopeToWorkbook()
+ * .build();
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
+ * ```
+ */
+ setScopeToWorkbook(): FDefinedNameBuilder {
+ this._definedNameParam.localSheetId = SCOPE_WORKBOOK_VALUE_DEFINED_NAME;
+ return this;
+ }
+
/**
* Sets the hidden status of the defined name builder.
* @param {boolean} hidden The hidden status of the defined name.
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
+ * .setName('MyDefinedName')
+ * .setRef('Sheet1!$A$1')
* .setHidden(true)
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
setHidden(hidden: boolean): FDefinedNameBuilder {
@@ -187,13 +239,13 @@ export class FDefinedNameBuilder {
* @returns {ISetDefinedNameMutationParam} The defined name mutation parameter.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameBuilder = univerAPI.newDefinedName()
- * .setRef('Sheet1!$A$1')
* .setName('MyDefinedName')
- * .setComment('This is a comment')
+ * .setRef('Sheet1!$A$1')
+ * .setComment('A reference to A1 cell in Sheet1')
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
build(): ISetDefinedNameMutationParam {
@@ -206,17 +258,17 @@ export class FDefinedNameBuilder {
* @returns {FDefinedNameBuilder} The instance of `FDefinedNameBuilder` for method chaining.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
+ * const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNameParam = {
* id: '4TMPceoqg8',
- * unitId: workbook.getId(),
+ * unitId: fWorkbook.getId(),
* name: 'MyDefinedName',
* formulaOrRefString: 'Sheet1!$A$1',
* }
* const definedNameBuilder = univerAPI.newDefinedName()
* .load(definedNameParam)
* .build();
- * workbook.insertDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.insertDefinedNameBuilder(definedNameBuilder);
* ```
*/
load(param: ISetDefinedNameMutationParam): FDefinedNameBuilder {
@@ -256,8 +308,8 @@ export class FDefinedName extends FBase {
* @returns {string} The name of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* console.log(definedName?.getName());
* ```
*/
@@ -270,8 +322,8 @@ export class FDefinedName extends FBase {
* @param {string} name The name of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* definedName?.setName('NewDefinedName');
* ```
*/
@@ -285,8 +337,8 @@ export class FDefinedName extends FBase {
* @param {string} formula The formula of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* definedName?.setFormula('SUM(Sheet1!$A$1)');
* ```
*/
@@ -300,8 +352,8 @@ export class FDefinedName extends FBase {
* @param {string} refString The reference of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* definedName?.setRef('Sheet1!$A$1');
* ```
*/
@@ -315,8 +367,8 @@ export class FDefinedName extends FBase {
* @returns {string} The formula or reference string of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* console.log(definedName?.getFormulaOrRefString());
* ```
*/
@@ -332,9 +384,9 @@ export class FDefinedName extends FBase {
* @param {number} numColumns The number of columns in the range.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
- * definedName?.setRefByRange(1, 3, 2, 5);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
+ * definedName?.setRefByRange(1, 3, 2, 5); // D2:H3
* ```
*/
setRefByRange(row: number, column: number, numRows: number, numColumns: number): void {
@@ -352,8 +404,8 @@ export class FDefinedName extends FBase {
* @returns {string | undefined} The comment of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* console.log(definedName?.getComment());
* ```
*/
@@ -366,8 +418,8 @@ export class FDefinedName extends FBase {
* @param {string} comment The comment of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* definedName?.setComment('This is a comment');
* ```
*/
@@ -381,10 +433,12 @@ export class FDefinedName extends FBase {
* @param {FWorksheet} worksheet The worksheet to set the scope to.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const worksheet = workbook.getSheets()[0];
- * const definedName = workbook.getDefinedNames()[0];
- * definedName?.setScopeToWorksheet(worksheet);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const sheets = fWorkbook.getSheets();
+ *
+ * // Get the first defined name and make it available only in the second worksheet
+ * const definedName = fWorkbook.getDefinedNames()[0];
+ * definedName?.setScopeToWorksheet(sheets[1]);
* ```
*/
setScopeToWorksheet(worksheet: FWorksheet): void {
@@ -396,8 +450,8 @@ export class FDefinedName extends FBase {
* Sets the scope of the defined name to the workbook.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* definedName?.setScopeToWorkbook();
* ```
*/
@@ -411,8 +465,8 @@ export class FDefinedName extends FBase {
* @param {boolean} hidden The hidden status of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* definedName?.setHidden(true);
* ```
*/
@@ -425,8 +479,8 @@ export class FDefinedName extends FBase {
* Deletes the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* definedName?.delete();
* ```
*/
@@ -439,8 +493,8 @@ export class FDefinedName extends FBase {
* @returns {string | undefined} The local sheet id of the defined name.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* console.log(definedName?.getLocalSheetId());
* ```
*/
@@ -453,8 +507,8 @@ export class FDefinedName extends FBase {
* @returns {boolean} True if the defined name is in the workbook scope, false otherwise.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* console.log(definedName?.isWorkbookScope());
* ```
*/
@@ -467,15 +521,15 @@ export class FDefinedName extends FBase {
* @returns {FDefinedNameBuilder} The defined name builder.
* @example
* ```ts
- * const workbook = univerAPI.getActiveWorkbook();
- * const definedName = workbook.getDefinedNames()[0];
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const definedName = fWorkbook.getDefinedNames()[0];
* if (!definedName) return;
* const definedNameBuilder = definedName
* .toBuilder()
* .setName('NewDefinedName')
* .setFormula('SUM(Sheet1!$A$1)')
* .build();
- * workbook.updateDefinedNameBuilder(definedNameBuilder);
+ * fWorkbook.updateDefinedNameBuilder(definedNameBuilder);
* ```
*/
toBuilder(): FDefinedNameBuilder {
diff --git a/packages/sheets/src/facade/f-workbook.ts b/packages/sheets/src/facade/f-workbook.ts
index 299c7f5991..aaee728663 100644
--- a/packages/sheets/src/facade/f-workbook.ts
+++ b/packages/sheets/src/facade/f-workbook.ts
@@ -760,7 +760,11 @@ export class FWorkbook extends FBaseInitialable {
* // The code below gets the defined name by name
* const fWorkbook = univerAPI.getActiveWorkbook();
* const definedName = fWorkbook.getDefinedName('MyDefinedName');
- * console.log(definedName);
+ * console.log(definedName?.getFormulaOrRefString());
+ *
+ * if (definedName) {
+ * definedName.setName('NewDefinedName');
+ * }
* ```
*/
getDefinedName(name: string): FDefinedName | null {
@@ -780,7 +784,7 @@ export class FWorkbook extends FBaseInitialable {
* // The code below gets all the defined names in the workbook
* const fWorkbook = univerAPI.getActiveWorkbook();
* const definedNames = fWorkbook.getDefinedNames();
- * console.log(definedNames);
+ * console.log(definedNames, definedNames[0]?.getFormulaOrRefString());
* ```
*/
getDefinedNames(): FDefinedName[] {
@@ -802,7 +806,7 @@ export class FWorkbook extends FBaseInitialable {
* ```ts
* // The code below inserts a defined name
* const fWorkbook = univerAPI.getActiveWorkbook();
- * fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!A1');
+ * fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1');
* ```
*/
insertDefinedName(name: string, formulaOrRefString: string): FWorkbook {
@@ -863,11 +867,17 @@ export class FWorkbook extends FBaseInitialable {
* ```ts
* // The code below updates the defined name with the given name
* const fWorkbook = univerAPI.getActiveWorkbook();
- * const definedNameBuilder = fWorkbook.getDefinedName('MyDefinedName').toBuilder();
- * const param = definedNameBuilder.setRef('Sheet1!A2')
- * .setName('NewDefinedName')
- * .build();
- * fWorkbook.updateDefinedNameBuilder(param);
+ * const definedName = fWorkbook.getDefinedName('MyDefinedName');
+ * console.log(definedName?.getFormulaOrRefString());
+ *
+ * // Update the defined name
+ * if (definedName) {
+ * const newDefinedNameParam = definedName.toBuilder()
+ * .setName('NewDefinedName')
+ * .setRef('Sheet1!$A$2')
+ * .build();
+ * fWorkbook.updateDefinedNameBuilder(newDefinedNameParam);
+ * }
* ```
*/
updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): void {
diff --git a/packages/sheets/src/facade/f-worksheet.ts b/packages/sheets/src/facade/f-worksheet.ts
index 1cdcef7c53..177120cdd5 100644
--- a/packages/sheets/src/facade/f-worksheet.ts
+++ b/packages/sheets/src/facade/f-worksheet.ts
@@ -2349,7 +2349,7 @@ export class FWorksheet extends FBaseInitialable {
* ```ts
* // The code below inserts a defined name
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
- * fWorksheet.insertDefinedName('MyDefinedName', 'Sheet1!A1');
+ * fWorksheet.insertDefinedName('MyDefinedName', 'Sheet1!$A$1');
* ```
*/
insertDefinedName(name: string, formulaOrRefString: string): void {
@@ -2367,7 +2367,7 @@ export class FWorksheet extends FBaseInitialable {
* // The code below gets all the defined names in the worksheet
* const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
* const definedNames = fWorksheet.getDefinedNames();
- * console.log(definedNames);
+ * console.log(definedNames, definedNames[0]?.getFormulaOrRefString());
* ```
*/
getDefinedNames(): FDefinedName[] {