# FDocumentColumnGroup

- Human documentation: [https://docs.univer.ai/reference/facade/document-column-group](https://docs.univer.ai/reference/facade/document-column-group)

- Agent Markdown: [https://docs.univer.ai/reference/facade/document-column-group.md](https://docs.univer.ai/reference/facade/document-column-group.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/document-column-group.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/document-column-group.mdx)

---

Facade object for a docs column group.

ColumnGroup is available only in modern documents. Read methods return empty values
if a retained facade is used after switching to traditional mode; mutation methods
throw `DocsColumnUnsupportedDocumentFlavorError`.

A column group is the horizontal block container that owns two to five columns.
Mutating methods run synchronously through the Univer rich-text mutation pipeline,
so undo/redo and collaboration receive the same document changes as UI operations.

## Access

Access through:

* [`FDocument.getColumnGroups()`](https://docs.univer.ai/reference/facade/document.md#getcolumngroups)
* [`FDocument.getColumnGroup()`](https://docs.univer.ai/reference/facade/document.md#getcolumngroup)
* [`FDocument.getColumnGroupAt()`](https://docs.univer.ai/reference/facade/document.md#getcolumngroupat)
* [`FDocument.findColumnGroupByText()`](https://docs.univer.ai/reference/facade/document.md#findcolumngroupbytext)
* [`FDocument.findColumnGroups()`](https://docs.univer.ai/reference/facade/document.md#findcolumngroups)
* [`FDocument.insertColumnGroup()`](https://docs.univer.ai/reference/facade/document.md#insertcolumngroup)

## Example

```ts
const fDocument = univerAPI.getActiveDocument()

const groups = fDocument.getColumnGroups()
console.log(groups.map((group) => group.describe()))

const group = fDocument.findColumnGroupByText('Launch')
console.log(group?.describe())

group?.setWidthRatios([1.2, 1, 0.8])
```

## Setup

Register [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/docs-column/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/docs/getting-started/facade.md).

## `@univerjs-pro/docs-column`

### `FDocumentColumnGroup.addColumn`

Adds an empty column to the left or right of an existing column.

```typescript
addColumn(targetColumnId: string, position: ColumnPosition, columnId?: string): FDocumentColumn | null
```

**Parameters**

* `targetColumnId` — Required. Existing column id used as the insertion anchor.
* `position` — Required. Whether the new column is inserted to the left or right of the target column.
* `columnId` — Optional. Default: `generateRandomId(6)`. Optional id for the inserted column. A random id is generated when omitted.

**Returns**

The inserted column wrapper, or `null` if the mutation failed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const columns = group.getColumns()

// Add a new column to the left of the last column in the group.
if (columns.length > 0) {
  const rightColumn = group.getColumn(columns.length - 1)
  const inserted = group.addColumn(
    rightColumn.getId(),
    univerAPI.Enum.DocsColumnPositionEnum.LEFT,
    'new-column',
  )
  console.log(inserted?.getInsertOffset())
}
```

**Types:** [`FDocumentColumn`](https://docs.univer.ai/reference/facade/document-column.md) · [`ColumnPosition`](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/common/column-types.d.ts)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.deleteColumn`

Deletes a column from this group.
Column groups must keep at least two columns, so deleting from a two-column group returns `false`.

```typescript
deleteColumn(columnId: string): boolean
```

**Parameters**

* `columnId` — Required. The column id to delete.

**Returns**

`true` if the mutation was committed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const columns = group.getColumns()

// Delete the first column in the group.
group.deleteColumn(columns[0].getId())
```

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.describe`

Returns a compact, serializable description of the column group.

```typescript
describe(): IDocsColumnDescription
```

**Returns**

Id, layout config, column ratios, and sample column text.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]
  console.log(group.describe())
}
```

**Types:** [`IDocsColumnDescription`](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getColumn`

Returns a column by zero-based index or by column id.

```typescript
getColumn(indexOrId: number | string): FDocumentColumn | null
```

**Parameters**

* `indexOrId` — Required. Zero-based column index, or persisted column id.

**Returns**

The column wrapper, or `null` if no column matches.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]

  const columnWithIndex = group.getColumn(0)
  console.log(columnWithIndex?.getText())

  const columnWithId = group.getColumn('right-column')
  console.log(columnWithId?.getText())
}
```

**Types:** [`FDocumentColumn`](https://docs.univer.ai/reference/facade/document-column.md)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getColumnCount`

Returns the number of columns in the group.

```typescript
getColumnCount(): number
```

**Returns**

The column count, or `0` if the group is missing.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]
  console.log(group.getColumnCount())
}
```

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getColumns`

Returns all column wrappers in document order.

```typescript
getColumns(): FDocumentColumn[]
```

**Returns**

Column wrappers, or an empty array when the group is missing.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]
  const columns = group.getColumns()
  columns.forEach((column) => console.log(column.getText()))
}
```

**Types:** [`FDocumentColumn`](https://docs.univer.ai/reference/facade/document-column.md)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getConfig`

Returns the column group config stored in `documentData.body.columnGroups`.

```typescript
getConfig(): ICustomColumnGroup | undefined
```

**Returns**

The group config, or `undefined` if the group is missing.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]
  console.log(group.getConfig())
}
```

**Types:** [`ICustomColumnGroup`](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/common/column-types.d.ts)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getId`

Returns the column group id.

```typescript
getId(): string
```

**Returns**

The persisted column group id.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]
  console.log(group.getId())
}
```

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getParagraphs`

Returns all paragraph facades inside the group, in column and document order.

```typescript
getParagraphs(): FDocumentParagraph[]
```

**Returns**

Paragraphs in column and document order.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument?.findColumnGroupByText('Launch')
const paragraphs = group?.getParagraphs() ?? []
console.log(paragraphs.map((paragraph) => paragraph.getText()))
```

**Types:** [`FDocumentParagraph`](https://docs.univer.ai/reference/facade/document-paragraph.md)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getRange`

Returns the structural range for this column group.
The group range includes the column group start and end structural tokens.

```typescript
getRange(): IDocsColumnGroupOffsetRange | null
```

**Returns**

The parsed group range, or `null` if the group is missing.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]
  console.log(group.getRange())
}
```

**Types:** [`IDocsColumnGroupOffsetRange`](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/common/column-range.d.ts)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.getWidthRatios`

Returns the current column width ratios.

```typescript
getWidthRatios(): number[]
```

**Returns**

The width ratios from the column group config.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const groups = fDocument.getColumnGroups()

if (groups.length > 0) {
  const group = groups[0]
  console.log(group.getWidthRatios())
}
```

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.remove`

Deletes the entire column group from the document body.

```typescript
remove(): boolean
```

**Returns**

`true` if the mutation was committed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const removed = group.remove()
console.log(removed)
```

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)

### `FDocumentColumnGroup.setWidthRatios`

Updates the width ratios for every column in the group.
The number of ratios must match the current column count and every ratio must be positive.

```typescript
setWidthRatios(widthRatios: number[]): boolean
```

**Parameters**

* `widthRatios` — Required. New positive width ratios, in column order.

**Returns**

`true` if the mutation was committed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
group.setWidthRatios([1.2, 1, 0.8])
```

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column@1.0.0-rc.0/lib/types/facade/f-document-column-group.d.ts)