# 行列操作

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

## Facade API

完整 Facade API 类型定义，请查看 [Facade API](https://reference.univer.ai/zh-CN)

### 行 Row

#### 在指定行后插入行

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

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

// 这将在第一行位置后插入一行
sheet.insertRowAfter(0)
```

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

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

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

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

#### 插入多行

[`insertRows(rowIndex, numRows)`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#insertrows): 在工作表中从指定位置开始插入一个或多个连续的空白行。

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

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

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

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

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

// 这将在第一行后插入五行
sheet.insertRowsAfter(0, 5)
```

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

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

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

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

#### 删除指定行

[`deleteRow(rowPosition)`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#deleterow): 删除给定行位置处的行。

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

// 行从 0 开始 - 这将删除第一行
sheet.deleteRow(0)
```

#### 删除多行

[`deleteRows(rowPosition, howMany)`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#deleterows): 删除从给定行位置开始的若干行。

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

// 行从 0 开始 - 这将删除前两行
sheet.deleteRows(0, 2)
```

#### 删除多行（不连续）

[`deleteRowsByPoints(rowPoints)`](https://docs.univer.ai/zh-CN/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-CN/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-CN/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-CN/reference/facade/worksheet.md#hiderows): 隐藏从指定索引开始的一个或多个连续行。此方法使用 0 索引。

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

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

#### 取消隐藏行

[`unhideRow(row)`](https://docs.univer.ai/zh-CN/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-CN/reference/facade/worksheet.md#showrows): 取消隐藏从指定索引开始的一个或多个连续行。此方法使用 0 索引。

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

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

#### 设置行高

[`setRowHeight(rowPosition, height)`](https://docs.univer.ai/zh-CN/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-CN/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-CN/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-CN/reference/facade/worksheet.md#autoresizerows): 设置给定行的高度自动调整以适应单元格内容。

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

// 设置前三行的高度自动调整以适应单元格内容
sheet.autoResizeRows(0, 3)
```

#### 设置行自定义属性

[`setRowCustom(custom)`](https://docs.univer.ai/zh-CN/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-CN/reference/facade/worksheet.md#insertcolumnafter): 在指定列位置之后插入一列。

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

// 这将在第一列位置后插入一列
sheet.insertColumnAfter(0)
```

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

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

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

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

#### 插入多列

[`insertColumns(columnIndex, numColumns)`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#insertcolumns): 在工作表中从指定位置开始插入一个或多个连续的空白列。

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

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

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

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

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

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

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

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

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

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

#### 删除指定列

[`deleteColumn(columnPosition)`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#deletecolumn): 删除给定列位置处的列。

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

// 列从 0 开始 - 这将删除第一列
sheet.deleteColumn(0)
```

#### 删除多列

[`deleteColumns(columnPosition, howMany)`](https://docs.univer.ai/zh-CN/reference/facade/worksheet.md#deletecolumns): 删除从给定列位置开始的若干列。

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

// 列从 0 开始 - 这将删除前两列
sheet.deleteColumns(0, 2)
```

#### 删除多列（不连续）

[`deleteColumnsByPoints(columnPoints)`](https://docs.univer.ai/zh-CN/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-CN/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-CN/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-CN/reference/facade/worksheet.md#hidecolumns): 隐藏从给定索引开始的一个或多个连续列。此方法使用 0 索引。

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

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

#### 取消隐藏列

[`unhideColumn(column)`](https://docs.univer.ai/zh-CN/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-CN/reference/facade/worksheet.md#showcolumns): 取消隐藏从指定索引开始的一个或多个连续列。此方法使用 0 索引。

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

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

#### 设置列宽

[`setColumnWidth(columnPosition, width)`](https://docs.univer.ai/zh-CN/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-CN/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-CN/reference/facade/worksheet.md#autoresizecolumns): 设置指定列的宽度自动调整以适应单元格内容。

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

// 设置 A-C 列的宽度自动调整以适应单元格内容
sheet.autoResizeColumns(0, 3)
```

#### 设置列自定义属性

[`setColumnCustom(custom)`](https://docs.univer.ai/zh-CN/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 },
})
```