# 표

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-table",
      "locale": "@univerjs/preset-sheets-table/locales/ko-KR",
      "style": "@univerjs/preset-sheets-table/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/sheets-table",
      "facade": "@univerjs/sheets-table/facade",
      "locale": "@univerjs/sheets-table/locale/ko-KR"
    },
    {
      "client": "@univerjs/sheets-table-ui",
      "locale": "@univerjs/sheets-table-ui/locale/ko-KR",
      "style": "@univerjs/sheets-table-ui/lib/index.css"
    }
  ],
  "server": false
}
```

표 기능을 사용하면 스프레드시트에서 표를 만들고 관리하여 데이터를 더 체계적으로 구성하고 표현할 수 있습니다. 다양한 표 스타일과 작업을 지원하므로 정보를 빠르게 처리하고 분석할 수 있습니다.

## 플러그인 모드

### 설치

#### npm

```bash
npm install @univerjs/sheets-table @univerjs/sheets-table-ui
```

#### pnpm

```bash
pnpm add @univerjs/sheets-table @univerjs/sheets-table-ui
```

#### yarn

```bash
yarn add @univerjs/sheets-table @univerjs/sheets-table-ui
```

#### bun

```bash
bun add @univerjs/sheets-table @univerjs/sheets-table-ui
```

### 사용법

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetsTablePlugin } from '@univerjs/sheets-table' // [!code ++]
import { UniverSheetsTableUIPlugin } from '@univerjs/sheets-table-ui' // [!code ++]
import SheetsTableUIEnUS from '@univerjs/sheets-table-ui/locale/en-US' // [!code ++]
import '@univerjs/sheets-table-ui/lib/index.css' // [!code ++]
import '@univerjs/sheets-table/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      SheetsTableUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsTablePlugin) // [!code ++]
univer.registerPlugin(UniverSheetsTableUIPlugin) // [!code ++]
```

## 모바일 지원

먼저 [모바일 에디터](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/installation.md#mobile-support)를 구성하세요. 이 페이지의 플러그인 모드 초기화 코드에서 아래 데스크톱 등록을 같은 패키지의 모바일 버전으로 바꾸고 **문서를 열기 전에** 완료하세요. 모델 플러그인, 스타일, 언어 파일과 Facade 가져오기는 유지하며 두 버전을 동시에 등록하지 마세요.

| 패키지                         | 데스크톱 등록                     | 모바일 등록                            |
| --------------------------- | --------------------------- | --------------------------------- |
| `@univerjs/sheets-table-ui` | `UniverSheetsTableUIPlugin` | `UniverSheetsTableMobileUIPlugin` |

## 프리셋 모드

### 설치

#### npm

```bash
npm install @univerjs/preset-sheets-table
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-table
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-table
```

#### bun

```bash
bun add @univerjs/preset-sheets-table
```

### 사용법

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsTablePreset } from '@univerjs/preset-sheets-table' // [!code ++]
import UniverPresetSheetsTableEnUS from '@univerjs/preset-sheets-table/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-table/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsTableEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsTablePreset(), // [!code ++]
  ],
})
```

## Facade API

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

### 가져오기

> [!INFO: 플러그인 모드 참고]
> Facade 패키지를 직접 가져와야 하는 것은 플러그인 모드뿐입니다. 프리셋 모드에는 해당 Facade 패키지가 이미 포함되어 있으므로 별도로 가져올 필요가 없습니다.

```typescript
import '@univerjs/sheets-table/facade'
```

### 표 삽입

* `FWorkbook.addTable`: 통합 문서에서 지정한 워크시트에 표 삽입
* `FWorksheet.addTable`: 워크시트에 표 삽입

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
    columns: [
      { id: 'col-1', displayName: 'Column 1' },
    ],
    filters: [
      {
        filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
        filterInfo: {
          conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
          compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
          expectedValue: 2,
        },
      },
    ],
  },
)

if (success) {
  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

### 표 가져오기

* `FWorkbook.getTableList`: 통합 문서의 모든 표 목록 가져오기
* `FWorksheet.getSubTableInfos`: 워크시트의 모든 표 목록 가져오기

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const tables = fWorkbook.getTableList()
console.log('debugger tables', tables)
```

