# FDocumentSection

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade wrapper for an OOXML-compatible traditional document section.
Modern documents use ColumnGroup APIs. Unspecified documents must resolve
their flavor before using this facade.

## Access

Access through:

* [`FDocument.getSections()`](https://docs.univer.ai/reference/facade/document.md#getsections)
* [`FDocument.getSection()`](https://docs.univer.ai/reference/facade/document.md#getsection)
* [`FDocument.getSectionAt()`](https://docs.univer.ai/reference/facade/document.md#getsectionat)
* [`FDocument.insertSectionBreak()`](https://docs.univer.ai/reference/facade/document.md#insertsectionbreak)

## Example

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  console.log(fDocument.getSection(0)?.describe())
}
```

## Setup

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

## `@univerjs/docs`

### `FDocumentSection.describe`

Returns a compact serializable section summary.

```typescript
describe(): IFDocumentSectionDescription
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.describe())
```

**Types:** [`IFDocumentSectionDescription`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-section.d.ts)

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

### `FDocumentSection.ensureFooter`

Ensures a footer segment linked specifically to this section.

```typescript
ensureFooter(variant?: SectionHeaderFooterVariant): string
```

**Parameters**

* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  const segmentId = fDocument.getSection(0)?.ensureFooter('first')
  if (segmentId) {
    fDocument.insertText(0, 'Confidential', segmentId)
  }
}
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.ensureHeader`

Ensures a header segment linked specifically to this section.

```typescript
ensureHeader(variant?: SectionHeaderFooterVariant): string
```

**Parameters**

* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  const segmentId = fDocument.getSection(0)?.ensureHeader()
  if (segmentId) {
    fDocument.insertText(0, 'Quarterly report', segmentId)
  }
}
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.getColumns`

Returns the explicit columns. An empty array means the normal single-column layout.
Column widths and trailing spaces are in 96-DPI layout pixels.

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.getColumns())
```

**Types:** [`ISectionColumnProperties`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocumentSection.getConfig`

Returns the section break snapshot that terminates this section.

```typescript
getConfig(): ISectionBreak
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.getConfig())
```

**Types:** [`ISectionBreak`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocumentSection.getEffectivePageSetup`

Returns nominal page geometry after resolving this section's overrides
against document defaults. All geometry values use 96-DPI layout pixels.

This synchronous model-only API works without `engine-render`. It does not
report physical page count, remaining page space, or final coordinates.

```typescript
getEffectivePageSetup(): IEffectiveSectionPageSetup
```

**Returns**

A cloned, serializable page setup.

**Examples**

```ts
const document = univerAPI.getActiveDocument()
if (!document) {
  throw new Error('No active document')
}
if (!document.isTraditional()) {
  throw new Error('Traditional document sections are required')
}

const section = document.getSection(0)
if (!section) {
  throw new Error('The document has no traditional section')
}

const layout = section.getEffectivePageSetup()
console.log({
  pageWidth: layout.pageSize.width,
  pageHeight: layout.pageSize.height,
  contentWidth: layout.contentSize.width,
  contentHeight: layout.contentSize.height,
  margins: layout.margins,
})
```

**Types:** [`IEffectiveSectionPageSetup`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/utils/section-columns.d.ts)

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

### `FDocumentSection.getFooterId`

Returns the effective footer id after resolving links to previous sections.

```typescript
getFooterId(variant?: SectionHeaderFooterVariant): string | null
```

**Parameters**

* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.getFooterId('first'))
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.getHeaderId`

Returns the effective header id after resolving links to previous sections.

```typescript
getHeaderId(variant?: SectionHeaderFooterVariant): string | null
```

**Parameters**

* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.getHeaderId('default'))
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.getId`

Returns the persisted section id.

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.getId())
```

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

### `FDocumentSection.getIndex`

Returns the current zero-based section index.

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.getIndex())
```

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

### `FDocumentSection.getPageSetup`

Returns this section's explicit page setup overrides.
Missing values inherit from the document style. Geometry values use 96-DPI layout pixels.

Use `getEffectivePageSetup()` when an agent needs resolved page and content
dimensions rather than only the overrides stored on this section.

```typescript
getPageSetup(): FDocumentSectionPageSetup
```

**Returns**

A cloned object containing only explicit section overrides.

**Examples**

```ts
const document = univerAPI.getActiveDocument()
const section = document?.getSection(0)
console.log(section?.getPageSetup())
```

**Types:** [`FDocumentSectionPageSetup`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-section.d.ts)

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

### `FDocumentSection.getPermission`

Returns this Section's permission facade.

```typescript
getPermission(): FDocumentObjectPermission
```

**Returns**

Permission facade combining Document and Section Edit points.

**Examples**

```ts
const section = univerAPI.getActiveDocument()?.getSection(0)
if (!section) throw new Error('Section not found.')
await section.getPermission().setReadOnly()
```

**Types:** [`FDocumentObjectPermission`](https://docs.univer.ai/reference/facade/document-object-permission.md)

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

### `FDocumentSection.getRange`

Returns the section content range, excluding its terminating section-break token.

```typescript
getRange(): IFDocumentTextRange
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(0)?.getRange())
```

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

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

### `FDocumentSection.isFooterLinkedToPrevious`

Whether this footer variant inherits the previous section's reference.

```typescript
isFooterLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean
```

**Parameters**

* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(1)?.isFooterLinkedToPrevious('even'))
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.isHeaderLinkedToPrevious`

Whether this header variant inherits the previous section's reference.

```typescript
isHeaderLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean
```

**Parameters**

* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument?.getSection(1)?.isHeaderLinkedToPrevious())
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.remove`

