tiptap 后端文档操作

后端文档操作允许开发者通过编程方式在协作服务器（本地部署和云版本）上管理文档。

此功能提供了文档管理的灵活性，通过 JSON 进行更新，这是直接使用 Yjs 方法的一个更简单选择。

该功能完全符合版本历史记录，并能追踪用户的更改，以及后端文档操作功能。

警告 需要订阅
此功能需要有效的商业或企业订阅，并且运行了 Tiptap Cloud 实例 。

应用场景

后端文档操作支持多种应用场景，例如：

• 文档内容的实时翻译。
• 服务器端组件，如执行 SQL 查询并显示结果。
• 自动拼写和语法纠错。
• 版本历史集成和并发编辑时无冲突的合并。

这一强大的功能集使 Tiptap 平台上的文档处理具有广泛的定制化和自动化能力，适用于各种协同编辑场景。

更新文档

要更新协作服务器上的现有文档，可以使用 PATCH 方法和以下 API 端点：

PATCH /api/documents/:identifier?format=:format

该端点接受一个 Yjs 更新消息，并将其应用到指定的文档。format 查询参数指定了更新的格式，可以是以下之一：

• binary：直接使用 Yjs 的Y.encodeStateAsUpdate方法。
• base64：二进制状态作为 Base64 字符串编码。
• json：使用 JSON 格式更新文档（有一些限制，见下文）。

成功更新后，服务器将返回 HTTP 状态码 204。如果文档不存在，将返回 404 ；如果负载无效或无法应用更新，则返回 422。

更新文档的 curl 命令示例：

curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \\
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \\
--data '@yjsUpdate.binary.txt'

通过 JSON 更新

通过 JSON 更新时，服务器会计算当前文档状态与提供的 JSON 之间的差异，然后内部计算所需的 Yjs 更新以达到目标状态。

为了确保精确更新，特别是针对节点特定的更改，建议使用 nodeAttributeName 和 nodeAttributeValue 参数。这些可以通过 Tiptap 的 唯一 ID 扩展 或自定义实现生成。

• nodeAttributeName：在唯一 ID 扩展中配置为 attributeName。
• nodeAttributeValue：要更新的节点的唯一生成值。

从版本 3.3.0 开始，可以使用 ?mode=append 在不改变现有内容的情况下向文档的 JSON 表示添加节点。

省略这些参数可能会覆盖在获取文档和发出更新调用之间所做的任何更新。

以下是使用 JSON 更新文档的 TypeScript 示例：

// 定义文档名称、密钥和应用程序ID
const docName = ''
const secret = ''
const appId = ''

// 构建基URL
const url = `https://${appId}.collab.tiptap.dev`

// 获取当前文档的JSON表示
const docJson = await axios.get(`${url}/api/documents/${docName}?format=json`, {
  headers: {
    Authorization: secret
  },
})

// 提取文档的JSON内容
const tiptapJson = docJson.data
const nodes = tiptapJson.content

// 使用唯一标识符查找并打印特定节点
const queryNode = nodes.find(n => n.attrs?.identifier === 'fe5c0789-85d9-4877-a2c3-bccf5d874866').content[0].text
const resultTable = nodes.find(n => n.attrs?.identifier === '246368b6-0746-4ca1-a16f-8d964aff4041')

console.log(`查询：${queryNode}`)
console.log(JSON.stringify(resultTable.content))

// 在结果表节点中添加新内容
resultTable.content.push({
  // 新表格行内容在这里
  {
    "type": "tableRow",
    "content": [
      {
        "type": "tableCell",
        "attrs": {
          "colspan": 1,
          "rowspan": 1
        },
        "content": [
          {
            "type": "paragraph",
            "attrs": {
              "textAlign": "left"
            },
            "content": [
              {
                "type": "text",
                "text": "Jan"
              }
            ]
          }
        ]
      },
      // ...
    ]
  }
})

// 将更新后的JSON发送回服务器应用更改
await axios.patch(`${url}/api/documents/${docName}?format=json`, tiptapJson, {
  headers: {
    Authorization: secret
  }
})

创建文档

要在 Tiptap Collab 服务器上播种新文档，使用 POST 方法和以下端点：

POST /api/documents/:identifier?format=:format

服务器对于成功创建将返回 HTTP 状态码 204，如果文档已存在（必须先删除才能覆盖）将返回 409，如果操作失败将返回 422。

format 参数接受与更新端点相同的值（ binary、base64 或 json ）。