* `FWorkbook.getTableInfo`: 표 ID로 표 정보 가져오기
* `FWorkbook.getTableInfoByName`: 표 이름으로 표 정보 가져오기

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
  },
)

if (success) {
  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

* `FWorksheet.getTableByCell`: 셀 위치로 표 정보 가져오기

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

const cellB2 = fWorksheet.getRange('B2')
const row = cellB2.getRow()
const column = cellB2.getColumn()
console.log('debugger tableInfo', fWorksheet.getTableByCell(row, column))

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
  },
)
console.log('debugger tableInfo2', fWorksheet.getTableByCell(row, column))
```

### 필터 설정

* `FWorkbook.setTableFilter`: 통합 문서의 표에 필터 설정
* `FWorksheet.setTableFilter`: 워크시트의 표에 필터 설정

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
  },
)

if (success) {
  // Set the filter for the second column
  await fWorksheet.setTableFilter('id-1', 1, {
    filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
    filterInfo: {
      conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
      compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
      expectedValue: 10,
    },
  })

  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

* `FWorksheet.resetFilter`: 워크시트 표의 필터 재설정

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
  },
)

if (success) {
  // Set the filter for the second column
  await fWorksheet.setTableFilter('id-1', 1, {
    filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
    filterInfo: {
      conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
      compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
      expectedValue: 10,
    },
  })

  // Reset the filter for the second column after 3 seconds
  setTimeout(async () => {
    await fWorksheet.resetFilter('id-1', 1)
  }, 3000)

  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

### 표 수정/삭제

* `FWorkbook.removeTable`: 통합 문서에서 표 제거
* `FWorksheet.removeTable`: 워크시트에서 표 제거

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const tableInfo = fWorkbook.getTableInfo('id-1')
console.log('debugger tableInfo', tableInfo)

if (tableInfo) {
  // Remove the table with the specified id
  await fWorksheet.removeTable('id-1')
}
```

* `FWorksheet.setTableRange`: 워크시트의 표 범위 업데이트

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
  },
)

if (success) {
  // Update the table range to B2:F21 after 3 seconds
  setTimeout(async () => {
    const newRange = fWorksheet.getRange('B2:F21')
    await fWorksheet.setTableRange('id-1', newRange.getRange())

    const tableInfo = fWorkbook.getTableInfo('id-1')
    console.log('debugger tableInfo', tableInfo)
  }, 3000)
}
```

* `FWorksheet.setTableName`: 워크시트의 표 이름 업데이트

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
  },
)

if (success) {
  // Update the table name after 3 seconds
  setTimeout(async () => {
    await fWorksheet.setTableName('id-1', 'new-name')

    const tableInfo = fWorkbook.getTableInfo('id-1')
    console.log('debugger tableInfo', tableInfo)
  }, 3000)
}
```

### 표 테마 추가

* `FWorksheet.addTableTheme`: 워크시트의 표에 테마 추가

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Insert a table in the range B2:F11
const fRange = fWorksheet.getRange('B2:F11')
const success = await fWorksheet.addTable(
  'name-1',
  fRange.getRange(),
  'id-1',
  {
    tableStyleId: 'table-default-4',
  },
)

if (success) {
  await fWorksheet.addTableTheme('id-1', {
    name: 'table-custom-1',
    headerRowStyle: {
      bg: {
        rgb: '#145f82',
      },
    },
    firstRowStyle: {
      bg: {
        rgb: '#c0e4f5',
      },
    },
  })

  const tableInfo = fWorkbook.getTableInfo('id-1')
  console.log('debugger tableInfo', tableInfo)
}
```

## 셀과 함께 테이블 이동

테이블 전체를 포함하는 셀 범위를 이동하면 테이블도 함께 이동합니다. 같은 시트 안이나 같은 통합 문서의 다른 시트로 이동할 수 있으며, 머리글과 모든 데이터 행을 포함해야 합니다. ID, 이름, 스타일, 열 메타데이터와 필터가 유지되고 구조화된 참조도 이동한 테이블을 따릅니다. 대상 범위는 편집 가능하고 시트 경계 안에 있어야 하며 다른 테이블과 겹칠 수 없습니다. 실행 취소와 다시 실행은 셀과 테이블 메타데이터를 함께 복원합니다.