从你的编辑器导出 EPUB

Available in Start planBetav0.3.0

使用 Tiptap 的 @tiptap-pro/extension-export-epub 可将编辑器内容导出为 .epub 文件。该扩展通过将文档发送到 Tiptap convert 服务进行转换，为你的编辑器集成 EPUB 导出功能。

如果你更希望自行处理转换，也可以改用 REST API。

安装 EPUB 导出扩展

Conversion 扩展发布在 Tiptap 的私有 npm 注册表中。请按照私有注册表指南集成这些扩展。

完成后，你就可以安装并导入 Export EPUB 扩展包。

npm i @tiptap-pro/extension-export-epub

import { ExportEpub } from '@tiptap-pro/extension-export-epub'

配置扩展

ExportEpub 扩展可通过 configure 方法接收一个 ExportEpubOptions（object）作为参数，并支持以下属性：

import { ExportEpub } from '@tiptap-pro/extension-export-epub'

const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    ExportEpub.configure({
      endpoint: 'https://api.tiptap.dev/v2/convert',
      token: 'YOUR_TOKEN',
      appId: 'YOUR_APP_ID',
      styleOverrides: {},
      headers: {},
      footers: {},
      pageSize: { width: '21cm', height: '29.7cm' },
      pageMargins: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' },
      customNodes: [],
      onCompleteExport: (result) => {
        // 处理导出的 Blob
      },
    }),
    // 其他扩展 ...
  ],
})

参数	类型	描述	默认值
`endpoint`	`string`	用于转换的 Tiptap API 端点	`'https://api.tiptap.dev/v2/convert'`
`token`	`string`	用于身份验证的 Tiptap JWT	`''`
`appId`	`string`	用于身份验证的 Tiptap App ID	`''`
`styleOverrides`	`Record<string, string>`	要应用到导出的样式覆盖	`undefined`
`headers`	`HeaderConfig`	导出文档的页眉配置	`undefined`
`footers`	`FooterConfig`	导出文档的页脚配置	`undefined`
`pageSize`	`PageSize`	页面尺寸配置	`undefined`
`pageMargins`	`PageMargins`	页面边距配置	`undefined`
`customNodes`	`CustomNodeDefinition[]`	用于基于 DOCX 的转换的自定义节点定义（需要 `@tiptap-pro/extension-export-docx`）	`undefined`
`onCompleteExport`	`(result: Blob) => void`	接收导出文件 Blob 的回调	未提供时抛出错误

HeaderConfig

属性	类型	描述
`evenAndOddHeaders`	`boolean`	是否为奇数页和偶数页使用不同的页眉
`differentFirstPage`	`boolean`	是否在首页使用不同的页眉。设置为 `true` 时，第一页将使用 `first` 的值而不是 `default`。
`default`	`string`	每页的标准默认页眉，或在启用 `evenAndOddHeaders` 时奇数页的页眉。可接受纯文本字符串或字符串化的 Tiptap JSONContent，用于富文本格式。
`first`	`string`	首页的页眉。仅在 `differentFirstPage` 设置为 `true` 时使用。可接受纯文本字符串或字符串化的 Tiptap JSONContent，用于富文本格式。
`even`	`string`	启用 `evenAndOddHeaders` 选项时偶数页的页眉。可接受纯文本字符串或字符串化的 Tiptap JSONContent，用于富文本格式。

FooterConfig

属性	类型	描述
`evenAndOddFooters`	`boolean`	是否为奇数页和偶数页使用不同的页脚
`differentFirstPage`	`boolean`	是否在首页使用不同的页脚。设置为 `true` 时，第一页将使用 `first` 的值而不是 `default`。
`default`	`string`	每页的标准默认页脚，或在启用 `evenAndOddFooters` 时奇数页的页脚。可接受纯文本字符串或字符串化的 Tiptap JSONContent，用于富文本格式。
`first`	`string`	首页的页脚。仅在 `differentFirstPage` 设置为 `true` 时使用。可接受纯文本字符串或字符串化的 Tiptap JSONContent，用于富文本格式。
`even`	`string`	启用 `evenAndOddFooters` 选项时偶数页的页脚。可接受纯文本字符串或字符串化的 Tiptap JSONContent，用于富文本格式。

PageSize

属性	类型	描述	默认值
`width`	`string`	页面宽度。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"21cm"`
`height`	`string`	页面高度。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"29.7cm"`

PageMargins

