FDocumentColumnGroup

本 API 页面目前提供英文正文。代码签名与标识符不随界面语言变化。

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:

Example

TypeScript

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 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.

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

TypeScript

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

Package: @univerjs-pro/docs-column · Type definitions

`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

TypeScript

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 · Type definitions

`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

TypeScript

const fDocument = univerAPI.getActiveDocument()const groups = fDocument.getColumnGroups()if (groups.length > 0) {  const group = groups[0]  console.log(group.describe())}

Types: IDocsColumnDescription

Package: @univerjs-pro/docs-column · Type definitions

`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

TypeScript

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

Package: @univerjs-pro/docs-column · Type definitions

`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

TypeScript

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 · Type definitions

`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

TypeScript

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

Package: @univerjs-pro/docs-column · Type definitions

`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

TypeScript

const fDocument = univerAPI.getActiveDocument()const groups = fDocument.getColumnGroups()if (groups.length > 0) {  const group = groups[0]  console.log(group.getConfig())}

Types: ICustomColumnGroup

Package: @univerjs-pro/docs-column · Type definitions

`FDocumentColumnGroup.getId`

Returns the column group id.

TypeScript

getId(): string

Returns

The persisted column group id.

Examples

TypeScript

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 · Type definitions

`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

TypeScript

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

Types: FDocumentParagraph

Package: @univerjs-pro/docs-column · Type definitions

`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

TypeScript

const fDocument = univerAPI.getActiveDocument()const groups = fDocument.getColumnGroups()if (groups.length > 0) {  const group = groups[0]  console.log(group.getRange())}

Types: IDocsColumnGroupOffsetRange

Package: @univerjs-pro/docs-column · Type definitions

`FDocumentColumnGroup.getWidthRatios`

Returns the current column width ratios.

TypeScript

getWidthRatios(): number[]

Returns

The width ratios from the column group config.

Examples

TypeScript

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 · Type definitions

`FDocumentColumnGroup.remove`

Deletes the entire column group from the document body.

TypeScript

remove(): boolean

Returns

true if the mutation was committed.

Examples

TypeScript

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

Package: @univerjs-pro/docs-column · Type definitions

`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

TypeScript

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

Package: @univerjs-pro/docs-column · Type definitions

你觉得这篇文档如何？