{"id":19937104,"url":"https://github.com/oldj/wp-epub-gen","last_synced_at":"2026-06-08T08:34:15.319Z","repository":{"id":57690427,"uuid":"473954742","full_name":"oldj/wp-epub-gen","owner":"oldj","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-03T05:58:07.000Z","size":1417,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-03T07:27:25.849Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oldj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-03-25T09:56:09.000Z","updated_at":"2026-05-03T05:58:11.000Z","dependencies_parsed_at":"2024-11-12T23:31:18.249Z","dependency_job_id":"bbc361c3-1034-494b-bfa9-f6ea2a9e2168","html_url":"https://github.com/oldj/wp-epub-gen","commit_stats":{"total_commits":9,"total_committers":1,"mean_commits":9.0,"dds":0.0,"last_synced_commit":"a09a2ee98db233d5646e3d973e47127c2794739b"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/oldj/wp-epub-gen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oldj%2Fwp-epub-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oldj%2Fwp-epub-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oldj%2Fwp-epub-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oldj%2Fwp-epub-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oldj","download_url":"https://codeload.github.com/oldj/wp-epub-gen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oldj%2Fwp-epub-gen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34055249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T23:30:55.043Z","updated_at":"2026-06-08T08:34:15.314Z","avatar_url":"https://github.com/oldj.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wp-epub-gen\n\n基于 [epub-gen](https://github.com/cyrilis/epub-gen/) 改进的 EPUB 生成器，支持 TypeScript 和现代 ES 模块。\n\n## 安装\n\n使用 npm 安装：\n\n```bash\nnpm install wp-epub-gen --save\n```\n\n## 基本使用\n\n### JavaScript (CommonJS)\n\n```javascript\nconst { epubGen } = require(\"wp-epub-gen\");\n\nepubGen({\n  title: \"我的电子书\",\n  author: \"作者名\",\n  output: \"./my-book.epub\",\n  content: [\n    {\n      title: \"第一章\",\n      data: \"\u003ch1\u003e第一章\u003c/h1\u003e\u003cp\u003e这是第一章的内容...\u003c/p\u003e\"\n    }\n  ]\n}).then(\n  () =\u003e console.log(\"电子书生成成功！\"),\n  err =\u003e console.error(\"生成失败：\", err)\n);\n```\n\n### TypeScript / ES 模块\n\n```typescript\nimport { epubGen, type IEpubGenOptions } from 'wp-epub-gen';\n\nconst options: IEpubGenOptions = {\n  title: \"我的电子书\",\n  author: \"作者名\",\n  output: \"./my-book.epub\",\n  content: [\n    {\n      title: \"第一章\",\n      data: \"\u003ch1\u003e第一章\u003c/h1\u003e\u003cp\u003e这是第一章的内容...\u003c/p\u003e\"\n    }\n  ]\n};\n\ntry {\n  const result = await epubGen(options);\n  if (result.success) {\n    console.log(\"电子书生成成功！\");\n  } else {\n    console.error(\"生成失败：\", result.message);\n  }\n} catch (error) {\n  console.error(\"发生错误：\", error);\n}\n```\n\n### 完整示例\n\n```typescript\nimport { epubGen } from 'wp-epub-gen';\n\nconst options = {\n  title: \"完整示例电子书\",\n  author: [\"张三\", \"李四\"],\n  publisher: \"我的出版社\",\n  cover: \"https://example.com/cover.jpg\",\n  output: \"./complete-book.epub\",\n  version: 3,\n  lang: \"zh-cn\",\n  css: \"body { font-family: 'Microsoft YaHei', sans-serif; }\",\n  tocTitle: \"目录\",\n  appendChapterTitles: true,\n  tocAutoNumber: true,\n  verbose: true,\n  timeoutSeconds: 60,\n  content: [\n    {\n      title: \"前言\",\n      data: \"\u003ch1\u003e前言\u003c/h1\u003e\u003cp\u003e这是前言内容...\u003c/p\u003e\",\n      beforeToc: true\n    },\n    {\n      title: \"第一部分\",\n      data: \"\u003ch1\u003e第一部分\u003c/h1\u003e\",\n      children: [\n        {\n          title: \"第一章\",\n          data: \"\u003ch2\u003e第一章\u003c/h2\u003e\u003cp\u003e第一章内容...\u003c/p\u003e\"\n        },\n        {\n          title: \"第二章\", \n          data: \"\u003ch2\u003e第二章\u003c/h2\u003e\u003cp\u003e第二章内容...\u003c/p\u003e\"\n        }\n      ]\n    },\n    {\n      title: \"第二部分\",\n      data: \"\u003ch1\u003e第二部分\u003c/h1\u003e\u003cp\u003e第二部分内容...\u003c/p\u003e\"\n    },\n    {\n      title: \"附录\",\n      data: \"\u003ch1\u003e附录\u003c/h1\u003e\u003cp\u003e附录内容...\u003c/p\u003e\",\n      excludeFromToc: true\n    }\n  ]\n};\n\nepubGen(options).then(result =\u003e {\n  if (result.success) {\n    console.log(\"电子书生成成功！\");\n  }\n});\n```\n\n## API 参考\n\n### epubGen(options, configs?)\n\n主要的 EPUB 生成函数。\n\n**参数：**\n- `options: IEpubGenOptions` - 配置选项对象（标题、作者、封面、章节内容等）\n- `configs?: IGenConfigs` - 可选的运行时回调（logger、onProgress、concurrency），见下文 [IGenConfigs](#igenconfigs-运行时回调)\n\n**返回值：**\n- `Promise\u003cIOut\u003e` - 包含生成结果的 Promise\n\n### IEpubGenOptions 配置选项\n\n#### 必需参数\n\n- **`title: string`** - 电子书标题\n- **`output: string`** - 输出文件路径（绝对路径）\n- **`content: IChapter[]`** - 章节内容数组\n\n#### 可选参数\n\n- **`author?: string | string[]`** - 作者名称，可以是字符串或字符串数组\n  - 示例：`\"张三\"` 或 `[\"张三\", \"李四\"]`\n\n- **`publisher?: string`** - 出版社名称\n\n- **`cover?: string`** - 封面图片\n  - 支持网络 URL：`\"https://example.com/cover.jpg\"`\n  - 支持本地文件：`\"/path/to/cover.jpg\"`\n\n- **`version?: 2 | 3`** - EPUB 版本\n  - `3`：最新版本（默认）\n  - `2`：兼容老设备\n\n- **`lang?: string`** - 语言代码\n  - 默认：`\"en\"`\n  - 中文：`\"zh-cn\"`\n\n- **`css?: string`** - 自定义 CSS 样式\n  - 示例：`\"body { font-family: 'Microsoft YaHei'; }\"`\n\n- **`fonts?: string[]`** - 自定义字体文件路径数组\n  - 示例：`[\"/path/to/font.ttf\"]`\n  \n  使用方法：\n  ```css\n  @font-face {\n    font-family: \"CustomFont\";\n    src: url(\"./fonts/font.ttf\");\n  }\n  ```\n\n- **`tocTitle?: string`** - 目录标题\n  - 默认：`\"Table Of Contents\"`\n\n- **`appendChapterTitles?: boolean`** - 是否在章节开头自动添加标题\n  - 默认：`true`\n\n- **`tocAutoNumber?: boolean`** - 目录是否自动编号\n  - 默认：`false`\n\n- **`verbose?: boolean`** - 是否输出详细日志\n  - 默认：`false`\n\n- **`timeoutSeconds?: number`** - 超时时间（秒）\n  - `0` 表示无超时\n  - 默认：`900`（15分钟）\n\n- **`description?: string`** - 电子书描述\n\n- **`date?: string`** - 出版日期（ISO 格式）\n\n- **`tmpDir?: string`** - 临时目录路径\n\n#### 高级自定义选项\n\n- **`customOpfTemplatePath?: string`** - 自定义 OPF 模板文件路径\n- **`customNcxTocTemplatePath?: string`** - 自定义 NCX 目录模板文件路径  \n- **`customHtmlTocTemplatePath?: string`** - 自定义 HTML 目录模板文件路径\n\n### IChapter 章节对象\n\n每个章节对象可以包含以下属性：\n\n#### 必需属性\n\n- **`data: string`** - 章节的 HTML 内容\n  - 网络图片：`\u003cimg src=\"https://example.com/image.jpg\" /\u003e`\n  - 本地图片：`\u003cimg src=\"file:///path/to/image.jpg\" /\u003e`\n\n#### 可选属性\n\n- **`id?: string`** - 唯一标识符\n- **`title?: string`** - 章节标题\n- **`author?: string | string[]`** - 章节作者（覆盖全局作者）\n- **`filename?: string`** - 自定义文件名\n- **`excludeFromToc?: boolean`** - 是否从目录中排除（默认：`false`）\n- **`beforeToc?: boolean`** - 是否显示在目录之前（如版权页）（默认：`false`）\n- **`appendChapterTitle?: boolean`** - 覆盖全局的 `appendChapterTitles` 设置\n- **`children?: IChapter[]`** - 子章节数组（用于创建层级结构）\n\n### 返回值类型 IOut\n\n```typescript\ninterface IOut {\n  success?: boolean;     // 是否成功\n  message?: string;      // 错误信息（如果失败）\n  options?: IEpubGenOptions; // 使用的配置选项\n}\n```\n\n### IGenConfigs 运行时回调\n\n`epubGen` 的第二个参数，用于注入宿主侧的回调和并发配置。所有字段都是可选的。\n\n```typescript\ninterface IGenConfigs {\n  logger?: ILogger;\n  onProgress?: (e: IProgressEvent) =\u003e void;\n  concurrency?: number;\n}\n```\n\n#### `logger?: ILogger`\n\n注入自定义日志记录器（替代默认 `console`）。常用于 Electron 主进程把日志转发到渲染进程。\n\n```typescript\ninterface ILogger {\n  log: (msg: any) =\u003e void;\n  info: (msg: any) =\u003e void;\n  warn: (msg: any) =\u003e void;\n  error: (msg: any) =\u003e void;\n}\n```\n\n#### `onProgress?: (e: IProgressEvent) =\u003e void`\n\n进度回调。生成过程会在 5 个阶段中分别推送事件，宿主可据此渲染进度条或转发 IPC 给 UI。\n\n```typescript\ntype ProgressPhase =\n  | 'parseContent'    // 解析章节 HTML\n  | 'writeChapters'   // 写章节临时文件\n  | 'buildToc'        // 渲染 OPF / NCX / TOC\n  | 'downloadImage'   // 下载图片（仅当存在图片时）\n  | 'zip'             // 打包 .epub\n\ninterface IProgressEvent {\n  phase: ProgressPhase;\n  current: number;     // 已完成数量\n  total: number;       // 总数量\n  label?: string;      // 当前条目标签（章节标题 / 图片 URL）\n}\n```\n\n最小用法：\n\n```typescript\nawait epubGen(options, {\n  onProgress: (e) =\u003e {\n    console.log(`[${e.phase}] ${e.current}/${e.total}`);\n  },\n});\n```\n\n回调中抛出的异常会被库静默吞掉，不会中断 EPUB 生成。\n\n#### `concurrency?: number`\n\n写章节文件和下载图片所共用的并发上限。默认 `16`，机械硬盘或带宽受限场景可调小（如 `4`）。非有限正整数（NaN、负数等）会被自动归一化为默认值。\n\n## 导出的类型\n\n库导出了所有 TypeScript 类型定义：\n\n```typescript\nimport type {\n  IEpubGenOptions,\n  IChapter,\n  IChapterData,\n  IEpubData,\n  IEpubImage,\n  IGenConfigs,\n  ILogger,\n  IProgressEvent,\n  ProgressPhase,\n  IOut,\n} from 'wp-epub-gen';\n```\n\n## 错误处理\n\n```typescript\nimport { epubGen, errors } from 'wp-epub-gen';\n\nconst result = await epubGen(options);\n\nif (!result.success) {\n  switch (result.message) {\n    case errors.no_title:\n      console.error(\"缺少标题\");\n      break;\n    case errors.no_output_path:\n      console.error(\"缺少输出路径\");\n      break;\n    case errors.no_content:\n      console.error(\"缺少内容\");\n      break;\n    default:\n      console.error(\"未知错误：\", result.message);\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foldj%2Fwp-epub-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foldj%2Fwp-epub-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foldj%2Fwp-epub-gen/lists"}