# FDocumentColumn

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade object for a single column inside a docs column group.

Columns in this facade belong to the modern-document ColumnGroup model. Read methods
return empty values in traditional mode; mutation methods throw a flavor-specific error.

The column wrapper resolves its range from persisted column ids every time a method
is called, so it stays useful after edits insert content before the column group.

## Access

Access through:

* [`FDocumentColumnGroup.getColumns()`](https://docs.univer.ai/reference/facade/document-column-group.md#getcolumns)
* [`FDocumentColumnGroup.getColumn()`](https://docs.univer.ai/reference/facade/document-column-group.md#getcolumn)
* [`FDocumentColumnGroup.addColumn()`](https://docs.univer.ai/reference/facade/document-column-group.md#addcolumn)

## Example

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

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

const column = group?.getColumn(0)
console.log(column?.getText())
console.log(column?.getInsertOffset())
```

## 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`

### `FDocumentColumn.appendParagraph`

Appends a plain-text paragraph inside this column.

```typescript
appendParagraph(text?: string): FDocumentParagraph
```

**Parameters**

* `text` — Optional. Default: `''`. The paragraph text. Defaults to an empty paragraph.

**Returns**

The appended paragraph facade.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0)
const paragraph = column?.appendParagraph('Next steps')
console.log(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.d.ts)

### `FDocumentColumn.getColumnGroupId`

Returns the parent column group id.

```typescript
getColumnGroupId(): string
```

**Returns**

The persisted column group id.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const column = group?.getColumn(0)
console.log(column?.getColumnGroupId())
```

**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.d.ts)

### `FDocumentColumn.getContentRange`

Returns the editable content range inside this column.

The range excludes the column structural tokens and stops before the trailing
paragraph or section-break token that keeps the column editable. Use this range
for text replacement and `getInsertOffset()` for inserting blocks, such as tables.

```typescript
getContentRange(): IDocsColumnContentRange | null
```

**Returns**

The editable range, or `null` if the column no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const column = group?.getColumn(0)
console.log(column?.getContentRange())
```

**Types:** [`IDocsColumnContentRange`](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.d.ts)

### `FDocumentColumn.getId`

Returns the column id stored in the parent column group config.

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

**Returns**

The persisted column id.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const column = group?.getColumn(0)
console.log(column?.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.d.ts)

### `FDocumentColumn.getIndex`

Returns the current zero-based column index inside the parent group.

```typescript
getIndex(): number
```

**Returns**

The column index, or `-1` when the column no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const column = group?.getColumn(0)
console.log(column?.getIndex())
```

**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.d.ts)

### `FDocumentColumn.getInsertOffset`

Returns the safest insertion offset for adding content at the end of this column.

This offset is intentionally placed before the trailing paragraph or section-break
token when one exists. Keeping that trailing token after inserted tables prevents
the table from being parsed as content outside the column group.

```typescript
getInsertOffset(): number | null
```

**Returns**

The insertion offset, or `null` if the column no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const thirdColumn = group?.getColumn(2)
const offset = thirdColumn?.getInsertOffset()

if (offset != null) {
  fDocument?.insertTableFromData(
    [
      ['Metric', 'Now', 'Next'],
      ['Adoption', '68%', '80%'],
    ],
    {
      offset,
    },
  )
}
```

**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.d.ts)

### `FDocumentColumn.getParagraphs`

Returns paragraph facades whose paragraph marks are contained in this column.

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

**Returns**

Paragraphs in column-local order.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0)
const paragraphs = column?.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.d.ts)

### `FDocumentColumn.getRange`

Returns the structural data-stream range for this column.
The range includes the column start and end structural tokens.

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

**Returns**

The column range, or `null` if the column no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const column = group?.getColumn(0)
console.log(column?.getRange())
```

**Types:** [`IDocsColumnOffsetRange`](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.d.ts)

### `FDocumentColumn.getText`

Returns plain text inside the column.
Paragraph breaks are normalized to `\n`, and trailing structural breaks are omitted.

```typescript
getText(): string
```

**Returns**

The column text, or an empty string if the column no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const group = fDocument.findColumnGroupByText('Launch')
const column = group?.getColumn(0)
console.log(column?.getText())
```

**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.d.ts)

### `FDocumentColumn.getTextRange`

Returns an editable text-range facade for the column content.

```typescript
getTextRange(): FDocumentTextRange | null
```

**Returns**

The editable range, or `null` if the column no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0)
console.log(column?.getTextRange()?.getText())
```

**Types:** [`FDocumentTextRange`](https://docs.univer.ai/reference/facade/document-text-range.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.d.ts)

### `FDocumentColumn.insertParagraph`

Inserts a plain-text paragraph at a column-local paragraph index.

The index is relative to this column, not the whole document. Passing the
current paragraph count appends inside the column, before `COLUMN_END`.

```typescript
insertParagraph(index: number, text?: string): FDocumentParagraph
```

**Parameters**

* `index` — Required. The zero-based column-local paragraph insertion index.
* `text` — Optional. Default: `''`. The paragraph text. Defaults to an empty paragraph.

**Returns**

The inserted paragraph facade.

**Throws**

If the index is outside `0..getParagraphs().length`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0)

// The index is relative to this column. This inserts before its first paragraph.
const paragraph = column?.insertParagraph(0, 'Executive summary')
console.log(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.d.ts)

### `FDocumentColumn.setText`

Replaces the editable column content with plain text.

```typescript
setText(text: string): boolean
```

**Parameters**

* `text` — Required. The replacement text.

**Returns**

`true` if the edit was applied.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0)
column?.setText('Launch plan\nOwner: Product')
```

**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.d.ts)

### `FDocumentColumn.setTextStyle`

Applies a text-style patch across the editable column content.
`style.fs` is a font size in points (pt), not CSS pixels.

```typescript
setTextStyle(style: ITextStyle): boolean
```

**Parameters**

* `style` — Required. The text-style patch to apply.

**Returns**

`true` if the edit was applied.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const column = fDocument?.findColumnGroupByText('Launch')?.getColumn(0)
column?.setTextStyle({ fs: 10.5, bl: univerAPI.Enum.BooleanNumber.TRUE })
```

**Types:** [`ITextStyle`](https://docs.univer.ai/reference/types/text-style.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.d.ts)