x-pdf-s PDF合成

把图片组、文本或图文叠字合成 PDF。可选图片水印，以及删页、调序、合并。

识别文字请在业务页调用 x-ocr-s，再把结果交给 textToPdf，插件不依赖 OCR。

兼容性

Harmony	IOS	Android	WEB	小程序
支持	支持	支持	空实现	空实现

调用

import { imagesToPdf, textToPdf, imageTextToPdf } from "@/uni_modules/x-pdf-s"

imagesToPdf({
  paths: imagePaths,
  watermark: {
    path: watermarkPath,
    size: 96,
    position: "bottomRight",
    opacity: 0.35
  },
  success: (res) => {
    console.log(res.path, res.pageCount)
  }
})

图文叠字（底图淡化，文字盖在上面）：

imageTextToPdf({
  pages: [
    { path: imgPath, text: pageText, texts: pageTexts, lines: pageLines }
  ],
  imageOpacity: 0.35,
  success: (res) => {
    console.log(res.path, res.pageCount)
  }
})

方法

名称	说明
imagesToPdf	一图一页合成 PDF（纸质归档）
textToPdf	文本分页合成 PDF（纯文本另页）
imageTextToPdf	一图一页：淡化底图 + 叠字，imageOpacity 控制底图透明度
removePdfPages	按 0 起始页码删页
reorderPdfPages	按新页序重排
mergePdfs	按顺序合并多个 PDF

imageTextToPdf 的 pages[]：path 必填；text / texts / lines 任选。lines.box 有八点坐标时按原图位置叠字（字号跟框高走，上限 28 点），否则按页排 text。imageOpacity 0–1，默认 0.35。鸿蒙叠字底图不竖直翻转。叠字 PDF 底图会按长边缩小后再淡化，存档原图不变。iOS 上 pages / lines 先序列化成 JSON 再读字段，不要把 Options 强转成 UTSJSONObject。业务页可以直接传 OCR 行对象。

水印

watermark.path 为图片。size 是宽度 pt，默认 96。position：topLeft / topRight / bottomLeft / bottomRight。opacity 0–1，默认 0.35。

平台差异

1. Web、微信仅空签名，回调 1005。
2. 安卓删页/调序/合并会栅格化原页后再写，复杂矢量可能变图片。
3. 鸿蒙按页拷贝。iOS 文本 / 叠字走 UIGraphicsPDFRenderer 写入沙盒 Caches（叠字在后台线程）；删页 / 调序 / 合并按页拷贝。

更新日志

0.1.25（2026-09-11）

• 修「叠字整体往下掉、偏下约 3/4 个字高」。落点原来算的是「检测框中心 ± 半个字号」：PDF 的 y 是从页底往上算的，而这一项按「y 向下」写成了 框底 - 框高/2 + 字号/2，等于把落点压到框底下面一截 —— 实测比正确基线低约 0.58 个字高，和真机上看到的「偏下 3/4 个字」一致。
• 现在三端都优先钉在 OCR 量出来的基线上（XPdfTextLine 新增可选 baseline / inkTop / inkH，由 x-correct-s 的 OCR 结果透传）：基线是按墨迹算的，和检测框的位置无关，框偏下、框里混进上下标都不会带偏。没给基线才退回墨迹带底，最后才退回「按框居中」。
  • 鸿蒙：addTextObject 直接吃基线（页底往上算）；
  • Android：Canvas.drawText 的 baseline（视图坐标，从上往下算）；
  • iOS：NSString.draw(at:) 的点是文字框左上角，所以从基线往上退一个 ascender；顺带修掉原来「从框顶再退 ascent」把字整体抬高的问题。
• XPdfTextLine 去掉恒为空串的 latex（x-correct-s 的公式识别已下线，这个字段是它留下的空壳，本版起不再透传）。kind 保留。

0.1.24（2026-09-11）

• 叠字 PDF 的字号不再夹在 8–28 点，改成 框高(图片像素) × fontScale × 图片到页面的缩放，框越高字越大，和原图比例一致；预览叠字用同一个 0.85 系数，两边对得上。
• 新增 minFontPt：等比换算后小于它才用它兜底，避免缩得太小看不清。默认 10pt，不影响坐标。
• 新增 textOnly：纯文本模式不画底图，页面尺寸按图片比例（最长边 842pt）且不套页边距，文字按原图位置与大小等比输出。适合要「可选中纯文字、位置尺寸同图」的场合；此时 paperSize / margin / imageOpacity 不起作用。
• 新增 fontScale：框高到字号的系数，默认 0.85，可 0.3–1.5 之间调。
• 有坐标行的文字改为按框居中，框不够宽时整行横向压扁（先缩字号、再压字距），不再截断或溢出。
• XPdfTextLine 增加 kind / latex 两个可选字段，供上层把行类型与公式原文一路带到 PDF 层（本版只透传，PDF 里画的仍是 text）。

0.1.23（2026-09-09）

• iOS 合成不再对相册 / 扫描的沙箱绝对路径走 convert2AbsFullPath，文件已存在就直接读。避免和安卓一样报「图片读取失败」。

0.1.22（2026-09-09）

• 安卓改为 Kotlin 后台线程合成：当前线程先 JSON.stringify，避免 UTS 对象在 IO dispatcher 里序列化卡死。PDF 固定写到应用 cacheDir。

