# FPdfList

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

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade for one story-backed semantic PDF list.

## Access

Access through:

* [`FPdfPage.getLists()`](https://docs.univer.ai/zh-CN/reference/facade/pdf-page.md#getlists)
* [`FPdfPage.insertList()`](https://docs.univer.ai/zh-CN/reference/facade/pdf-page.md#insertlist)

## Inheritance

Extends [`FPdfPageElement`](https://docs.univer.ai/zh-CN/reference/facade/pdf-page-element.md). Its inherited members are available on this object.

## Example

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.insertList({
  text: 'First item',
  kind: univerAPI.Enum.PdfListKind.UNORDERED,
  preset: univerAPI.Enum.PdfListPresetId.UNORDERED_DISC,
})

list
  .insertItem(1, { text: '第二项' })
  .insertItem(2, { text: '子项', level: 1 })
  .insertItem(3, { text: '第四项' })
console.log(list.getItems())
```

## Setup

Register [`@univerjs-pro/pdfs`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/pdfs.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/pdfs/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/facade.md).

## `@univerjs-pro/pdfs`

### `FPdfList.changeItemLevel`

Set the absolute zero-based nesting level of one item.
Increasing the level requires a preceding item at the parent level, so the first item can only use level 0.

```typescript
changeItemLevel(itemId: string, level: number): this
```

**Parameters**

* `itemId` — Required. The stable item ID.
* `level` — Required. The nesting level from 0 through 8.

**Returns**

This list Facade for chaining.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.getLists()[0]
if (list) {
  list.insertItem(1, { text: 'Child item' })
  list.changeItemLevel(list.getItems()[1].id, 1)
}
```

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

### `FPdfList.getItems`

Return detached semantic list items in story order.

```typescript
getItems(): readonly IPdfListItemSnapshot[]
```

**Returns**

The current list-item snapshots.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.getLists()[0]
console.log(list?.getItems())
```

**Types:** [`IPdfListItemSnapshot`](https://unpkg.com/@univerjs-pro/pdfs@1.0.0-rc.0/lib/types/facade/types.d.ts)

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

### `FPdfList.insertItem`

Insert one semantic list item at a zero-based index.

```typescript
insertItem(index: number, item: IPdfListItemInput): this
```

**Parameters**

* `index` — Required. The insertion index.
* `item` — Required. The new item data.

**Returns**

This list Facade for chaining.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.getLists()[0]
if (list) {
  list.insertItem(1, { text: 'Second item', level: 0 })
}
```

**Types:** [`IPdfListItemInput`](https://unpkg.com/@univerjs-pro/pdfs@1.0.0-rc.0/lib/types/facade/types.d.ts)

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

### `FPdfList.removeItem`

Remove one stable semantic list item.

```typescript
removeItem(itemId: string): this
```

**Parameters**

* `itemId` — Required. The stable item ID.

**Returns**

This list Facade for chaining.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.getLists()[0]
const item = list?.getItems()[0]
if (list && item) {
  list.removeItem(item.id)
}
```

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

### `FPdfList.setItemText`

Replace the body text of one stable list item.

```typescript
setItemText(itemId: string, text: string): this
```

**Parameters**

* `itemId` — Required. The stable item ID.
* `text` — Required. The replacement body text.

**Returns**

This list Facade for chaining.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.getLists()[0]
const item = list?.getItems()[0]
if (list && item) {
  list.setItemText(item.id, 'Updated item')
}
```

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

### `FPdfList.setPreset`

Replace this list's marker preset.

```typescript
setPreset(preset: PdfListPresetId): this
```

**Parameters**

* `preset` — Required. The new list preset.

**Returns**

This list Facade for chaining.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.getLists()[0]
if (list) {
  list.setPreset(univerAPI.Enum.PdfListPresetId.UNORDERED_SQUARE)
}
```

**Types:** [`PdfListPresetId`](https://unpkg.com/@univerjs-pro/pdfs@1.0.0-rc.0/lib/types/text/list-presets.d.ts)

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

### `FPdfList.setStartNumber`

Set the starting ordinal for level zero of an ordered list.
All built-in `ORDERED_*` presets support this operation; unordered lists do not.

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

**Parameters**

* `startNumber` — Required. The positive first ordinal.

**Returns**

This list Facade for chaining.

**Examples**

```ts
const pdf = univerAPI.getActivePdf()
const page = pdf.getPageByIndex(0)
const list = page.insertList({
  text: 'First item',
  kind: univerAPI.Enum.PdfListKind.ORDERED,
  preset: univerAPI.Enum.PdfListPresetId.ORDERED_NUMBER_ALPHA,
})

list
  .insertItem(1, { text: '第二项' })
  .insertItem(2, { text: '子项', level: 1 })
  .insertItem(3, { text: '第四项' })
list.setStartNumber(3)
```

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