FDocumentList

Facade object for a docs list identified by listId.

Access

Access through:

• FDocument.getLists()
• FDocument.getList()
• FDocument.insertList()
• FDocument.setBullet()
• FDocument.setOrderedList()

Example

const fDocument = univerAPI.getActiveDocument()const lists = fDocument.getLists()console.log(lists.map((list) => list.describe()))const list = fDocument.getList('list-a')list?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER)list?.setPrefixSuffix('Step ', ':')list?.promote()

Setup

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

@univerjs-pro/docs-list

FDocumentList.demote

Demotes the whole list by one nesting level.

demote(): boolean

Returns

Whether the mutation succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()// Demote the whole list by one level.const list = fDocument.getList('list-a')list?.demote()

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

FDocumentList.describe

Returns a compact description of this list for agents.

describe(): IDocsListInfo

Returns

The list id, item count, and item descriptions.

Examples

const fDocument = univerAPI.getActiveDocument()const lists = fDocument.getLists()// Get a description of the first list.if (lists.length > 0) {  const list = lists[0]  console.log(list.describe())}

Types: IDocsListInfo

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

FDocumentList.getId

Returns the list id shared by all items in this list.

getId(): string

Returns

The list id.

Examples

const fDocument = univerAPI.getActiveDocument()const lists = fDocument.getLists()// Get the id of the first list.if (lists.length > 0) {  const list = lists[0]  console.log(list.getId())}

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

FDocumentList.getItems

Returns all item facades in this list.

getItems(): FDocumentListItem[]

Returns

The list item facades.

Examples

const fDocument = univerAPI.getActiveDocument()const lists = fDocument.getLists()// Get the items of the first list.if (lists.length > 0) {  const list = lists[0]  const items = list.getItems()  items.forEach((item) => console.log(item.describe()))}

Types: FDocumentListItem

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

FDocumentList.getSegmentId

Get the segment id of this list. The main body lists have an empty string segment id. The header and footer lists have a non-empty string segment id.

getSegmentId(): string

Returns

The segment id.

Examples

const fDocument = univerAPI.getActiveDocument()const lists = fDocument.getLists()// Get the segment id of the first list.if (lists.length > 0) {  const list = lists[0]  console.log(list.getSegmentId())}

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

FDocumentList.hasOrderedItems

Returns whether this list contains at least one ordered item.

Lists can mix ordered and unordered items at different nesting levels, so this method answers "does any item support ordered-list-only operations?" rather than "is the whole list ordered?".

hasOrderedItems(): boolean

Returns

true when at least one item in this list is ordered.

Examples

const fDocument = univerAPI.getActiveDocument()const list = fDocument.getList('list-a')if (list?.hasOrderedItems()) {  list.setPrefixSuffix('Step ', ':')}

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

FDocumentList.hasUnorderedItems

Returns whether this list contains at least one unordered bullet item.

Lists can mix ordered and unordered items at different nesting levels.

hasUnorderedItems(): boolean

Returns

true when at least one item in this list is unordered.

Examples

const fDocument = univerAPI.getActiveDocument()const list = fDocument.getList('list-a')if (list?.hasUnorderedItems()) {  list.setGlyphSymbol('•')}

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

FDocumentList.isMixed

Returns whether this list contains both ordered and unordered items.

Mixed lists are valid. Agents should prefer item-level guards when applying APIs that only make sense for ordered or unordered markers.

isMixed(): boolean

Returns

true when this list has both ordered and unordered items.

Examples

const fDocument = univerAPI.getActiveDocument()const list = fDocument.getList('list-a')if (list?.isMixed()) {  console.log('Use item-level isOrdered/isUnordered checks for precise edits.')}

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

FDocumentList.promote

Promotes the whole list by one nesting level.

promote(): boolean

Returns

Whether the mutation succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()// Promote the whole list by one level.const list = fDocument.getList('list-a')list?.promote()

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

FDocumentList.setGlyphSymbol

Changes the bullet symbol for the whole list.

setGlyphSymbol(symbol: string): boolean

Parameters

• symbol — Required. The bullet symbol to apply.

Returns

Whether the mutation succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()// Change the whole list to use '•' as the bullet symbol for unordered lists.const list = fDocument.getList('list-a')list?.setGlyphSymbol('•')

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

FDocumentList.setGlyphType

Changes the list marker glyph type for the whole list.

glyphType controls the marker value style, such as decimal numbers, upper-case letters, lower-case letters, or Roman numerals. It does not change marker punctuation or wrapping; use setPrefixSuffix() to change formats such as 1., (1), or Step 1:.

For unordered bullet lists, setting an ordered glyph type such as DECIMAL removes the bullet symbol and renders the marker as an ordered value. For ordered lists, setting the same glyph type as the current level may succeed without a visible change. For example, the default first level of PresetListType.ORDER_LIST is already DECIMAL.

setGlyphType(glyphType: ListGlyphType): boolean

Parameters

• glyphType — Required. The marker glyph type to apply.

Returns

Whether the mutation succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()// Change the whole list to use upper-case letters.const list = fDocument.getList('list-a')list?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER)

Types: ListGlyphType

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

FDocumentList.setPrefixSuffix

Sets ordered-list prefix and suffix for the whole list.

This changes the ordered marker format around the number placeholder. For example, prefix: '(' and suffix: ')' renders markers like (1), while prefix: 'Step ' and suffix: ':' renders markers like Step 1:. No-op for unordered bullet lists.

setPrefixSuffix(prefix: string, suffix: string): boolean

Parameters

• prefix — Required. Prefix before the number token.
• suffix — Required. Suffix after the number token.

Returns

Whether the mutation succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()// Change the whole list to use 'Step ' as prefix and ':' as suffix for ordered items.const list = fDocument.getList('list-a')if (list?.hasOrderedItems()) {  list.setPrefixSuffix('Step ', ':')}

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

FDocumentList.setStartNumber

Starts ordered-list numbering from the provided number at the first item in this list.

This only applies to ordered lists. Calling it on an unordered bullet list is a no-op.

setStartNumber(startNumber: number): boolean

Parameters

• startNumber — Required. The visible number to start from.

Returns

Whether the mutation succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()// Start the ordered items in the whole list from number 3.const list = fDocument.getList('list-a')if (list?.hasOrderedItems()) {  list.setStartNumber(3)}

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