Web SDK

定義名稱

定義名稱是用於為單元格、單元格區域或公式賦予一個自訂名稱的功能。透過命名，使用者可以更直觀地引用資料，簡化公式，提高工作表的可讀性、可維護性和專業性。

  • 提高公式可讀性：使用定義名稱可以讓公式更易於理解。例如，使用 銷售總額 代替 A1 + A2 + A3，使得公式的含義更加明確。
  • 簡化複雜引用：當需要引用多個單元格或複雜的範圍時，定義名稱可以簡化這些引用。例如，可以將 A1:A10 定義為 銷售資料，在公式中直接使用 銷售資料 來代替。
  • 便於統一管理資料區域：定義名稱可以幫助使用者更好地管理資料區域。當資料範圍發生變化時，只需更新定義名稱的引用即可，無需逐一修改所有公式。

使用方法

名稱管理器入口在 Sheet 左上角名稱框旁邊的下拉箭頭，點選後可以看到所有已定義的名稱列表和名稱管理器的入口。透過名稱管理器，使用者可以檢視、編輯和刪除已定義的名稱。

在公式中使用定義名稱時，只需直接輸入名稱即可。例如，如果你定義了一個名稱為 銷售總額，可以在公式中直接使用 =銷售總額 來引用該範圍。

注意事項

  • 名稱的唯一性：在同一個工作表中，定義名稱必須是唯一的，不能與其他名稱或內建函式衝突。
  • 名稱的有效性：定義名稱不能以數字開頭，不能包含空格或特殊字元（如 !、@、# 等）。如果輸入的名稱不符合規則，系統會提示錯誤。
  • 更新定義名稱：如果需要修改已定義的名稱，可以再次開啟“定義名稱”編輯面板，選擇要修改的名稱進行編輯。修改後，點選“確定”儲存更改。
  • 刪除定義名稱：如果不再需要某個定義名稱，可以在“定義名稱”編輯面板中選擇該名稱，然後點選“刪除”按鈕進行刪除。刪除後，相關的公式將不再有效。
  • 跨工作表使用：定義名稱可以在同一個工作簿的不同工作表中使用，但需要注意名稱的唯一性。如果在不同工作表中定義了相同的名稱，可能會導致引用混淆。
  • 命名規範：建議使用有意義的名稱，避免使用過於簡短或模糊的名稱，以便於其他使用者理解和維護。
  • 除錯公式：如果在使用定義名稱時遇到問題，可以檢查名稱是否正確，引用範圍是否準確，以及是否存在名稱衝突等問題。可以透過“名稱管理器”面板檢視所有已定義的名稱及其引用範圍。
  • 使用範圍：定義名稱可以設定為工作簿級別或工作表級別。工作簿級別的名稱可以在整個工作簿中使用，而工作表級別的名稱只能在特定的工作表中使用。

Facade API

完整 Facade API 型別定義，請檢視 Facade API

建立定義名稱

FWorkbook.newDefinedNameBuilder() 建立一個定義名稱構建器，返回一個 FDefinedNameBuilder 例項，可以透過鏈式呼叫生成 ISetDefinedNameMutationParam 物件用於建立定義名稱。

以下是 FDefinedNameBuilder 上的一些成員方法：

方法描述
build構建定義名稱物件
setName設定定義名稱
setFormula設定定義名稱的公式
setRef設定定義名稱的引用範圍
setComment設定定義名稱的註釋
setScopeToWorksheet設定定義名稱為某個工作表可用
setScopeToWorkbook設定定義名稱為整個工作簿可用

透過 FWorkbook.insertDefinedNameBuilder() 方法可以建立整個工作簿可用的定義名稱。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const definedNameParam = fWorkbook.newDefinedNameBuilder()  .setName('MyDefinedName')  .setRef('Sheet1!$A$1')  .setComment('A reference to A1 cell in Sheet1')  .build()fWorkbook.insertDefinedNameBuilder(definedNameParam)

也可以透過 FWorkbook.insertDefinedName() 方法快速建立定義名稱。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1')

其他方法：

獲取定義名稱

FWorkbook.getDefinedName() 方法可以獲取工作簿中已定義的名稱，返回一個 FDefinedName 例項。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const definedName = fWorkbook.getDefinedName('MyDefinedName')console.log(definedName?.getFormulaOrRefString())if (definedName) {  definedName.setName('NewDefinedName')}

其他方法：

修改定義名稱

FWorkbook.updateDefinedNameBuilder() 方法可以修改工作簿中已定義的名稱。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const definedName = fWorkbook.getDefinedName('MyDefinedName')console.log(definedName?.getFormulaOrRefString())// 更新定義名稱if (definedName) {  const newDefinedNameParam = definedName.toBuilder()    .setName('NewDefinedName')    .setRef('Sheet1!$A$2')    .build()  fWorkbook.updateDefinedNameBuilder(newDefinedNameParam)}

也可以透過返回的 FDefinedName 例項直接修改定義名稱配置。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const definedName = fWorkbook.getDefinedName('MyDefinedName')console.log(definedName?.getFormulaOrRefString())// 更新定義名稱if (definedName) {  definedName.setName('NewDefinedName')  definedName.setRef('Sheet1!$A$2')}

刪除定義名稱

FWorkbook.deleteDefinedName() 方法可以刪除工作簿中已定義的名稱。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()fWorkbook.deleteDefinedName('MyDefinedName')

也可以透過返回的 FDefinedName 例項直接刪除定義名稱。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const definedName = fWorkbook.getDefinedName('MyDefinedName')console.log(definedName?.getFormulaOrRefString())// 刪除定義名稱if (definedName) {  definedName.delete()}

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.