# 定義名稱

- Human documentation: [https://docs.univer.ai/zh-TW/guides/sheets/features/core/defined-names](https://docs.univer.ai/zh-TW/guides/sheets/features/core/defined-names)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/sheets/features/core/defined-names.md](https://docs.univer.ai/zh-TW/guides/sheets/features/core/defined-names.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/features/core/defined-names.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/defined-names.zh-TW.mdx)

---

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

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

## 使用方法

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



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

## 注意事項

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

## Facade API

完整 Facade API 型別定義，請檢視 [Facade API](https://docs.univer.ai/zh-TW/reference/facade/univer.md)

### 建立定義名稱

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

以下是 [`FDefinedNameBuilder`](https://docs.univer.ai/zh-TW/reference/facade/defined-name-builder.md) 上的一些成員方法：

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

透過 [`FWorkbook.insertDefinedNameBuilder()`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#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()`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#insertdefinedname) 方法快速建立定義名稱。

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

其他方法：

* [`FWorksheet.insertDefinedName()`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertdefinedname)：建立工作表可用的定義名稱。

### 獲取定義名稱

[`FWorkbook.getDefinedName()`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#getdefinedname) 方法可以獲取工作簿中已定義的名稱，返回一個 `FDefinedName` 例項。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())

if (definedName) {
  definedName.setName('NewDefinedName')
}
```

其他方法：

* [`FWorkbook.getDefinedNames()`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#getdefinednames) 方法可以獲取工作簿中所有已定義的名稱，返回一個 `FDefinedName[]` 陣列。
* [`FWorksheet.getDefinedNames()`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#getdefinednames) 方法可以獲取所有此工作表可用的定義名稱，返回一個 `FDefinedName[]` 陣列。

### 修改定義名稱

`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`](https://docs.univer.ai/zh-TW/reference/facade/defined-name.md) 例項直接修改定義名稱配置。

```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()`](https://docs.univer.ai/zh-TW/reference/facade/workbook.md#deletedefinedname) 方法可以刪除工作簿中已定義的名稱。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.deleteDefinedName('MyDefinedName')
```

也可以透過返回的 [`FDefinedName`](https://docs.univer.ai/zh-TW/reference/facade/defined-name.md) 例項直接刪除定義名稱。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())

// 刪除定義名稱
if (definedName) {
  definedName.delete()
}
```