# 셀 데이터 구조

- Human documentation: [https://docs.univer.ai/ko-KR/guides/sheets/model/cell-data](https://docs.univer.ai/ko-KR/guides/sheets/model/cell-data)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/sheets/model/cell-data.md](https://docs.univer.ai/ko-KR/guides/sheets/model/cell-data.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [sheets/model/cell-data.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/model/cell-data.ko-KR.mdx)

---

## 셀 위치

Univer Sheets의 셀 데이터는 [IWorksheetData](https://docs.univer.ai/ko-KR/reference/types/worksheet-data.md) 객체의 [cellData](https://docs.univer.ai/ko-KR/reference/types/worksheet-data.md#celldata) 필드에 저장되며, 이 필드에는 셀 값, 스타일, 타입 등 셀에 관한 모든 정보가 포함됩니다.

cellData의 구조는 다음과 같습니다.

```typescript
interface IWorksheetData {
  cellData: {
    // first row
    0: {
      // first column
      0: { v: 'A1' }
      // second column
      1: { v: 'B1' }
    }
    // second row
    1: {
      // first column
      0: { v: 'A2' }
      // second column
      1: { v: 'B2' }
    }
  }
}
```

## 셀 데이터

전체 셀 정보는 다음과 같습니다.

| 속성     | 설명                      |
| ------ | ----------------------- |
| v      | 셀 원본 값                  |
| s      | 셀 스타일 ID 또는 스타일 객체      |
| t      | 셀 타입                    |
| p      | 리치 텍스트이자 📝 Univer Docs |
| f      | 수식                      |
| si     | 수식 ID                   |
| custom | 사용자 지정 필드               |

[ICellData](https://docs.univer.ai/ko-KR/reference/types/cell-data.md)의 각 필드에 대한 타입 정보를 확인하세요.

### 셀 원본 값

`cellData.v`는 셀의 원본 값을 저장하며 문자열 또는 숫자일 수 있습니다. 수식이 있는 셀에서는 `v`에 수식의 계산 결과가 저장됩니다.

다음은 서로 다른 두 가지 셀 값의 예입니다.

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: { v: 'A1' }
      1: { v: 1 }
    }
  }
}
```

### 셀 스타일

`cellData.s`는 셀의 스타일 ID 또는 스타일 객체를 저장합니다.

`s`가 문자열이면 스타일 ID를 나타냅니다. Univer Sheets는 스타일의 참조 최적화를 지원합니다. 반복되는 스타일 객체는 IWorkbookData의 [styles](https://docs.univer.ai/ko-KR/reference/types/workbook-data.md#styles) 필드에 저장됩니다. 이 필드는 Map 구조이며 각 키는 스타일 ID, 값은 스타일 객체입니다.

> [!WARNING]
> 투명도가 있는 색상 값(예: rgba)은 사용하지 마세요. 그렇지 않으면 편집 상태가 활성화될 때 배경에 아래쪽 셀의 내용이 비칠 수 있습니다.

```typescript
interface IWorkbookData {
  styles: {
    random_style_id_1: {
      fs: 12
      bg: {
        rgb: '#ff0000'
      }
    }
  }
}
```

그런 다음 셀 스타일에 ID를 저장하여 스타일을 재사용할 수 있습니다.

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: {
        v: 'A1'
        s: 'random_style_id_1'
      }
      1: {
        v: 'B1'
        s: 'random_style_id_1'
      }
    }
  }
}
```

