---
title: "图表语法"
description: "图表语法是将图表编写为文本的简短方法。"
canonical_url: "https://tiptap.zhcndoc.com/diagrams/data/chart-syntax"
---

# 图表语法

图表语法是将图表编写为文本的简短方法。

```txt
bar
Month | Online | Retail
Jan   | 42     | 30
Feb   | 48     | 28
```

## 类型行

如果第一行只包含图表类型（例如 `bar`、`pie` 或通过 `chartTypes` 注册的类型），则该行是类型行。类型名称不区分大小写，前后空格也会被忽略。

- **没有类型行时**，图表使用命令传入的类型，例如 `insertChartFrom` 的 `type` 选项；若未传入，则使用 `chart.defaultType`。
- **类型行优先于** `type` 选项，因此文本本身会指定图表类型。
- **类型行会保留在文本中。** `editChartAsText` 会将其作为第一行写回，`setDiagramInputType` 则会替换该行。

## 行的读取方式

| 规则    | 读取方式                                            |
| ----- | ----------------------------------------------- |
| 分隔符   | 逗号、分号、竖线和制表符；通过 `chart.delimiters` 选项配置         |
| 标题    | 如果第一行除第一列外不含数字，则该行是标题                           |
| `{H}` | 放在单元格前可将该单元格标记为标题                               |
| 标签    | 第一列包含标签                                         |
| `{L}` | 放在单元格前可将该单元格标记为标签                               |
| 空单元格  | 缺失值                                             |
| 非数字   | 非数字单元格保留为文本                                     |
| 引号    | 双引号中的单元格可以包含分隔符                                 |
| 列表    | 行首的项目符号或编号（`•`、`-`、`*`、`1.`）会被忽略，因此粘贴的列表会按数据行读取 |
| 单列    | 不含分隔符的多行文本会被读取为一列值，并标记为 1、2、3 等                 |

因此 `Month | Sales` 是标题，`Jan | 2` 是数据行。对于包含数字的标头（例如 `Region | 2025 | 2026`），请将 `{H}` 放在其单元格前面。

### 哪个分隔符分割

包含允许的分隔符的第一行决定整个文本的分隔符。在具有多个分隔符的行中，制表符、竖线或分号胜过逗号。因此，`Jan ; 1,5` 在分号处拆分，并将 `1,5` 读取为数字。

### 数字

- 对于 `decimalSeparator: 'auto'`，`1.5` 读取为 1.5，当分隔符不是逗号时，`1,5` 读取为 1.5。
- 将 `decimalSeparator` 设置为 `'.'` 或 `','` 以固定小数点分隔符。
- 不读取千位分隔符。

### 错误

引号打开后未闭合会被视为格式错误，例如 `Line 3: A quote is opened and never closed.`

## 在代码中使用

`insertChartFrom`、`updateChartFrom` 和 [AI 模型工具](https://tiptap.zhcndoc.com/diagrams/guides/ai.md) 都使用相同的文本格式：

```ts
editor.commands.insertChartFrom({ format: 'chart-syntax', content: 'bar\nJan | 42\nFeb | 48' })
```

`editor.storage.diagrams.read({ format: 'chart-syntax' })` 使用图表语法写入图表数据，并使用键入时使用的分隔符：

| 分隔符  | 写为        |
| ---- | --------- |
| 管道   | `\|`      |
| 制表符  | 裸制表符      |
| 任何其他 | 分隔符，然后是空格 |