# 畫板元素

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [boards/model/board-elements.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/boards/model/board-elements.zh-TW.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 動作。