`s`가 객체이면 완전한 셀 스타일 객체인 [IStyleData](https://docs.univer.ai/ko-KR/reference/types/style-data.md)를 나타냅니다.

전체 스타일 필드는 다음과 같습니다.

| 속성 | 설명            |
| -- | ------------- |
| ff | 글꼴            |
| fs | 글꼴 크기         |
| it | 기울임꼴          |
| bl | 굵게            |
| ul | 밑줄            |
| st | 취소선           |
| ol | 윗줄            |
| bg | 배경색           |
| bd | 테두리           |
| cl | 글꼴 색상         |
| va | 위 첨자 또는 아래 첨자 |
| tr | 텍스트 회전        |
| ht | 가로 맞춤         |
| vt | 세로 맞춤         |
| tb | 넘치는 텍스트 처리    |
| pd | 안쪽 여백         |
| n  | 숫자 형식         |

[IStyleData](https://docs.univer.ai/ko-KR/reference/types/style-data.md)의 각 필드에 대한 타입 정보를 확인할 수 있습니다.

#### 글꼴

`ff`는 글꼴 이름을 나타내는 문자열입니다.

```typescript
interface IStyleData {
  ff: 'Arial' // Font name is Arial
}
```

#### 글꼴 크기

`fs`는 숫자이며 단위는 **pt**입니다.

```typescript
interface IStyleData {
  fs: 12 // Font size is 12 pt
}
```

#### 기울임꼴

`it`는 불리언 숫자로, `0`은 기울임꼴이 아님을, `1`은 기울임꼴임을 의미합니다.

```typescript
interface IStyleData {
  it: 1 // Italic
}
```

#### 굵게

`bl`은 불리언 숫자로, `0`은 굵게가 아님을, `1`은 굵게임을 의미합니다.

```typescript
interface IStyleData {
  bl: 1 // Bold
}
```

#### 밑줄

`ul`은 밑줄 스타일을 나타내는 객체입니다.

```typescript
interface IStyleData {
  ul: {
    s: 1 // Whether to show underline
    c: 0 // Whether the color follows the font color. When `c` is 1 (TRUE), cl does not work. The default value is 1
    cl: { // Underline color
      rgb: '#ff0000'
    }
    t: 0 // Underline type
  }
}
```

#### 취소선

`st`는 취소선 스타일을 나타내는 객체입니다.

```typescript
interface IStyleData {
  st: {
    s: 1 // Whether to show strikethrough
    c: 0 // Whether the color follows the font color. When `c` is 1 (TRUE), cl does not work. The default value is 1
    cl: { // Strikethrough color
      rgb: '#ff0000'
    }
    t: 0 // Strikethrough type
  }
}
```

#### 윗줄

`ol`은 윗줄 스타일을 나타내는 객체입니다.

```typescript
interface IStyleData {
  ol: {
    s: 1 // Whether to show overline
    c: 0 // Whether the color follows the font color. When `c` is 1 (TRUE), cl does not work. The default value is 1
    cl: { // Overline color
      rgb: '#ff0000'
    }
    t: 0 // Overline type
  }
}
```

#### 배경색

`bg`는 배경색을 나타내는 객체입니다.

```typescript
interface IStyleData {
  bg: {
    rgb: '#ff0000' // Background color is red
  }
}
```

#### 테두리

`bd`는 테두리 스타일을 나타내는 객체입니다.

```typescript
interface IStyleData {
  bd: {
    // Top border
    t: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
    // Bottom border
    b: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
    // Left border
    l: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
    // Right border
    r: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
  }
}
```

#### 글꼴 색상

`cl`은 글꼴 색상을 나타내는 객체입니다.

```typescript
interface IStyleData {
  cl: {
    rgb: '#ff0000' // Font color is red
  }
}
```

#### 위 첨자 또는 아래 첨자

`va`는 열거형 숫자로, `1`은 보통, `2`는 아래 첨자, `3`은 위 첨자를 의미합니다.

```typescript
interface IStyleData {
  va: 2 // Subscript
}
```

#### 텍스트 회전

`tr`은 텍스트 회전을 나타내는 객체입니다.

```typescript
interface IStyleData {
  tr: {
    a: 0 // Text rotation angle
    v: 0 // Whether it is vertical. 1 means vertical, 0 means horizontal. The default value is 0. When v is 1, a is invalid
  }
}
```

#### 가로 맞춤

`ht`는 열거형 숫자로, `1`은 왼쪽 맞춤, `2`는 가운데 맞춤, `3`은 오른쪽 맞춤을 의미합니다.

```typescript
interface IStyleData {
  ht: 1 // Left alignment
}
```

#### 세로 맞춤

`vt`는 열거형 숫자로, `1`은 위쪽 맞춤, `2`는 가운데 맞춤, `3`은 아래쪽 맞춤을 의미합니다.

```typescript
interface IStyleData {
  vt: 1 // Top alignment
}
```

#### 넘치는 텍스트 처리

`tb`는 열거형 숫자로, `1`은 넘침, `2`는 자르기, `3`은 줄 바꿈을 의미합니다.

```typescript
interface IStyleData {
  tb: 1 // Overflow
}
```

#### 안쪽 여백

`pd`는 안쪽 여백을 나타내는 객체입니다.

```typescript
interface IStyleData {
  pd: {
    t: 0 // Top padding
    b: 0 // Bottom paddingAdd commentMore actions
    l: 0 // Left padding
    r: 0 // Right padding
  }
}
```

#### 숫자 형식

`n`은 객체이며 `pattern` 필드는 숫자 형식을 나타냅니다. 숫자 형식은 문자열입니다. 자세한 내용은 [여기](https://support.microsoft.com/en-us/office/number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68)를 참고하세요.

`n`이 `null`이거나 `pattern`이 `null`이면 일반 형식을 나타냅니다.

```typescript
import type { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/core'

interface IStyleData {
  n: {
    pattern: DEFAULT_TEXT_FORMAT_EXCEL // text format
  }
}
```

[0으로 시작하는 숫자나 날짜 형식으로 변환될 수 있는 숫자를 입력할 때 셀이 기본적으로 변환되지 않게 하고 싶습니다](https://docs.univer.ai/ko-KR/guides/sheets/features/core/numfmt.md#usage)

### 셀 타입

`cellData.t`는 셀의 타입을 나타내는 열거형 [CellValueType](https://docs.univer.ai/ko-KR/reference/enums/cell-value-type.md)입니다. `1`은 문자열, `2`는 숫자, `3`은 불리언, `4`는 텍스트 강제 적용을 의미합니다. 설정하지 않으면 Univer가 자동으로 인식합니다.

셀이 불리언 타입이면 `cellData.v` 값은 `0` 또는 `1`로 저장됩니다. `0`은 false, `1`은 true를 의미합니다.

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: {
        v: 'A1'
        t: 1 // String
      }
      1: {
        v: 1
        t: 2 // Number
      }
      2: {
        v: 1 // TRUE
        t: 3 // Boolean
      }
      3: {
        v: '012.0'
        t: 4 // Force text
      }
    }
  }
}
```

`disableForceStringAlert` 및 `disableForceStringMark`를 구성하여 텍스트 강제 적용 알림과 표시의 활성화 여부를 제어할 수 있습니다. 구성 위치는 다음을 참고하세요.

* [프리셋 모드](https://docs.univer.ai/ko-KR/guides/sheets/features/core.md#univerjspreset-sheets-core)
* [플러그인 모드](https://docs.univer.ai/ko-KR/guides/sheets/features/core.md#univerjssheets-ui)

### 리치 텍스트

`cellData.p`는 리치 텍스트를 나타내는 객체이자 Univer Doc입니다. [IDocumentData](https://docs.univer.ai/ko-KR/reference/types/document-data.md)에서 자세히 알아보세요.

> [!NOTE]
> 셀의 `p`와 `v`를 모두 설정하면 `p`의 내용만 표시됩니다.

`cellData.p.body.dataStream`은 리치 텍스트의 내용입니다.

### 수식

`cellData.f`는 수식을 나타내는 문자열입니다.

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: {
        f: '=SUM(A1:B1)' // function SUM
      }
    }
  }
}
```

### 수식 ID

`cellData.si`는 수식 ID를 나타내는 문자열입니다. Univer Sheets는 수식의 참조 최적화를 지원합니다. 현재 수식이 셀에서 `si`와 연결되면 다른 셀은 `si`를 통해 현재 수식을 참조할 수 있습니다. `si`가 있는 셀의 위치는 참조 셀의 오른쪽 아래에 있어야 합니다. 그렇지 않으면 XLSX로 내보낼 때 오류가 발생합니다.

실제 수식은 Facade API `range.getFormulas()`를 통해 가져올 수 있습니다. `si`에 해당하는 수식 `f`를 가져온 다음, 현재 셀 위치에서 참조 위치까지의 오프셋을 기준으로 실제 수식을 계산합니다.

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: {
        f: '=SUM(A1:B1)' // Sum formula
        si: 'random_formula_id_1' // ID of the current formula
      }
      1: {
        si: 'random_formula_id_1' // Take the formula corresponding to this ID during calculation
      }
    }
  }
}
```

### 사용자 지정 필드

`cellData.custom`은 사용자 지정 필드를 나타내는 객체입니다. JSON 형식을 준수하는 모든 데이터를 넣어 추가 정보를 원하는 방식으로 저장할 수 있습니다.

`custom` 데이터를 업데이트하면 기존 `custom` 데이터를 덮어씁니다. 데이터를 업데이트할 때 기존 `custom` 데이터를 유지해야 한다면 먼저 `custom` 데이터를 가져와 새 데이터에 병합한 후 업데이트하세요.

> [!WARNING]
> `custom` 필드는 일부 특수한 시나리오에만 적합하며, 이 필드에 저장된 데이터는 사용자의 어떤 작업으로도 덮어쓰거나 삭제될 수 있습니다. 주의해서 사용하세요.

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: {
        custom: {
          key: 'value'
        }
      }
    }
  }
}
```