Deletes this section break. The final top-level section break cannot be removed.

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  const sections = fDocument.getSections()
  if (sections.length > 1) {
    sections[0].remove()
  }
}
```

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

### `FDocumentSection.setColumnProperties`

Sets explicit OOXML-compatible column width and trailing-space values in 96-DPI layout pixels.

```typescript
setColumnProperties(columns: ISectionColumnProperties[], separator?: ColumnSeparatorType): boolean
```

**Parameters**

* `columns` — Required.
* `separator` — Optional. Default: `ColumnSeparatorType.NONE`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  fDocument.getSection(0)?.setColumnProperties(
    [
      { width: 240, paddingEnd: 18 },
      { width: 240, paddingEnd: 0 },
    ],
    univerAPI.Enum.ColumnSeparatorType.BETWEEN_EACH_COLUMN,
  )
}
```

**Types:** [`ISectionColumnProperties`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts) · [`ColumnSeparatorType`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocumentSection.setColumns`

Sets equal or explicitly sized columns for this traditional section.
Use `columnCount = 1` to restore normal single-column layout.
`gap` and `widths` are in 96-DPI layout pixels.

```typescript
setColumns(columnCount: number, options?: IFDocumentSectionColumnOptions): boolean
```

**Parameters**

* `columnCount` — Required.
* `options` — Optional. Default: `{}`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  fDocument.getSection(0)?.setColumns(2, { gap: 18, separator: true })
}
```

**Types:** [`IFDocumentSectionColumnOptions`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-section.d.ts)

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

### `FDocumentSection.setFooterLinkedToPrevious`

Links or unlinks this footer variant. Unlinking clones the inherited footer.

```typescript
setFooterLinkedToPrevious(linkedToPrevious: boolean, variant?: SectionHeaderFooterVariant): boolean
```

**Parameters**

* `linkedToPrevious` — Required.
* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  fDocument.getSection(1)?.setFooterLinkedToPrevious(true, 'even')
}
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.setHeaderFooterOptions`

Updates header/footer switches and margins on this section break.
`marginHeader` and `marginFooter` are in 96-DPI layout pixels.

```typescript
setHeaderFooterOptions(options: IHeaderFooterProps): boolean
```

**Parameters**

* `options` — Required.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  fDocument.getSection(0)?.setHeaderFooterOptions({
    marginHeader: 36,
    marginFooter: 36,
    useFirstPageHeaderFooter: univerAPI.Enum.BooleanNumber.TRUE,
  })
}
```

**Types:** [`IHeaderFooterProps`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/commands/commands/create-header-footer.command.d.ts)

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

### `FDocumentSection.setHeaderLinkedToPrevious`

Links or unlinks this header variant. Unlinking clones the inherited header.

```typescript
setHeaderLinkedToPrevious(linkedToPrevious: boolean, variant?: SectionHeaderFooterVariant): boolean
```

**Parameters**

* `linkedToPrevious` — Required.
* `variant` — Optional. Default: `'default'`.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (fDocument?.isTraditional()) {
  fDocument.getSection(1)?.setHeaderLinkedToPrevious(false, 'default')
}
```

**Types:** [`SectionHeaderFooterVariant`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/section-header-footer.d.ts)

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

### `FDocumentSection.setPageSetup`

Updates this section's page setup through the document section command.
Geometry values use 96-DPI layout pixels.

This method changes static page geometry; it does not choose where the
section begins. Use `setSectionType()` for an existing boundary, or
`insertSectionBreak(..., { nextSectionType })` while creating one.

```typescript
setPageSetup(pageSetup: FDocumentSectionPageSetup): boolean
```

**Parameters**

* `pageSetup` — Required. Explicit section overrides to patch.

**Returns**

`true` when the section command was applied.

**Examples**

```ts
const document = univerAPI.getActiveDocument()
if (!document?.isTraditional()) {
  throw new Error('A Traditional document is required')
}

const section = document.getSection(1)
if (!section) {
  throw new Error('The second section does not exist')
}
const updated = section.setPageSetup({
  pageSize: { width: 816, height: 1056 },
  marginTop: 96,
  marginBottom: 96,
  marginLeft: 96,
  marginRight: 96,
})
if (!updated) {
  throw new Error('Failed to update section page setup')
}
console.log(section.getEffectivePageSetup())
```

**Types:** [`FDocumentSectionPageSetup`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-section.d.ts)

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

### `FDocumentSection.setSectionType`

Sets how this section begins relative to the previous section.

The first section has no preceding boundary, so setting its type does not
create an initial blank page. Prefer `FDocument.insertSectionBreak` with
`nextSectionType` when creating a new boundary; use this method when
updating an existing section after resolving it again from the document.

```typescript
setSectionType(sectionType: SectionType): boolean
```

**Parameters**

* `sectionType` — Required. How this section begins.

**Returns**

`true` when the section command was applied.

**Examples**

```ts
const document = univerAPI.getActiveDocument()
if (!document?.isTraditional()) {
  throw new Error('A Traditional document is required')
}

const secondSection = document.getSection(1)
if (!secondSection) {
  throw new Error('The second section does not exist')
}
if (!secondSection.setSectionType(univerAPI.Enum.SectionType.NEXT_PAGE)) {
  throw new Error('Failed to update the second section')
}
```

**Types:** [`SectionType`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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