# 行列操作

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

## Facade API

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

### 行 Row

#### 在指定行後插入行

[`insertRowAfter(afterPosition)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertrowafter): 在指定行位置之後插入一行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將在第一行位置後插入一行
sheet.insertRowAfter(0)
```

#### 在指定行前插入行

[`insertRowBefore(beforePosition)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertrowbefore): 在指定行位置之前插入一行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將在第一行位置前插入一行
sheet.insertRowBefore(0)
```

#### 插入多行

[`insertRows(rowIndex, numRows)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertrows): 在工作表中從指定位置開始插入一個或多個連續的空白行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 將所有行向下移動三位
sheet.insertRows(0, 3)
```

#### 在指定行後插入多行

[`insertRowsAfter(afterPosition, howMany)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertrowsafter): 在指定行位置之後插入若干行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將在第一行後插入五行
sheet.insertRowsAfter(0, 5)
```

#### 在指定行前插入多行

[`insertRowsBefore(beforePosition, howMany)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertrowsbefore): 在指定行位置之前插入若干行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這在第一行之前插入五行
sheet.insertRowsBefore(0, 5)
```

#### 刪除指定行

[`deleteRow(rowPosition)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#deleterow): 刪除給定行位置處的行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 行從 0 開始 - 這將刪除第一行
sheet.deleteRow(0)
```

#### 刪除多行

[`deleteRows(rowPosition, howMany)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#deleterows): 刪除從給定行位置開始的若干行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 行從 0 開始 - 這將刪除前兩行
sheet.deleteRows(0, 2)
```

#### 刪除多行 (不連續)

[`deleteRowsByPoints(rowPoints)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#deleterowsbypoints): 刪除由行位置陣列指定的多行（不連續）。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 行從 0 開始 - 這將刪除第 3 行和第 5-7 行
fWorksheet.deleteRowsByPoints([2, [4, 6]])
```

#### 移動行

[`moveRows(rowSpec, destinationIndex)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#moverows): 將給定範圍選定的行移動到 `destinationIndex` 指示的位置。`rowSpec` 本身不必準確表示要移動的整行或整組行 — 它選擇範圍跨越的所有行。

```typescript
// 以下程式碼將行 1-2 移動到目標索引 5
// 這會導致這些行變為行 3-4
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 選擇要移動的第 1 行和第 2 行
const rowSpec = sheet.getRange('1:2')
sheet.moveRows(rowSpec, 5)
```

#### 隱藏行

[`hideRow(row)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#hiderow): 隱藏指定範圍內的行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將隱藏第一行
const range = sheet.getRange('1:1')
sheet.hideRow(range)
```

#### 隱藏多行

[`hideRows(rowIndex, numRows)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#hiderows): 隱藏從指定索引開始的一個或多個連續行。此方法使用 0 索引。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 隱藏前三行
sheet.hideRows(0, 3)
```

#### 取消隱藏行

[`unhideRow(row)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#unhiderow): 取消隱藏指定範圍內的行。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 如果第一行之前被隱藏，則取消隱藏第一行
const range = sheet.getRange('1:1')
sheet.unhideRow(range)
```

#### 顯示多行

[`showRows(rowIndex, numRows)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#showrows): 取消隱藏從指定索引開始的一個或多個連續行。此方法使用 0 索引。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 取消隱藏前三行
sheet.showRows(0, 3)
```

#### 設定行高

[`setRowHeight(rowPosition, height)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#setrowheight): 設定給定行的行高（以畫素為單位）。預設情況下，行會擴充以適應單元格內容的大小。如果想要將行強制設定為指定高度，請使用 `setRowHeightsForced(startRow, numRows, height)`。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 將第一行的高度設定為 200 畫素
sheet.setRowHeight(0, 200)
```

#### 設定多行高度

[`setRowHeights(startRow, numRows, height)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#setrowheights): 設定給定行的高度（以畫素為單位）。預設情況下，行會擴充以適應單元格內容的大小。如果想要將行強制設定為指定高度，請使用 `setRowHeightsForced(startRow, numRows, height)`。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 將前三行的高度設定為 200 畫素
sheet.setRowHeights(0, 3, 200)
```

#### 強制設定多行高度

[`setRowHeightsForced(startRow, numRows, height)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#setrowheightsforced): 設定給定行的高度（以畫素為單位）。預設情況下，行會擴充以適應單元格內容的大小。使用 `setRowHeightsForced` 時，即使單元格內容高於行高，行也會被強制為指定的高度。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 將前三行的高度設定為 5 畫素
sheet.setRowHeightsForced(0, 3, 5)
```

#### 設定行高自動調整

[`autoResizeRows(startRow, numRows)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#autoresizerows): 設定給定行的高度自動調整以適應單元格內容。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 設定前三行的高度自動調整以適應單元格內容
sheet.autoResizeRows(0, 3)
```

#### 設定行自訂屬性

[`setRowCustom(custom)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#setrowcustom)：設定給定行的自訂屬性，在行上儲存一個物件 `custom`, 其中可以放入任何符合 JSON 格式的資料，用於自訂儲存一些額外的資訊。
更新 `custom` 資料會覆蓋原有的 `custom` 資料，如果你在更新資料時需要保留原有的 `custom` 資料，請提前獲取到 `custom` 資料合併成新的資料後再更新。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 設定第一行和第三行的自訂屬性
sheet.setRowCustom({
  0: { color: 'red' },
  2: { size: 16 },
})
```

### 列 Column

#### 在指定列後插入列

[`insertColumnAfter(afterPosition)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertcolumnafter): 在指定列位置之後插入一列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將在第一列位置後插入一列
sheet.insertColumnAfter(0)
```

#### 在指定列前插入列

[`insertColumnBefore(beforePosition)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertcolumnbefore): 在指定列位置之前插入一列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將在第一列位置插入一列
sheet.insertColumnBefore(0)
```

#### 插入多列

[`insertColumns(columnIndex, numColumns)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertcolumns): 在工作表中從指定位置開始插入一個或多個連續的空白列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 將所有列移動三位
sheet.insertColumns(0, 3)
```

#### 在指定列後插入多列

[`insertColumnsAfter(afterPosition, howMany)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertcolumnsafter): 在指定列位置後插入指定數量的列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 在第一列後插入兩列
sheet.insertColumnsAfter(0, 2)
```

#### 在指定列前插入多列

[`insertColumnsBefore(beforePosition, howMany)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#insertcolumnsbefore): 在指定列位置之前插入若干列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將在第一列之前插入五列
sheet.insertColumnsBefore(0, 5)
```

#### 刪除指定列

[`deleteColumn(columnPosition)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#deletecolumn): 刪除給定列位置處的列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 列從 0 開始 - 這將刪除第一列
sheet.deleteColumn(0)
```

#### 刪除多列

[`deleteColumns(columnPosition, howMany)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#deletecolumns): 刪除從給定列位置開始的若干列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 列從 0 開始 - 這將刪除前兩列
sheet.deleteColumns(0, 2)
```

#### 刪除多列（不連續）

[`deleteColumnsByPoints(columnPoints)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#deletecolumnsbypoints): 刪除由列位置陣列指定的多列（不連續）。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 列從 0 開始 - 這將刪除第 C 列和第 E-G 列
fWorksheet.deleteColumnsByPoints([2, [4, 6]])
```

#### 移動列

[`moveColumns(columnSpec, destinationIndex)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#movecolumns): 將給定範圍選定的列移動到 `destinationIndex` 指示的位置。 `columnSpec` 本身不必準確表示要移動的整列或整組列 - 它會選擇範圍跨越的所有列。

```typescript
// 以下程式碼將 A-B 行移動到目標索引 5。
// 這會導致這些列變成 C-D 列。
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 選擇要移動的 A 列和 B 列。
const columnSpec = sheet.getRange('A:B')
sheet.moveColumns(columnSpec, 5)
```

#### 隱藏列

[`hideColumn(column)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#hidecolumn): 隱藏給定範圍內的一列或多列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 這將隱藏第一列
const range = sheet.getRange('A:A')
sheet.hideColumn(range)
```

#### 隱藏多列

[`hideColumns(columnIndex, numColumns)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#hidecolumns): 隱藏從給定索引開始的一個或多個連續列。此方法使用 0 索引。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 隱藏前三列
sheet.hideColumns(0, 3)
```

#### 取消隱藏列

[`unhideColumn(column)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#unhidecolumn): 取消隱藏指定範圍內的列。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 如果第一列之前被隱藏，則取消隱藏
const range = sheet.getRange('A:A')
sheet.unhideColumn(range)
```

#### 顯示多列

[`showColumns(columnIndex, numColumns)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#showcolumns): 取消隱藏從指定索引開始的一個或多個連續列。此方法使用 0 索引。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 取消隱藏前三列
sheet.showColumns(0, 3)
```

#### 設定列寬

[`setColumnWidth(columnPosition, width)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#setcolumnwidth): 設定指定列的寬度（以畫素為單位）。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 將第一列的寬度設定為 200 畫素
sheet.setColumnWidth(0, 200)
```

#### 設定多列寬度

[`setColumnWidths(startColumn, numColumns, width)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#setcolumnwidths): 設定指定列的寬度（以畫素為單位）。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 將前三列的寬度設定為 200 畫素
sheet.setColumnWidths(0, 3, 200)
```

#### 設定列寬自動調整

[`autoResizeColumns(startColumn, numColumns)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#autoresizecolumns): 設定指定列的寬度自動調整以適應單元格內容。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 設定 A-C 列的寬度自動調整以適應單元格內容
sheet.autoResizeColumns(0, 3)
```

#### 設定列自訂屬性

[`setColumnCustom(custom)`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#setcolumncustom): 設定給定列的自訂屬性，在列上儲存一個物件 `custom`, 其中可以放入任何符合 JSON 格式的資料，用於自訂儲存一些額外的資訊。
更新 `custom` 資料會覆蓋原有的 `custom` 資料，如果你在更新資料時需要保留原有的 `custom` 資料，請提前獲取到 `custom` 資料合併成新的資料後再更新。

```typescript
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

// 設定第一列和第三列的自訂屬性
sheet.setColumnCustom({
  0: { color: 'red' },
  2: { size: 16 },
})
```