# 表格

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

#### Package metadata

```json
{
  "mobile": true,
  "preset": [
    {
      "client": "@univerjs/preset-sheets-table",
      "locale": "@univerjs/preset-sheets-table/locales/zh-TW",
      "style": "@univerjs/preset-sheets-table/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs/sheets-table",
      "facade": "@univerjs/sheets-table/facade",
      "locale": "@univerjs/sheets-table/locale/zh-TW"
    },
    {
      "client": "@univerjs/sheets-table-ui",
      "locale": "@univerjs/sheets-table-ui/locale/zh-TW",
      "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 SheetsTableUIZhTW from '@univerjs/sheets-table-ui/locale/zh-TW' // [!code ++]

import '@univerjs/sheets-table-ui/lib/index.css' // [!code ++]

import '@univerjs/sheets-table/facade' // [!code ++]

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

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

## 行動裝置支援

先設定[行動版編輯器](https://docs.univer.ai/zh-TW/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 UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'
import { UniverSheetsTablePreset } from '@univerjs/preset-sheets-table' // [!code ++]
import UniverPresetSheetsTableZhTW from '@univerjs/preset-sheets-table/locales/zh-TW' // [!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.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      UniverPresetSheetsCoreZhTW,
      UniverPresetSheetsTableZhTW, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsTablePreset(), // [!code ++]
  ],
})
```

## Facade API

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

### 引入

> [!INFO: 外掛模式提示]
> 僅外掛模式需要手動引入 Facade 套件。預設模式已內建對應的 Facade 套件，無需額外引入。

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

### 插入表格

* `FWorkbook.addTable`：在工作薄指定工作表中插入一個表格
* `FWorksheet.addTable`：在工作表中插入一個表格

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

// 在 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()

// 在 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))

// 在 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()

// 在 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.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()

// 在 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.setTableFilter('id-1', 1, {
    filterType: univerAPI.Enum.TableColumnFilterTypeEnum.condition,
    filterInfo: {
      conditionType: univerAPI.Enum.TableConditionTypeEnum.Number,
      compareType: univerAPI.Enum.TableNumberCompareTypeEnum.GreaterThan,
      expectedValue: 10,
    },
  })

  // 3 秒後重置第二列的過濾器
  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) {
  // 透過指定的 ID 刪除表格
  await fWorksheet.removeTable('id-1')
}
```

* `FWorksheet.setTableRange`：修改工作表中表格的範圍

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

// 在 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) {
  // 3 秒後更新表格範圍
  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()

// 在 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) {
  // 3 秒後更新表格名稱
  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)
}
```

## 隨儲存格範圍移動表格

移動包含完整表格的儲存格範圍時，表格會一起移動，可在同一工作表內或同一活頁簿的不同工作表間移動。選取範圍須包含標題列及所有表格資料列。表格保留識別碼、名稱、樣式、欄中繼資料與篩選條件，結構化參照會跟隨移動後的表格。目標範圍必須可編輯、位於工作表邊界內且不與其他表格重疊。復原與重做會同時還原儲存格及表格中繼資料。