更新记录

1.0.0（2026-05-16）

• 发布 HTML / Markdown 转 PDF、DOCX 的基础能力。
• 支持 Android、iOS、HarmonyOS 和 Web 端常用导出场景。
• 提供文件输入、进度回调、取消转换、能力判断、Web Blob URL 释放和调试日志开关。
• 补充使用文档、错误码和平台限制说明。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

hans-docify

hans-docify 是一个 HTML / Markdown 转 PDF、DOCX 的 uni-app / uni-app x UTS 插件，适合在 App、HarmonyOS 和 Web 端生成报告、合同、说明文档等文件。

支持平台

调用前可以用 isDocifySupportedSync(format) 做能力判断。

import { isDocifySupportedSync } from '@/uni_modules/hans-docify'

const canExportPdf = isDocifySupportedSync('pdf')
const canExportDocx = isDocifySupportedSync('docx')

安装与导入

把插件放入项目的 uni_modules/hans-docify 目录后，在页面或业务模块中导入需要的 API：

import {
  convertDocument,
  convertHtmlToPdf,
  convertMarkdownToPdf,
  convertHtmlToDocx,
  convertMarkdownToDocx,
  revokeObjectUrl,
} from '@/uni_modules/hans-docify'

页面里也可以直接从插件入口导入公共类型，不需要引用 utssdk/interface.uts：

import type {
  DocifyChartSnapshotOptions,
  DocifyConvenienceOptions,
  DocifyConvertOptions,
  DocifyConvertResult,
  DocifyFail,
  DocifyMargins,
  DocifyProgress,
  DocifyStyleOptions,
} from '@/uni_modules/hans-docify'

const margins: DocifyMargins = { top: 24, right: 24, bottom: 24, left: 24 }

const style: DocifyStyleOptions = {
  title: '报告标题',
  pageSize: 'A4',
  margins,
}

const chartSnapshot: DocifyChartSnapshotOptions = {
  selector: '#chart',
  pixelRatio: 2,
  backgroundColor: '#ffffff',
}

const options: DocifyConvenienceOptions = {
  source: '<h1>报告</h1>',
  fileName: 'report.pdf',
  style,
  chartSnapshot,
  progress: (res: DocifyProgress) => {
    console.log(res.stage, res.progress)
  },
  success: (res: DocifyConvertResult) => {
    console.log(res.filePath)
  },
  fail: (err: DocifyFail) => {
    console.error(err.errCode, err.errMsg)
  },
}

convertHtmlToPdf(options)

const documentOptions: DocifyConvertOptions = {
  sourceType: 'html',
  source: '<h1>报告</h1>',
  format: 'docx',
  fileName: 'report.docx',
  style,
}

convertDocument(documentOptions)

快速开始

import { convertMarkdownToPdf, revokeObjectUrl } from '@/uni_modules/hans-docify'

const task = convertMarkdownToPdf({
  source: '# 报告\n\n- PDF\n- DOCX',
  fileName: 'report.pdf',
  progress: (res) => {
    console.log(res.stage, res.progress)
  },
  success: (res) => {
    console.log(res.filePath)

    // Web 端返回 Blob URL，不再使用时建议释放。
    if (res.filePath.startsWith('blob:')) {
      revokeObjectUrl(res.filePath)
    }
  },
  fail: (err) => {
    console.error(err.errCode, err.errMsg)
  },
})

// 如需取消转换：
// task.abort()

API

convertHtmlToPdf(options)

把 HTML 字符串转成 PDF。

convertHtmlToPdf({
  source: '<h1>月度报告</h1><p>这里是正文。</p>',
  fileName: 'monthly-report.pdf',
  style: {
    title: '月度报告',
    pageSize: 'A4',
    orientation: 'portrait',
    margins: { top: 24, right: 24, bottom: 24, left: 24 },
  },
  success: (res) => {
    console.log(res.filePath)
  },
})

convertMarkdownToPdf(options)

把 Markdown 字符串转成 PDF。

