FDocumentListItem
Facade object for a single docs list item.
Access
Access through:
FDocument.getListItems()FDocument.getListItem()FDocument.getListItemAt()FDocument.findListItemByText()FDocument.findListItems()FDocumentList.getItems()
Example
const fDocument = univerAPI.getActiveDocument()const item = fDocument.findListItemByText('Ship API')item?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER, { mode: univerAPI.Enum.DocsListSelectionMode.Level,})item?.demote()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
FDocumentListItem.continueNumbering
Continues numbering from the previous same-level ordered list segment.
continueNumbering(): booleanReturns
Whether the mutation succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Start a new list segment that continues numbering from the previous segment.const item = fDocument.findListItemByText('New Segment')item?.continueNumbering()Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.demote
Demotes this item, level, or whole list by one nesting level.
mode: Item only changes this item's nesting level. It works for both ordered and
unordered list items. Demoting an item that is already at the maximum nesting level is
a no-op, so it may succeed without a visible change.
demote(options?: IDocsListOperationOptions): booleanParameters
options— Optional. Default:{}. Scope options. Defaults tomode: 'list'in command behavior.
Returns
Whether the mutation succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Demote the whole list.const item = fDocument.findListItemByText('Todo')item?.demote({ mode: univerAPI.Enum.DocsListSelectionMode.List })// Demote the current level.const item2 = fDocument.findListItemByText('Subtask 1')item2?.demote({ mode: univerAPI.Enum.DocsListSelectionMode.Level })// Demote just the item.const item3 = fDocument.findListItemByText('Subtask 1')item3?.demote({ mode: univerAPI.Enum.DocsListSelectionMode.Item })Types: IDocsListOperationOptions
Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.describe
Returns an agent-friendly description of this list item.
describe(): IDocsListItemInfo | nullReturns
The list item info, or null if the paragraph is no longer a list item.
Examples
const fDocument = univerAPI.getActiveDocument()const item = fDocument.findListItemByText('Ship API')console.log(item?.describe())Types: IDocsListItemInfo
Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.getParagraphStartIndex
Returns the paragraph start index that identifies this list item.
getParagraphStartIndex(): numberReturns
The paragraph start index.
Examples
const fDocument = univerAPI.getActiveDocument()const item = fDocument.findListItemByText('Ship API')console.log(item?.getParagraphStartIndex())Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.getSegmentId
Get the segment id of this list item. The main body list item have an empty string segment id. The header and footer list item have a non-empty string segment id.
getSegmentId(): stringReturns
The segment id.
Examples
const fDocument = univerAPI.getActiveDocument()const item = fDocument.findListItemByText('Ship API')console.log(item?.getSegmentId())Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.getText
Returns plain text in this list item.
getText(): stringReturns
The list item text.
Examples
const fDocument = univerAPI.getActiveDocument()const item = fDocument.findListItemByText('Ship API')console.log(item?.getText())Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.isOrdered
Returns whether this list item is rendered as an ordered marker.
This is the recommended guard before calling ordered-list-only APIs such as
setPrefixSuffix() or setStartNumber().
isOrdered(): booleanReturns
true when this item uses an ordered marker.
Examples
const fDocument = univerAPI.getActiveDocument()const item = fDocument.findListItemByText('Step 1')if (item?.isOrdered()) { item.setPrefixSuffix('Step ', ':')}Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.isUnordered
Returns whether this list item is rendered as an unordered bullet marker.
This is the recommended guard before calling bullet-list-oriented APIs such as
setGlyphSymbol().
isUnordered(): booleanReturns
true when this item exists and uses an unordered marker.
Examples
const fDocument = univerAPI.getActiveDocument()const item = fDocument.findListItemByText('Todo')if (item?.isUnordered()) { item.setGlyphSymbol('•')}Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.promote
Promotes this item, level, or whole list by one nesting level.
mode: Item only changes this item's nesting level. It works for both ordered and
unordered list items. Promoting an item that is already at the top level is a no-op,
so it may succeed without a visible change.
promote(options?: IDocsListOperationOptions): booleanParameters
options— Optional. Default:{}. Scope options. Defaults tomode: 'list'in command behavior.
Returns
Whether the mutation succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Promote the whole list.const item = fDocument.findListItemByText('Todo')item?.promote({ mode: univerAPI.Enum.DocsListSelectionMode.List })// Promote the current level.const item2 = fDocument.findListItemByText('Subtask 1')item2?.promote({ mode: univerAPI.Enum.DocsListSelectionMode.Level })// Promote just the item.const item3 = fDocument.findListItemByText('Subtask 1')item3?.promote({ mode: univerAPI.Enum.DocsListSelectionMode.Item })Types: IDocsListOperationOptions
Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.select
Selects this item, its current level, or its whole list.
select(mode?: DocsListSelectionMode): booleanParameters
mode— Optional. Default:DocsListSelectionMode.Item. Selection scope. Defaults toitem.
Returns
Whether the selection command succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Select just the item.const item = fDocument.findListItemByText('Ship API')item?.select()// Select the whole list.const item2 = fDocument.findListItemByText('Todo')item2?.select(univerAPI.Enum.DocsListSelectionMode.List)// Select the current level.const item3 = fDocument.findListItemByText('Subtask 1')item3?.select(univerAPI.Enum.DocsListSelectionMode.Level)Types: DocsListSelectionMode
Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.setGlyphSymbol
Changes the bullet symbol for this item, level, or whole list.
setGlyphSymbol(symbol: string, options?: IDocsListOperationOptions): booleanParameters
symbol— Required. The bullet symbol to apply.options— Optional. Default:{}. Scope options. Defaults tomode: 'list'in command behavior.
Returns
Whether the mutation succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Change bullet symbol for the whole list.const item = fDocument.findListItemByText('Todo')item?.setGlyphSymbol('•', { mode: univerAPI.Enum.DocsListSelectionMode.List })// Change bullet symbol for the current level.const item2 = fDocument.findListItemByText('Subtask 1')item2?.setGlyphSymbol('◦', { mode: univerAPI.Enum.DocsListSelectionMode.Level })// Change bullet symbol for just the item.const item3 = fDocument.findListItemByText('Subtask 1')item3?.setGlyphSymbol('▪', { mode: univerAPI.Enum.DocsListSelectionMode.Item })Types: IDocsListOperationOptions
Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.setGlyphType
Changes the list marker glyph type for this item, level, or 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, options?: IDocsListOperationOptions): booleanParameters
glyphType— Required. The marker glyph type to apply.options— Optional. Default:{}. Scope options. Defaults tomode: 'list'in command behavior.
Returns
Whether the mutation succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Change glyph type for the whole list.const item = fDocument.findListItemByText('Todo')item?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER, { mode: univerAPI.Enum.DocsListSelectionMode.List,})// Change glyph type for the current level.const item2 = fDocument.findListItemByText('Subtask 1')item2?.setGlyphType(univerAPI.Enum.ListGlyphType.LOWER_ROMAN, { mode: univerAPI.Enum.DocsListSelectionMode.Level,})// Change glyph type for just the item.const item3 = fDocument.findListItemByText('Subtask 1')item3?.setGlyphType(univerAPI.Enum.ListGlyphType.UPPER_LETTER, { mode: univerAPI.Enum.DocsListSelectionMode.Item,})Types: ListGlyphType · IDocsListOperationOptions
Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.setPrefixSuffix
Sets ordered-list prefix and suffix for this item, level, or 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:.
In mode: Item, the item receives a custom list definition, but it keeps the same
listId so ordered-list numbering stays continuous with the surrounding list. Because
ordered marker rendering also depends on that shared numbering context, prefix/suffix
changes may appear to affect adjacent items in the same continuous list. Use mode: Level
or mode: List when formatting ordered-list markers for a stable visual result.
No-op for unordered bullet lists.
setPrefixSuffix(prefix: string, suffix: string, options?: IDocsListOperationOptions): booleanParameters
prefix— Required. Prefix before the number token.suffix— Required. Suffix after the number token.options— Optional. Default:{}. Scope options. Defaults tomode: 'list'in command behavior.
Returns
Whether the mutation succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Set prefix/suffix for the whole list.const item = fDocument.findListItemByText('Todo')if (item?.isOrdered()) { item.setPrefixSuffix('(', ')', { mode: univerAPI.Enum.DocsListSelectionMode.List })}// Set prefix/suffix for the current level.const item2 = fDocument.findListItemByText('Subtask 1')if (item2?.isOrdered()) { item2.setPrefixSuffix('<', '>', { mode: univerAPI.Enum.DocsListSelectionMode.Level })}// Set prefix/suffix for just the item.const item3 = fDocument.findListItemByText('Subtask 1')if (item3?.isOrdered()) { item3.setPrefixSuffix('[', ']', { mode: univerAPI.Enum.DocsListSelectionMode.Item })}Types: IDocsListOperationOptions
Package: @univerjs-pro/docs-list · Type definitions
FDocumentListItem.setStartNumber
Starts ordered-list numbering from the provided number at this item.
This only applies to ordered list items. Calling it on an unordered bullet list is a no-op.
The current implementation restarts numbering from this item and may affect following
continuous ordered-list items, regardless of mode.
setStartNumber(startNumber: number, options?: IDocsListStartNumberOptions): booleanParameters
startNumber— Required. The visible number to start from.options— Optional. Default:{}. Scope and restart options.
Returns
Whether the mutation succeeded.
Examples
const fDocument = univerAPI.getActiveDocument()// Start numbering from 5 for the whole list.const item = fDocument.findListItemByText('Todo')if (item?.isOrdered()) { item.setStartNumber(5, { mode: univerAPI.Enum.DocsListSelectionMode.List })}// Start numbering from 3 for the current level.const item2 = fDocument.findListItemByText('Subtask 1')if (item2?.isOrdered()) { item2.setStartNumber(3, { mode: univerAPI.Enum.DocsListSelectionMode.Level })}// Start numbering from 10 for just the item.const item3 = fDocument.findListItemByText('Subtask 1')if (item3?.isOrdered()) { item3.setStartNumber(10, { mode: univerAPI.Enum.DocsListSelectionMode.Item })}Types: IDocsListStartNumberOptions
Package: @univerjs-pro/docs-list · Type definitions
你觉得这篇文档如何？