FDocumentSection

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

Example

TypeScript

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

Setup

Register @univerjs/docs or a preset that includes it. In plugin mode, import @univerjs/docs/facade. Additional methods below require their listed plugin packages. See Facade setup.

`@univerjs/docs`

`FDocumentSection.describe`

Returns a compact serializable section summary.

TypeScript

describe(): IFDocumentSectionDescription

Examples

TypeScript

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

Types: IFDocumentSectionDescription

Package: @univerjs/docs · Type definitions

`FDocumentSection.ensureFooter`

Ensures a footer segment linked specifically to this section.

TypeScript

ensureFooter(variant?: SectionHeaderFooterVariant): string

Parameters

variant — Optional. Default: 'default'.

Examples

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`FDocumentSection.ensureHeader`

Ensures a header segment linked specifically to this section.

TypeScript

ensureHeader(variant?: SectionHeaderFooterVariant): string

Parameters

variant — Optional. Default: 'default'.

Examples

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: ISectionColumnProperties

Package: @univerjs/docs · Type definitions

`FDocumentSection.getConfig`

Returns the section break snapshot that terminates this section.

TypeScript

getConfig(): ISectionBreak

Examples

TypeScript

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

Types: ISectionBreak

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`FDocumentSection.getId`

Returns the persisted section id.

TypeScript

getId(): string

Examples

TypeScript

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

Package: @univerjs/docs · Type definitions

`FDocumentSection.getIndex`

Returns the current zero-based section index.

TypeScript

getIndex(): number

Examples

TypeScript

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

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: FDocumentSectionPageSetup

Package: @univerjs/docs · Type definitions

`FDocumentSection.getPermission`

Returns this Section's permission facade.

TypeScript

getPermission(): FDocumentObjectPermission

Returns

Permission facade combining Document and Section Edit points.

Examples

TypeScript

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

Types: FDocumentObjectPermission

Package: @univerjs/docs · Type definitions

`FDocumentSection.getRange`

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

TypeScript

getRange(): IFDocumentTextRange

Examples

TypeScript

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

Types: IFDocumentTextRange

Package: @univerjs/docs · Type definitions

`FDocumentSection.isFooterLinkedToPrevious`

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

TypeScript

isFooterLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean

Parameters

variant — Optional. Default: 'default'.

Examples

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`FDocumentSection.isHeaderLinkedToPrevious`

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

TypeScript

isHeaderLinkedToPrevious(variant?: SectionHeaderFooterVariant): boolean

Parameters

variant — Optional. Default: 'default'.

Examples

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`FDocumentSection.remove`

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

TypeScript

remove(): boolean

Examples

TypeScript

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

Package: @univerjs/docs · Type definitions

`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

TypeScript

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 · ColumnSeparatorType

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: IFDocumentSectionColumnOptions

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: IHeaderFooterProps

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: SectionHeaderFooterVariant

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Package: @univerjs/docs · Type definitions

How is this guide?