# FDocumentList

> Language fallback: requested `zh-CN`; content is `en-US`.

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade object for a docs list identified by `listId`.

## Access

Access through:

* [`FDocument.getLists()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#getlists)
* [`FDocument.getList()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#getlist)
* [`FDocument.insertList()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#insertlist)
* [`FDocument.setBullet()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#setbullet)
* [`FDocument.setOrderedList()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#setorderedlist)

## Example

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-list.md) 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](https://docs.univer.ai/zh-CN/guides/docs/getting-started/facade.md).

## `@univerjs-pro/docs-list`

### `FDocumentList.demote`

Demotes the whole list by one nesting level.

```typescript
demote(): boolean
```

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

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

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

### `FDocumentList.describe`

Returns a compact description of this list for agents.

```typescript
describe(): IDocsListInfo
```

**Returns**

The list id, item count, and item descriptions.

**Examples**

```ts
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`](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/types.d.ts)

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

### `FDocumentList.getId`

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

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

**Returns**

The list id.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list.d.ts)

### `FDocumentList.getItems`

Returns all item facades in this list.

```typescript
getItems(): FDocumentListItem[]
```

**Returns**

The list item facades.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/facade/document-list-item.md)

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

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

```typescript
getSegmentId(): string
```

**Returns**

The segment id.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list.d.ts)

### `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?".

```typescript
hasOrderedItems(): boolean
```

**Returns**

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const list = fDocument.getList('list-a')

if (list?.hasOrderedItems()) {
  list.setPrefixSuffix('Step ', ':')
}
```

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

### `FDocumentList.hasUnorderedItems`

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

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

```typescript
hasUnorderedItems(): boolean
```

**Returns**

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const list = fDocument.getList('list-a')

if (list?.hasUnorderedItems()) {
  list.setGlyphSymbol('•')
}
```

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

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

```typescript
isMixed(): boolean
```

**Returns**

`true` when this list has both ordered and unordered items.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list.d.ts)

### `FDocumentList.promote`

Promotes the whole list by one nesting level.

```typescript
promote(): boolean
```

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

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

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

### `FDocumentList.setGlyphSymbol`

Changes the bullet symbol for the whole list.

```typescript
setGlyphSymbol(symbol: string): boolean
```

**Parameters**

* `symbol` — Required. The bullet symbol to apply.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list.d.ts)

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

```typescript
setGlyphType(glyphType: ListGlyphType): boolean
```

**Parameters**

* `glyphType` — Required. The marker glyph type to apply.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/types/interfaces/i-document-data.d.ts)

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

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

```typescript
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**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list.d.ts)

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

```typescript
setStartNumber(startNumber: number): boolean
```

**Parameters**

* `startNumber` — Required. The visible number to start from.

**Returns**

Whether the mutation succeeded.

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list@1.0.0-rc.0/lib/types/facade/f-document-list.d.ts)