# 表格

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

#### Package metadata

```json
{
  "mobile": true,
  "plugins": [
    {
      "client": "@univerjs-pro/docs-table",
      "facade": "@univerjs-pro/docs-table/facade"
    },
    {
      "client": "@univerjs-pro/docs-table-ui",
      "locale": "@univerjs-pro/docs-table-ui/locale/zh-TW",
      "style": "@univerjs-pro/docs-table-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

增強表格功能為 Univer Docs 提供了豐富的表格編輯能力，包括儲存格樣式、邊框自訂、行列操作和資料填充。

## 介紹

在 Univer Docs 中，增強表格使您能夠：

* **以程式方式插入表格**：建立指定尺寸的表格。
* **操作結構**：新增、刪除和移動行列。
* **樣式儲存格**：套用邊框、背景和文字格式。
* **合併和拆分儲存格**：組合儲存格以實現複雜版面配置。

## 外掛模式

### 安裝

#### npm

```bash
npm install @univerjs-pro/docs-table @univerjs-pro/docs-table-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/docs-table @univerjs-pro/docs-table-ui
```

#### yarn

```bash
yarn add @univerjs-pro/docs-table @univerjs-pro/docs-table-ui
```

#### bun

```bash
bun add @univerjs-pro/docs-table @univerjs-pro/docs-table-ui
```

### 使用

```typescript
import { UniverDocsTablePlugin } from '@univerjs-pro/docs-table' // [!code ++]
import { UniverDocsTableUIPlugin } from '@univerjs-pro/docs-table-ui' // [!code ++]
import DocsTableUIZhTW from '@univerjs-pro/docs-table-ui/locale/zh-TW' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import '@univerjs-pro/docs-table-ui/lib/index.css' // [!code ++]

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

univer.registerPlugin(UniverDocsTablePlugin) // [!code ++]
univer.registerPlugin(UniverDocsTableUIPlugin) // [!code ++]
```

如果您擁有 Univer 商業授權，請參閱[在用戶端使用授權](https://docs.univer.ai/zh-TW/server/license.md#in-plugin-mode)進行配置。

## 行動裝置支援

先設定[行動版編輯器](https://docs.univer.ai/zh-TW/guides/docs/getting-started/installation.md#mobile-support)。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在**開啟文件前**完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

| 套件                            | 桌面版註冊                     | 行動版註冊                           |
| ----------------------------- | ------------------------- | ------------------------------- |
| `@univerjs-pro/docs-table-ui` | `UniverDocsTableUIPlugin` | `UniverDocsTableMobileUIPlugin` |

## Facade API

使用 API 前請確保已匯入 facade：

```typescript
import '@univerjs-pro/docs-table/facade'
```

### 插入表格

```typescript
const doc = univerAPI.getActiveDocument()
const table = doc?.insertTable(3, 4, { tableId: 'my-table' })
table?.setCellText(0, 0, 'Name')
```

### 從資料插入表格

```typescript
const doc = univerAPI.getActiveDocument()
doc?.insertTableFromData([
  ['Name', 'Status'],
  ['Facade', 'Ready'],
], { headerRowCount: 1 })
```

### 取得所有表格

```typescript
const doc = univerAPI.getActiveDocument()
const tables = doc?.getTables() ?? []
```

### 刪除表格

```typescript
const doc = univerAPI.getActiveDocument()
doc?.deleteTable('my-table')
```

## 表格框線

選取表格或其中的儲存格後，可在表格情境索引標籤中使用框線選擇器。它提供全部、外側、內部、單側與無框線預設，並可調整框線色彩、寬度和線條樣式。這些控制項由 `UniverDocsTableUIPlugin` 提供。

## 編輯、復原與協同

表格 Facade 的設定方法和結構編輯透過文件命令執行，參與復原、重做和協同。`setTableStyle()` 將背景與框線修改合併為一筆歷史。`setColumnType()` 同樣支援復原與同步，欄類型隨欄移動。`setCellText()` 取代整個儲存格值，並行取代按原子值衝突規則處理，一般逐字編輯仍使用文字 OT。鎖定內容控制項拒絕的儲存格編輯傳回 `false`，且不消耗復原/重做歷史。