0.1.21（2026-09-08）

• 安卓合成 / 删页 / 调序 / 合并改到 IO 线程，完成后再回主线程回调。避免挡住 showLoading，转圈不再假死。

0.1.20（2026-09-08）

• 安卓合成不再对相册 / 扫描的沙箱绝对路径走 convert2AbsFullPath，避免被当成包内相对路径拼坏后报「图片读取失败」。file:// 会解码，content:// 原样交给 BitmapFactory。大图按长边抽样，避免整图解码失败。

0.1.19（2026-08-20）

• iOS 图文叠字不再把 options 强转成 UTSJSONObject。Options 是 Swift 类型，as! 会闪退。页面数组改为 JSON.stringify 后再按 JSON 读字段。

0.1.18（2026-08-20）

• iOS 图文叠字按 OCR 写法处理页面数组：先 item = pages[i]，再用 UTSJSONObject 读 path / text / lines。不再写 options.pages[i].path，避免页面对象实际是字典时闪退。

0.1.17（2026-08-20）

• iOS 图文叠字不再把 pages[].lines 当成 XPdfTextLine[] 下标读取。对象字面量在 iOS 上是字典，强制转换会闪退（Expected XPdfTextLine but found __NSDictionaryM）。

0.1.16（2026-08-20）

• 安卓图文叠字按 OCR 框高写字（0.85，上限 28 点），不再被默认 12 点正文卡住，对齐 iOS/鸿蒙观感。

0.1.15（2026-08-20）

• iOS 文本 PDF 不再把 draw(with:options:) 栅格化进页。改为 UIGraphicsPDFRenderer 按行写入真实文字，避免页里出现 options(...) 和乱码符号。
• iOS 叠字 PDF 改到后台线程，底图长边缩到 1600，不再主线程 scale=2 双份位图，避免高清图闪退。

0.1.14（2026-08-20）

• 鸿蒙叠字 PDF 不再在主线程手写 4K PNG。底图先缩到 2048 再用 ImageKit 出 JPEG，避免 THREAD_BLOCK_6S 闪退。叠字坐标仍按原图。
• 安卓 / iOS 叠字底图同样按长边缩小后再画，存档原图不变。

0.1.13（2026-08-20）

• 鸿蒙图文叠字不再竖直翻转整页底图。水印仍翻正；底图再翻一次会倒过来，文字和水印却是正的。

0.1.12（2026-08-20）

• 新增 imageTextToPdf：底图降低透明度，文字叠在图上；imageOpacity 0–1 可调。有 OCR 框按原位置写，没有则按页排字。

0.1.11（2026-08-18）

• iOS 图片 / 文本合成去掉 drawPdfPages 里多余的 Y 轴翻转，图片、文本、水印不再整页倒置。
• 鸿蒙文本改用有效字体路径（font.getFontByName('HarmonyOS Sans')，兜底 /system/fonts/HarmonyOS_Sans.ttf），修复文本写入 PDF 后空白。
• 鸿蒙按 PdfPage 左下原点重排：文本首行置顶逐行向下，水印四角定位修正（默认底右）。
• 鸿蒙水印自绘 PNG 落图前竖直翻正，修复水印上下颠倒。

0.1.10（2026-08-18）

• 鸿蒙 PDF 固定写到应用 cacheDir/x-pdf-s/，file:// 先转沙箱路径，避免 1004 写入失败。

0.1.9（2026-08-18）

• iOS 合并 / 删页 / 调序改为 CGContext.drawPDFPage 原页拷贝，不再栅格化翻转，避免图倒过来。

0.1.8（2026-08-18）

• 鸿蒙数组元素补显式类型；水印解码改用 DecodingOptions.desiredPixelFormat。

0.1.7（2026-08-18）

• iOS 合并先把 thumbnail 竖直翻正再按合成同一套写入，对消 PDF 页图和 CGPDFContext 的 Y 轴差。

0.1.6（2026-08-18）

• iOS 删页 / 调序 / 合并改为 CGContext.drawPDFPage 按页拷贝，不再把页栅格化后再翻转写入。

0.1.5（2026-08-18）

• iOS 删页 / 调序 / 合并改为 PDFPage.thumbnail 取正立页图再写入，避免手写 Y 翻转把文字和水印倒过来。

0.1.4（2026-08-18）

• iOS 合成改为 Core Graphics CGPDFContext 写入沙盒 Caches，不再走 PDFKit write / dataRepresentation。

0.1.3（2026-08-18）

• 合成输出路径先转成绝对路径，iOS 改为 dataRepresentation 落盘，避免 1004 写入失败。

0.1.2（2026-08-18）

• iOS 合成、删页、调序、合并不再走 UIGraphics PDF 上下文，改为位图页 + PDFPage(image:) 写入，避免 Could not create CGContextRef。

0.1.1（2026-08-18）

• iOS 删页、调序、合并改为按页绘制写入，避免 UIGraphics 生成的 PDF 再 copy 时出现 Could not create CGContextRef。

0.1.0（2026-08-18）

• 新增图片组合成 PDF、文本合成 PDF。
• 合成时可配图片水印：大小、四角位置、透明度。
• 支持删页、调序、合并；Web / 微信先返回平台不支持。
• OCR 不内置，由页面调用 x-ocr-s 后再走 textToPdf。