convertMarkdownToPdf({
  source: '# 会议纪要\n\n1. 议题一\n2. 议题二',
  fileName: 'meeting.pdf',
  success: (res) => {
    console.log(res.filePath)
  },
})

convertHtmlToDocx(options)

把 HTML 字符串转成 DOCX。

convertHtmlToDocx({
  source: '<h1>合同</h1><p><strong>甲方：</strong>示例公司</p>',
  fileName: 'contract.docx',
  style: {
    title: '合同',
    defaultFontFamily: 'Microsoft YaHei',
    defaultFontSize: 12,
  },
  success: (res) => {
    console.log(res.filePath)
  },
})

convertMarkdownToDocx(options)

把 Markdown 字符串转成 DOCX。

convertMarkdownToDocx({
  source: '# 产品说明\n\n支持标题、段落、列表、表格和链接。',
  fileName: 'product-guide.docx',
  success: (res) => {
    console.log(res.filePath)
  },
})

convertDocument(options)

通用转换 API。需要读取本地 .html、.htm、.md、.markdown 文件时使用 sourceType: 'file'。

convertDocument({
  sourceType: 'file',
  source: '/path/to/input.md',
  inputFormat: 'markdown',
  format: 'docx',
  fileName: 'from-file.docx',
  success: (res) => {
    console.log(res.filePath)
  },
})

App Android、App iOS、App HarmonyOS 会读取应用可访问的本地路径。Web 端不能直接读取任意本地路径，建议业务侧先读取文件内容，再用 sourceType: 'html' 或 sourceType: 'markdown' 传入。

revokeObjectUrl(url)

Web 端转换结果是 Blob URL。上传、下载或预览完成后，可以调用 revokeObjectUrl(url) 释放资源。

revokeObjectUrl(filePath)

setDocifyLogEnabled(enabled)

排查问题时可打开插件日志。日志只输出调用状态、进度、成功、失败、取消等信息，不输出完整 HTML / Markdown 正文。

import { setDocifyLogEnabled } from '@/uni_modules/hans-docify'

setDocifyLogEnabled(true)

可通过 isDocifyLogEnabledSync() 读取当前日志开关状态。

options 参数

style 参数

style: {
  title: '报告标题',
  baseUrl: 'https://example.com/',
  pageSize: 'A4',
  orientation: 'portrait',
  margins: { top: 24, right: 24, bottom: 24, left: 24 },
  defaultFontFamily: 'Microsoft YaHei',
  defaultFontSize: 12,
  css: 'body { line-height: 1.6; }'
}

图表和动态内容

如果 HTML 中有图表、异步渲染内容或远程资源，建议显式开启相关选项。

convertHtmlToDocx({
  source: html,
  fileName: 'chart-report.docx',
  allowJavaScript: true,
  allowRemoteResources: true,
  readyExpression: 'window.__CHART_READY === true',
  renderDelay: 300,
  chartSnapshot: {
    selector: '#chart',
    pixelRatio: 2,
    backgroundColor: '#ffffff',
  },
  success: (res) => {
    console.log(res.filePath)
  },
})

多个图表可以使用 selectors：

chartSnapshot: {
  selectors: ['#line-chart', '#bar-chart', '#pie-chart'],
  pixelRatio: 2,
  backgroundColor: '#ffffff',
}

返回结果

type DocifyConvertResult = {
  success: boolean
  format: 'pdf' | 'docx'
  filePath: string
  fileName: string
  mimeType: string
  size: number
  pages?: number
}

错误码

使用限制

• docxMode: 'snapshot' 目前支持 Android / iOS，HarmonyOS / Web 会返回 9090012。
• chartSnapshot 目前支持 Android / iOS；使用时必须设置 allowJavaScript: true。
• HarmonyOS PDF 需要 API 14+，建议在页面显示后调用；页面未准备好时可能返回 9090012。
• Web 端返回 Blob URL，不是持久文件路径；上传、下载或预览完成后建议调用 revokeObjectUrl(url)。
• 远程图片、字体、脚本等资源需要设置 allowRemoteResources: true，并确保设备网络和资源跨域策略允许访问。