超链接和书签

超链接在 DOCX 和 Tiptap 之间转换时，会作为带有 href 属性的 link 标记处理。外部 URL 和电子邮件链接可以顺利地双向转换。指向同一文档中其他位置的链接也可以双向转换，同时保留它们所指向的书签目标。

你需要什么

• 扩展： ConvertKit，它同时注册用于超链接的 Link 标记和用于锚点目标的 Bookmark 节点。
• 配置： 无需配置。

支持概览

导入

使用 编辑器扩展 或 REST API 导入超链接。两者产生相同的输出。

转换服务会检测 <w:hyperlink> 元素，并生成带有 link 标记的文本节点。外部链接通过文档的关系文件解析。

{
  "type": "text",
  "text": "访问 Tiptap 网站",
  "marks": [
    { "type": "link", "attrs": { "href": "https://tiptap.dev" } }
  ]
}

文档内的链接

跳转到同一文档中其他位置的链接（例如目录条目或“返回顶部”链接）会变成一个 link 标记，其 href 为片段：

{
  "type": "text",
  "text": "Go to introduction",
  "marks": [
    { "type": "link", "attrs": { "href": "#intro" } }
  ]
}

Word 会以不止一种方式存储这些链接，所有方式都会被导入：

• 超链接元素自身的锚点，Word 将其写为 w:anchor。
• 带有 \l 开关的 HYPERLINK 域，包括简单形式和复杂形式。

当链接同时包含网址和锚点时，两者会合并为单个 href，例如 https://example.com#intro。

书签目标

链接跳转到的位置是一个 Word 书签。每个书签都会被导入为一个宽度为零的 bookmark 节点，并将书签名称作为其 id：

{ "type": "bookmark", "attrs": { "id": "intro" } }

该节点位于书签开始的位置，因此锚点会保留其在文档中的位置。链接通过使用 # 后跟相同的 id 来指向它。位于段落之间而非段落内部的书签，会附加到后续段落的开头。

编辑器渲染

ConvertKit 注册了 Link 扩展，因此无需单独安装。

它会将链接标记渲染为带有 href 属性的 <a> 标签。

该扩展会自动添加 target（默认 _blank）和 rel（默认 noopener noreferrer nofollow）属性。这些属性不会从 DOCX 导入中带入，也不会包含在 DOCX 导出中。

书签目标需要使用 Bookmark 节点，该节点默认由 ConvertKit 注册。如果没有该节点，导入的内容加载到编辑器时锚点会被丢弃，指向这些锚点的链接也会停止解析。该节点是一个内联原子节点，会渲染为空的 <span data-bookmark-id="...">，因此不占用空间，也不会与链接自身的 <a> 元素发生冲突。向 ConvertKit 传入 bookmark: false 即可将其排除。

导出

使用 编辑器扩展 或 REST API 导出超链接。两者对链接的处理相同。

指向网址的链接（包括 mailto: 地址）会被包装在带有 Hyperlink 样式的 DOCX 外部超链接中，href 会成为 DOCX 包中的外部关系。

href 以 # 开头的链接会导出为指向匹配书签的 Word 内部超链接，因此它的导航方式与编辑器中的相同。bookmark 节点会重新导出为 Word 书签，这些链接正是指向这些书签的。

单独的 # 没有可指向的目标，因此该文本会在没有链接的情况下导出。仅包含片段的 URL（例如 https://example.com#intro）仍然是外部链接。

哪些内容可以往返

带有纯链接文本的外部超链接可以完整通过导入、编辑、导出流程。href 和可见文本都会保留。导出的链接使用 DOCX Hyperlink 样式（通常是蓝色带下划线的文本）。

文档内导航也可以完整保留：链接仍然指向相同的目标，目标仍然保持其位置。

发生的变化：编辑器添加的 target 和 rel 属性不会带入 DOCX。