属性	类型	描述	默认值
`top`	`string`	页面的上边距。可以为负数。必须是一个数字，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`bottom`	`string`	页面的下边距。可以为负数。必须是一个数字，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`left`	`string`	页面的左边距。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`right`	`string`	页面的右边距。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`

导出 EPUB 文件

安装扩展后，你可以使用 exportEpub 命令将编辑器内容导出为 .epub。

/**
 * 通过 Tiptap convert 服务将当前文档导出为 EPUB 文件。
 *
 * @param options - 所有扩展级选项都可以在单次调用中覆盖
 * @example editor.commands.exportEpub({ onCompleteExport: (result) => {} })
 */
exportEpub: (options?: ExportEpubCommandOptions) => ReturnType

ExportEpubCommandOptions 接口扩展了 ExportEpubOptions，因此每个配置项都可以在单次命令调用中被覆盖：

属性	类型	描述
`endpoint`	`string`	覆盖此特定导出的 API 端点
`token`	`string`	覆盖此特定导出的 JWT 令牌
`appId`	`string`	覆盖此特定导出的 App ID
`styleOverrides`	`Record<string, string>`	覆盖此特定导出的样式覆盖
`headers`	`HeaderConfig`	覆盖此特定导出的页眉配置
`footers`	`FooterConfig`	覆盖此特定导出的页脚配置
`pageSize`	`PageSize`	覆盖此特定导出的页面尺寸
`pageMargins`	`PageMargins`	覆盖此特定导出的页面边距
`customNodes`	`CustomNodeDefinition[]`	覆盖此特定导出的自定义节点定义
`onCompleteExport`	`(result: Blob) => void`	覆盖此特定导出的回调

import { ExportEpub } from '@tiptap-pro/extension-export-epub'

const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    ExportEpub.configure({
      token: 'YOUR_TOKEN',
      appId: 'YOUR_APP_ID',
      onCompleteExport(result) {
        // 下载 EPUB 文件
        const url = URL.createObjectURL(result)
        const a = document.createElement('a')

        a.href = url
        a.download = 'document.epub'
        a.click()

        URL.revokeObjectURL(url)
      },
    }),
    // 其他扩展 ...
  ],
})

// 使用扩展级回调
editor.chain().exportEpub().run()

// 或为特定导出覆盖选项
editor
  .chain()
  .exportEpub({
    pageSize: { width: '8.5in', height: '11in' },
    onCompleteExport(result) {
      // 此特定导出的自定义处理
      const url = URL.createObjectURL(result)
      window.open(url)
    },
  })
  .run()

工作原理

当你调用 exportEpub 时，扩展会将编辑器的文档和任何已配置的选项（样式覆盖、页面布局、页眉、页脚）发送到 Convert 服务，Convert 服务会返回生成的 .epub 文件，形式为二进制 blob。onCompleteExport 回调会直接接收该 blob。错误会以异常形式抛出，而不是通过回调传递。

预期内容

需要认证（token JWT 和 appId）。请在服务器端生成 JWT。请参阅转换安装指南。
需要处理的 HTTP 响应： 401（缺少或无效的 JWT）、403（该操作不允许你的应用执行——通常是你的计划未包含的格式）、5xx（临时性服务器端错误；请使用退避策略重试）。
每个请求在响应前都会端到端处理完成。 对于较长的文档，请预留更长的往返时间。

不应期待的内容

按章节的元数据自定义。 EPUB 元数据（书名、作者、语言、自定义章节 spine）目前还不能通过导出选项进行配置。
在不同阅读应用中达到像素级一致的渲染。 EPUB 渲染取决于阅读应用；不同应用和设备之间的间距、字体回退和图像缩放会有所差异。请针对你的受众所使用的阅读器进行测试。

支持与限制

功能	支持情况
文本内容	✓ 基本文本、间距、标点符号
文本格式	✓ 粗体、斜体、下划线、删除线、对齐方式、行高
块级元素	✓ 段落、标题（1–6）、引用块、有序列表和无序列表
表格	✓ 基本结构、表头行、跨列合并
链接	✓ 超链接
媒体（图片）	✓ 嵌入图片，保留尺寸
样式	✓ 字体族*、字体颜色、字体大小、背景颜色、行高
页眉与页脚	✓
数学公式	✓
分页符	✓
章节	✗
脚注与尾注	✗
批注与修订	✗
目录	✗
高级格式	✗ 分栏、文字方向、表单、宏、嵌入脚本
元数据	✗
文本框、形状、SmartArt	✗

只要在导出文件打开时，目标字体已安装在操作系统上，就支持字体族。

如需按功能查看详细说明，请参阅支持的功能矩阵。请注意，DOCX 导出扩展中可用的元素覆盖（paragraphOverrides、textRunOverrides、tableOverrides、tableCellOverrides、imageOverrides）不会传递到 EPUB 转换中。

PreviouslyREST API

Next upREST API