# 画板元素

- Human documentation: [https://docs.univer.ai/zh-CN/guides/boards/model/board-elements](https://docs.univer.ai/zh-CN/guides/boards/model/board-elements)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/boards/model/board-elements.md](https://docs.univer.ai/zh-CN/guides/boards/model/board-elements.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [boards/model/board-elements.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/boards/model/board-elements.zh-CN.mdx)

---

画板页面将可绘制对象存储在 `elements` 中，并通过 `elementOrder` 记录它们的视觉顺序。每个元素都有稳定的 `id`、`type`，以及用于描述其在画布上位置和大小的 `transform`。

## 通用元素字段

| 字段           | 类型                         | 说明                                                                        |           |
| ------------ | -------------------------- | ------------------------------------------------------------------------- | --------- |
| id           | `string`                   | 元素 ID，在页面内唯一。                                                             |           |
| type         | `BoardElementType`         | 元素类型，例如 `text`、`shape`、`image`、`connector`、`container`、`table` 或 `group`。 |           |
| transform    | `IBoardElementTransform`   | 位置、大小、旋转、缩放、倾斜和翻转值。                                                       |           |
| parentId?    | `string`                   | 父容器或父组的 ID。                                                               |           |
| laneId?      | `string`                   | 元素位于泳道中时对应的泳道 ID。                                                         |           |
| name?        | `string`                   | 便于阅读的元素名称。                                                                |           |
| description? | `string`                   | 无障碍或应用元数据。                                                                |           |
| visible?     | `boolean`                  | 是否渲染该元素。                                                                  |           |
| selectable?  | `boolean`                  | 编辑器是否可以选中该元素。                                                             |           |
| locked?      | `boolean`                  | 是否锁定编辑。                                                                   |           |
| custom?      | \`Record\<string, unknown> | null\`                                                                    | 应用自定义元数据。 |

## 元素类型

| 类型          | 附加数据                                | 常见用途                 |
| ----------- | ----------------------------------- | -------------------- |
| `text`      | `text`, `textStyle`, `textData`     | 便签、标签和富文本块。          |
| `shape`     | `shapeData`                         | 矩形、箭头、标注和自定义形状。      |
| `image`     | `source`, `imageSourceType`, `crop` | 嵌入式图片。               |
| `connector` | `connectorData`                     | 连接到自由点或形状的线条和箭头。     |
| `container` | `containerData`                     | 框架、区域、泳道、UML 包和系统边界。 |
| `table`     | `tableId`                           | 由表格插件提供的画板表格元素。      |
| `chart`     | `chartId`                           | 图表元素。                |
| `media`     | `mediaType`, `source`               | 音频和视频占位符。            |
| `group`     | `children`                          | 成组的元素集合。             |

## 容器

容器通过 `containerData.behavior` 定义成员归属行为，并通过 `containerData.capturePolicy` 定义捕获规则。请使用 Facade 的容器方法移入或移出元素，以确保顺序和父子关系保持一致。

```ts
board.wrapElementsInContainer(['task-1', 'task-2'], {
  title: 'Sprint 1',
})
```

## 泳道

泳道是一种包含 `containerData.swimlane` 的容器。每条泳道都有稳定的 ID、标题、顺序值、大小，以及可选的折叠状态。

```ts
board.setSwimlaneLanes('lane-board', {
  orientation: 'horizontal',
  lanes: [
    { id: 'todo', title: 'Todo', order: 0, size: 240 },
    { id: 'doing', title: 'Doing', order: 1, size: 240 },
  ],
})
```

## 连接线

连接线使用端点和路由数据。端点可以是自由点、形状边界、连接点或生命线。由于路由数据通常取决于几何信息，编辑连接线时建议优先使用 Facade 操作或 UI 操作。