# 정의된 이름

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

정의된 이름은 셀, 셀 범위 또는 수식에 사용자 지정 이름을 할당하는 기능입니다. 이름을 지정하면 데이터를 더 직관적으로 참조하고 수식을 간소화할 수 있으며, 워크시트의 가독성과 유지보수성, 전문성을 높일 수 있습니다.

* **수식 가독성 향상**: 정의된 이름을 사용하면 수식을 더 쉽게 이해할 수 있습니다. 예를 들어 `A1 + A2 + A3` 대신 `Amount`를 사용하면 수식의 의미가 더 명확해집니다.
* **복잡한 참조 간소화**: 여러 셀이나 복잡한 범위를 참조할 때 정의된 이름으로 참조를 간소화할 수 있습니다. 예를 들어 `A1:A10`을 `SalesData`로 정의하고 수식에서 `SalesData`를 직접 사용할 수 있습니다.
* **데이터 영역의 통합 관리 지원**: 정의된 이름을 사용하면 데이터 영역을 더 효율적으로 관리할 수 있습니다. 데이터 범위가 변경되어도 모든 수식을 하나씩 수정할 필요 없이 정의된 이름의 참조만 업데이트하면 됩니다.

## 사용법

이름 관리자 진입점은 시트 왼쪽 위 이름 상자 옆에 있습니다. 여기서 정의된 모든 이름의 목록을 확인하고 이름 관리자에 접근할 수 있습니다. 이름 관리자에서는 정의된 이름을 확인하고 편집하거나 삭제할 수 있습니다.



수식에서 정의된 이름을 사용할 때는 이름을 그대로 입력하면 됩니다. 예를 들어 `TotalSales`라는 이름을 정의했다면 수식에서 `=TotalSales`를 사용하여 해당 범위를 참조할 수 있습니다.

## 참고 사항

* **이름의 고유성**: 정의된 이름은 동일한 워크시트 내에서 고유해야 하며 다른 이름이나 기본 제공 함수와 충돌할 수 없습니다.
* **이름의 유효성**: 정의된 이름은 숫자로 시작할 수 없으며 공백이나 특수 문자(예: `!`, `@`, `#` 등)를 포함할 수 없습니다. 입력한 이름이 규칙에 맞지 않으면 시스템에 오류가 표시됩니다.
* **정의된 이름 업데이트**: 기존 정의된 이름을 수정하려면 "이름 정의" 편집 패널을 다시 열고 수정할 이름을 선택하여 편집합니다. 변경한 후 "확인"을 클릭하여 저장합니다.
* **정의된 이름 삭제**: 정의된 이름이 더 이상 필요하지 않으면 "이름 정의" 편집 패널에서 해당 이름을 선택하고 "삭제" 버튼을 클릭합니다. 삭제 후에는 관련 수식이 더 이상 유효하지 않습니다.
* **워크시트 간 사용**: 정의된 이름은 동일한 통합 문서의 여러 워크시트에서 사용할 수 있지만 이름의 고유성에 주의해야 합니다. 서로 다른 워크시트에 같은 이름을 정의하면 참조가 혼동될 수 있습니다.
* **명명 규칙**: 다른 사용자가 쉽게 이해하고 유지보수할 수 있도록 의미 있는 이름을 사용하고 지나치게 짧거나 모호한 이름은 피하는 것이 좋습니다.
* **수식 디버깅**: 정의된 이름을 사용할 때 문제가 발생하면 이름이 올바른지, 참조 범위가 정확한지, 이름 충돌이 있는지 확인할 수 있습니다.
* **사용 범위**: 정의된 이름은 통합 문서 수준 또는 워크시트 수준으로 설정할 수 있습니다. 통합 문서 수준 이름은 통합 문서 전체에서 사용할 수 있고, 워크시트 수준 이름은 특정 워크시트 내에서만 사용할 수 있습니다.

## Facade API

전체 Facade API 타입 정의는 [Facade API](https://docs.univer.ai/ko-KR/reference/facade.md)에서 확인할 수 있습니다.

### 정의된 이름 만들기

`FWorkbook.newDefinedNameBuilder()`는 정의된 이름 빌더를 만들고 `FDefinedNameBuilder` 인스턴스를 반환합니다. 메서드 체이닝을 사용하여 정의된 이름을 만드는 데 필요한 `ISetDefinedNameMutationParam` 객체를 생성할 수 있습니다.

다음은 [`FDefinedNameBuilder`](https://docs.univer.ai/ko-KR/reference/facade/defined-name-builder.md)의 일부 멤버 메서드입니다.

| 메서드                 | 설명                                 |
| ------------------- | ---------------------------------- |
| build               | 정의된 이름 객체를 빌드합니다                   |
| setName             | 정의된 이름을 설정합니다                      |
| setFormula          | 정의된 이름의 수식을 설정합니다                  |
| setRef              | 정의된 이름의 참조 범위를 설정합니다               |
| setComment          | 정의된 이름의 주석을 설정합니다                  |
| setScopeToWorksheet | 정의된 이름을 특정 워크시트에서 사용할 수 있도록 설정합니다  |
| setScopeToWorkbook  | 정의된 이름을 통합 문서 전체에서 사용할 수 있도록 설정합니다 |

[`FWorkbook.insertDefinedNameBuilder()`](https://docs.univer.ai/ko-KR/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/ko-KR/reference/facade/workbook.md#insertdefinedname) 메서드를 사용하여 정의된 이름을 빠르게 만들 수 있습니다.

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

기타 메서드:

* [`FWorksheet.insertDefinedName()`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md#insertdefinedname): 특정 워크시트에서 사용할 수 있는 정의된 이름을 만듭니다.

### 정의된 이름 가져오기

[`FWorkbook.getDefinedName()`](https://docs.univer.ai/ko-KR/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/ko-KR/reference/facade/workbook.md#getdefinednames) 메서드는 통합 문서에 정의된 모든 이름을 `FDefinedName[]` 배열로 반환합니다.
* [`FWorksheet.getDefinedNames()`](https://docs.univer.ai/ko-KR/reference/facade/worksheet.md#getdefinednames) 메서드는 이 워크시트에서 사용할 수 있는 모든 정의된 이름을 `FDefinedName[]` 배열로 반환합니다.

### 정의된 이름 수정하기

[`FWorkbook.updateDefinedNameBuilder()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#updatedefinednamebuilder) 메서드를 사용하여 통합 문서의 정의된 이름을 수정할 수 있습니다.

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

// Modify the defined name
if (definedName) {
  const newDefinedNameParam = definedName.toBuilder()
    .setName('NewDefinedName')
    .setRef('Sheet1!$A$2')
    .build()
  fWorkbook.updateDefinedNameBuilder(newDefinedNameParam)
}
```

[`FDefinedName`](https://docs.univer.ai/ko-KR/reference/facade/defined-name.md) 인스턴스를 사용하여 정의된 이름의 구성을 직접 수정할 수도 있습니다.

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

// Modify the defined name
if (definedName) {
  definedName.setName('NewDefinedName')
  definedName.setRef('Sheet1!$A$2')
}
```

### 정의된 이름 삭제하기

[`FWorkbook.deleteDefinedName()`](https://docs.univer.ai/ko-KR/reference/facade/workbook.md#deletedefinedname) 메서드를 사용하여 통합 문서의 정의된 이름을 삭제할 수 있습니다.

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

반환된 [`FDefinedName`](https://docs.univer.ai/ko-KR/reference/facade/defined-name.md) 인스턴스를 사용하여 정의된 이름을 직접 삭제할 수도 있습니다.

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

// Delete the defined name
if (definedName) {
  definedName.delete()
}
```