---
title: "数据"
description: "图表将数据以列和行的形式保存在文档中。"
canonical_url: "https://tiptap.zhcndoc.com/diagrams/data/overview"
---

# 数据

图表将数据以列和行的形式保存在文档中。

每列都有 `id`、`label` 和 `role`。`role: 'label'` 表示用于命名各行的列，`role: 'series'` 表示数值列。每一行都是一个单元格列表，每列对应一个单元格。

## 数据来源

| 数据来源  | 处理方式                                                  | 页面                                                                    |
| ----- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| 输入的行  | 在 `:::` 后输入 `Jan \| 2` 这样的行，即可生成图表                    | [快速输入](https://tiptap.zhcndoc.com/diagrams/data/quick-input.md)       |
| 表格    | 将表格转换为图表；编辑表格时，关联的图表也会更新                              | [表格](https://tiptap.zhcndoc.com/diagrams/data/tables.md)              |
| 文件或服务 | 图表保存 CSV 或 JSON URL 的数据快照，也可保存自定义数据提供程序的快照            | [数据源](https://tiptap.zhcndoc.com/diagrams/data/sources.md)            |
| 粘贴的文本 | Mermaid 图表源码会转换为图表；粘贴到选中图表的行会替换其数据                    | [粘贴](https://tiptap.zhcndoc.com/diagrams/data/pasting.md)             |
| 代码    | 使用 `insertChart` 和图表数据，或使用 `insertChartFrom` 和指定格式的文本 | [图表](https://tiptap.zhcndoc.com/diagrams/charts/overview.md#commands) |
| AI 模型 | AI 工具通过相同的命令写入数据                                      | [模型工具](https://tiptap.zhcndoc.com/diagrams/guides/ai.md)              |

## 绘制哪些列

图表数据会保留所有列。图表设置中的 `encoding` 字段记录图表在编辑器和导出内容中要绘制的列 ID：

| 字段         | 说明                                                                                                                      |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `label`    | 用于命名各行的列                                                                                                                |
| `series`   | 要绘制的列，按绘制顺序排列                                                                                                           |
| `seriesIn` | `'rows'` 表示按行读取系列，会交换行和列，参见 [`setChartSeriesIn`](https://tiptap.zhcndoc.com/diagrams/data/overview.md#setchartseriesin) |

- 未指定 `label` 时，`role: 'label'` 的列用于命名各行。
- 未指定 `series` 时，会绘制其他所有 `role: 'series'` 的列。
- 如果某个 ID 不在数据中，就会被忽略。因此，即使数据源重命名了列，图表仍可继续绘制。
- 如果 `series` 中的 ID 一个也不在数据中，则会绘制所有系列。
- 同步会替换所有列，同时保留 `encoding`。参见[数据源](https://tiptap.zhcndoc.com/diagrams/data/sources.md#showing-only-some-columns)。

可通过 [`updateChartSpec`](https://tiptap.zhcndoc.com/diagrams/charts/appearance.md#updatechartspec) 或下列命令设置 `encoding`。

## 命令

### updateChartData

替换图表数据。

```ts
editor.commands.updateChartData({ data })
```

| 选项     | 类型          | 描述               |
| ------ | ----------- | ---------------- |
| `data` | `ChartData` | 新的图表数据           |
| `pos`  | `number`    | 图表位置，默认使用当前选中的图表 |

如果 `pos` 处或当前选区中没有图表，或者图表关联的数据源为只读且新数据与当前数据不同，则返回 `false`。

### setChartLabelColumn

指定用于命名各行的列。`encoding.series` 将设为图表类型可绘制的其他列。

```ts
editor.commands.setChartLabelColumn({ label: 'region' })
```

| 选项      | 类型       | 说明               |
| ------- | -------- | ---------------- |
| `label` | `string` | 用于命名各行的列 ID      |
| `pos`   | `number` | 图表位置，默认使用当前选中的图表 |

大多数图表类型会绘制 `role: 'series'` 的列。对于按 `matrix` 结构读取数据的类型（例如 `matrix` 图表），会绘制所有列。参见[注册自定义图表类型](https://tiptap.zhcndoc.com/diagrams/renderers/custom-chart-types.md#fields-of-a-chart-type)。选择第一列会从 `encoding` 中移除 `label` 和 `series`；`encoding.seriesIn` 始终保留。

如果指定的列 ID 不存在于数据中，则返回 `false`。

### setChartSeriesIn

指定图表系列按列还是按行读取。一个系列是一组要绘制的值，例如一条线或一种颜色的柱形。

```ts
editor.commands.setChartSeriesIn({ seriesIn: 'rows' })
```

| 选项         | 类型                    | 说明                               |
| ---------- | --------------------- | -------------------------------- |
| `seriesIn` | `'columns' \| 'rows'` | 默认值为 `'columns'`；`'rows'` 会交换行和列 |
| `pos`      | `number`              | 图表的位置。默认为选定的图表                   |

设为 `'rows'` 后，每一行都会成为一个以行标签命名的系列，每个要绘制的列都会成为一个类别。以下面的柱状图数据为例：

```txt
Month | Visitors
Jan   | 120
Feb   | 150
Mar   | 170
```

| `seriesIn`  | 类别       | 每个类别中的柱形              |
| ----------- | -------- | --------------------- |
| `'columns'` | 一月、二月、三月 | 每个类别一根柱形，系列为 Visitors |
| `'rows'`    | Visitors | 每个类别三根柱形，分别对应一月、二月、三月 |

此命令只会更改 `spec.encoding.seriesIn`，并保留 `label` 和 `series`。交换后，`spec.series` 中的样式按行标签指定，`spec.palette` 则按绘制顺序为系列着色。

### updateChartFrom

根据已注册格式的内容替换图表数据和规格。可将图表读为图表语法、图表 JSON 或 Mermaid 文本，修改后再写回：

> **Interactive demo:** [DiagramsFormats](https://embed-pro.tiptap.dev/preview/Extensions/DiagramsFormats)

```ts
editor.commands.updateChartFrom({ format: 'chart-syntax', content: 'Jan | 2\nFeb | 3' })
```

| 选项        | 类型       | 描述               |
| --------- | -------- | ---------------- |
| `format`  | `string` | 已注册格式的 ID        |
| `content` | `string` | 该格式的文本内容         |
| `pos`     | `number` | 图表位置，默认使用当前选中的图表 |

当内容无法读取或图表为只读时，返回 `false`。

### updateChartFromGrid

替换字符串网格中的数据。

```ts
editor.commands.updateChartFromGrid({ grid })
```

| 选项     | 类型           | 说明                |
| ------ | ------------ | ----------------- |
| `grid` | `string[][]` | 第 0 行是标题，第 0 列是标签 |
| `pos`  | `number`     | 图表的位置。默认为所选图表     |

可与 [`readGrid`](https://tiptap.zhcndoc.com/diagrams/api-reference/storage.md#reading-a-charts-data) 配合使用，将数据作为表单字段编辑。粘贴到选中图表上的电子表格行也会通过此命令更新数据，参见[粘贴到选中的图表](https://tiptap.zhcndoc.com/diagrams/data/pasting.md#onto-a-selected-chart)。

在与 `updateChartData` 相同的情况下返回 `false`。

### updateChartFromTable

替换表 JSON 中的数据。

```ts
editor.commands.updateChartFromTable({ table })
```

| 选项      | 类型         | 描述            |
| ------- | ---------- | ------------- |
| `table` | `JSONNode` | JSON 形式的表节点   |
| `pos`   | `number`   | 图表的位置。默认为所选图表 |

将其与 [`readTable`](https://tiptap.zhcndoc.com/diagrams/api-reference/storage.md#reading-a-charts-data) 一起使用，这会以表 JSON 形式返回图表数据。

在与 `updateChartData` 相同的情况下返回 `false`。

## 工具帮助程序

来自 `@tiptap-pro/extension-diagrams/core`：

| 函数                                     | 返回                               |
| -------------------------------------- | -------------------------------- |
| `encodeChartData(data, encoding)`      | 渲染器绘制的图表数据                       |
| `encodingForLabel(data, label, shape)` | 编码 `setChartLabelColumn` 写入，而不写入 |