# Document Body Structure

- Human documentation: [https://docs.univer.ai/guides/docs/model/document-body](https://docs.univer.ai/guides/docs/model/document-body)

- Agent Markdown: [https://docs.univer.ai/guides/docs/model/document-body.md](https://docs.univer.ai/guides/docs/model/document-body.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [docs/model/document-body.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/model/document-body.mdx)

---

## IDocumentBody

`IDocumentBody` stores the main flow content of a Univer Docs document.

The actual text is stored in `dataStream`. Styles and structural information are stored in parallel arrays and linked to the text through indexes.

### Properties

| Property           | Type                     | Description                                                                                                            |
| ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| dataStream         | `string`                 | Plain text stream of the document body. Special characters mark paragraphs, section breaks, tables, and custom blocks. |
| textRuns?          | `ITextRun[]`             | Inline style ranges.                                                                                                   |
| paragraphs?        | `IParagraph[]`           | Paragraph metadata and paragraph styles.                                                                               |
| sectionBreaks?     | `ISectionBreak[]`        | Section break metadata.                                                                                                |
| customBlocks?      | `ICustomBlock[]`         | Plugin-defined block placeholders.                                                                                     |
| tables?            | `ICustomTable[]`         | Table markers in the document body. Table definitions live in `IDocumentData.tableSource`.                             |
| columnGroups?      | `ICustomColumnGroup[]`   | Column group markers.                                                                                                  |
| blockRanges?       | `IDocumentBlockRange[]`  | Structured block ranges such as callout, quote, and code blocks.                                                       |
| customRanges?      | `ICustomRange[]`         | Special ranges such as hyperlinks, fields, bookmarks, comments, mentions, and plugin-defined ranges.                   |
| customDecorations? | `ICustomDecoration[]`    | Decoration ranges such as comment highlights.                                                                          |
| payloads?          | `Record<string, string>` | Temporary copy/paste payloads. This field is not persisted.                                                            |

### dataStream

`dataStream` is the source of truth for the body text. A paragraph usually ends with `\r\n`.

```typescript
const body: IDocumentBody = {
  dataStream: 'Title\r\nHello Univer\r\n',
  paragraphs: [
    { startIndex: 5, paragraphId: 'p-title' },
    { startIndex: 19, paragraphId: 'p-body' },
  ],
}
```

### Special Characters

Some document elements are represented by control characters in `dataStream` and expanded by the renderer:

| Character | Meaning                  |
| --------- | ------------------------ |
| `\r\n`    | Paragraph break          |
| `\n`      | Section break            |
| `\f`      | Page break               |
| `\v`      | Column break             |
| `\t`      | Tab                      |
| `\0`      | Document end             |
| `\b`      | Custom block placeholder |

Tables and custom ranges also use control characters internally. When working with tables, links, comments, and block-level features, prefer Facade APIs or commands instead of hand-writing control characters.

## Relationship with IDocumentData

`IDocumentBody` only stores the main document flow. External resources are stored on `IDocumentData`:

* `tableSource` stores table definitions.
* `drawings` stores image and drawing objects.
* `headers` and `footers` each contain their own `IDocumentBody`.
* `lists` stores list definitions referenced by paragraph bullets.
* `resources` stores plugin-defined data.