数据源

该图表存储地址（表示数据的来源）和快照（上次读取的数据的副本）。该图表是从快照中绘制的，因此它是在导出时离线绘制的，并且适合无法到达源的人员。

快速入门

editor.commands.linkChartSource({
  provider: 'url-csv',
  address: { url: 'https://example.com/sales.csv' },
  readOnly: true,
})

存储在文档中

listCharts() 报告两者。

链接或分离

mode、'linked' 或 'detached'，表示图表是否遵循其源。

已链接 (mode: 'linked')。快照由 linkChartSource、syncChartData、requestSync、relinkChartSource 以及使用 subscribe 推送更改的提供程序从源读取（请参阅编写提供程序）。在两者之间，图表显示了最后一个快照。与 readOnly: false 链接的图表也可以手动编辑。

分离 (mode: 'detached')。 detachChartSource 停止跟踪源并保留快照和地址，以便您可以再次编辑数据。 relinkChartSource 再次跟踪源并将数据替换为源返回的数据。

只读

readOnly 是一个单独的标志。它仅在图表链接时有效。使用 readOnly: true，更改数据的命令会返回 false，因此下次同步永远不会覆盖本地编辑。图表规格保持可编辑状态。分离会使标志保持原样，并且当您重新链接时它会再次起作用。

仅显示部分列

同步将替换所有列。要仅显示其中一些，请设置 encoding 和 updateChartSpec。它在每次同步中都存在。

editor.commands.updateChartSpec({ spec: { encoding: { label: 'region', series: ['revenue'] } } })

当图表同步时

同步读取源并将新快照写入图表。

• 快照不包含在撤消历史记录中，因此撤消永远不会与您的编辑一起收回同步。
• 每次同步都会设置 syncedAt，当数据相同时也是如此。然后，该文档会记录上次检查数据的时间。在版本比较中，这算作更改，请参阅 Versions.
• 当无法读取源时，图表将保留其快照。扩展调用 onSourceError 选项并显示错误和 { provider, address }。
• 每个同步客户端都需要注册提供程序。 没有它的客户端会显示快照并且无法读取源。

要同步读取 URL 的每个图表：

await editor.storage.diagrams.requestSync({ provider: 'url-csv', address: { url } })

该扩展程序不会按计划同步。例如，您的应用程序可以使用 setInterval。请遵守您所阅读的服务的限制。

内置提供程序

读取 URL

URL 必须是绝对的，并使用 http: 或 https:。当您设置 allowSourceUrl 选项时，URL 也必须传递它。服务器必须允许您的应用程序的网页读取该文件 (CORS)。已发布的 Google 表格可以做到这一点。

读取失败，图表保留其数据，在这些情况下：

• 该地址不是这样的 URL。
• 服务器以错误状态应答。
• 请求被阻止。
• 答案是 HTML 页面而不是文件。许多主机向他们不知道的地址发送状态为 200 的邮件。

读取表格

文档中表格后面的图表使用 document-table，请参阅表格。

编写提供程序

读取天气 API 并用接下来的 7 天填充图表的提供程序：

提供程序是具有 id 和 read 函数的对象。将其传递到 sources 选项中，或在运行时使用 editor.storage.diagrams.registerSource(provider) 添加：

import type { ChartSourceProvider } from '@tiptap-pro/extension-diagrams'

const salesApi: ChartSourceProvider = {
  id: 'sales-api',
  read: async (address, { fetch }) => {
    const { region } = address as { region: string }
    const response = await fetch(`/api/sales?region=${encodeURIComponent(region)}`)
    const rows: { month: string; total: number }[] = await response.json()
    return {
      columns: [
        { id: 'month', label: 'Month', role: 'label' },
        { id: 'total', label: 'Total', role: 'series' },
      ],
      rows: rows.map((row) => [row.month, row.total]),
    }
  },
  describe: (address) => `Sales, ${(address as { region: string }).region}`,
}

• context 具有 fetch、decimalSeparator 和 editor。当您的应用程序设置 allowSourceUrl 时，它也会设置 allowUrl。
• 要报告错误，请抛出带有人们可以阅读的消息的 ChartSourceError。
• 该扩展程序为每个链接地址保留一个订阅，并将每个更改写入与其链接的每个图表中。

文档存储地址并与打开该文档的每个人共享该地址。切勿将凭据放入其中。当您创建提供程序时，需要密钥或令牌的提供程序将从您的应用程序中获取它。

Google Sheets、Excel 和 Airtable 为每项服务都有一个提供程序，以及每项服务需要设置的内容。

命令

linkChartSource

将图表链接到数据源。

editor.commands.linkChartSource({
  provider: 'url-csv',
  address: { url: 'https://example.com/sales.csv' },
  readOnly: true,
})

对于未知提供者返回 false。

syncChartData

写入新快照。

editor.commands.syncChartData({
  source: { provider: 'url-csv', address: { url: 'https://example.com/sales.csv' } },
})

返回没有匹配图表的 false，或者对于没有源的图表，不返回 data。

detachChartSource

停止跟踪源，并保留快照和地址。

editor.commands.detachChartSource()

对于没有源的图表，返回 false。

relinkChartSource

再次跟踪源并读取它。

editor.commands.relinkChartSource()

对于没有源的图表，返回 false。