@composy/html2pdf-vue

@composy/html2pdf-vue

Vue 3 适配层，基于 @composy/html2pdf-core 提供 Composition API、模板指令和全局插件。实际 DOM 捕获、分页、PDF/图片编码仍由 Core 完成。

安装

pnpm add @composy/html2pdf-vue

vue 是 peer dependency，Core 由本包自动依赖。若只在非 Vue 页面使用，请直接安装 @composy/html2pdf-core。

公共 API

useHtml2Pdf

<script setup lang="ts">
import { useHtml2Pdf } from '@composy/html2pdf-vue'
import { ref } from 'vue'

const report = ref<HTMLElement | null>(null)
const { exportToPdf, exporting, progress, error, abort } = useHtml2Pdf({
  defaultOptions: {
    waitForFonts: true,
    waitForImages: true,
    resourceTimeoutMs: 5_000,
    maxPages: 40
  },
  cancelPrevious: true
})

async function download() {
  if (!report.value) return
  await exportToPdf(report.value, {
    filename: 'report.pdf',
    hooks: {
      onProgress: value => console.info(value.phase, value.ratio)
    }
  })
}
</script>

<template>
  <section ref="report">
    <h1>Report</h1>
    <!-- eslint-disable-next-line vue/singleline-html-element-content-newline -->
    <p>Content exported by the Vue adapter.</p>
  </section>
  <!-- eslint-disable-next-line vue/singleline-html-element-content-newline -->
  <button :disabled="exporting" type="button" @click="download">Export PDF</button>
  <!-- eslint-disable-next-line vue/singleline-html-element-content-newline -->
  <button type="button" @click="abort">Cancel</button>
  <progress v-if="progress" :value="progress.ratio" max="1" />
  <!-- eslint-disable-next-line vue/singleline-html-element-content-newline -->
  <p v-if="error">Export failed: {{ String(error) }}</p>
</template>

defaultOptions 支持普通对象或 MaybeRef<Html2PdfOptions>。每次导出会对默认配置和本次覆盖项做嵌套合并，默认保留 pdf、page、image、compat、html2canvas 与 hooks 中未被覆盖的字段。

cancelPrevious 默认为 true：同一个 composable 再次导出时会取消上一次任务。设置为 false 可允许并发任务；abort() 会取消当前 composable 管理的全部任务，组件卸载时也会自动执行清理。

vHtml2Pdf

<script setup lang="ts">
import { vHtml2Pdf } from '@composy/html2pdf-vue'

const value = {
  source: () => document.querySelector<HTMLElement>('#print-area'),
  options: {
    filename: 'page.pdf',
    waitForImages: true
  },
  cancelPrevious: true,
  onProgress: progress => console.info(progress.ratio),
  onDone: result => console.info(result.pageCount),
  onError: error => console.error(error)
}
</script>

<template>
  <!-- eslint-disable-next-line vue/singleline-html-element-content-newline -->
  <div id="print-area">Export content</div>
  <!-- eslint-disable-next-line vue/singleline-html-element-content-newline -->
  <button v-html2Pdf="value" type="button">Export PDF</button>
</template>

指令行为：

• mounted 保存绑定值并监听 click。
• 每次点击创建独立 AbortController，将 signal 合并到 Core options，并透传 onProgress。
• cancelPrevious 默认开启时，会取消同一元素上尚未结束的导出；关闭后允许并发导出。
• updated 使用最新绑定值，下一次点击立即生效。
• unmounted 移除监听并取消该元素的所有未完成任务，避免卸载后继续渲染或下载。

全局插件

import Html2PdfVue from '@composy/html2pdf-vue'
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).use(Html2PdfVue).mount('#app')

注册插件后可以使用 v-html2pdf（小写）指令；局部使用时从包中导入 vHtml2Pdf 并绑定 v-html2Pdf 也可以正常工作。

与 Core 的边界

Vue 适配器不复制渲染逻辑。分页、资源等待、跨 iframe、预算限制、AbortSignal、资源错误策略和进度阶段均使用 Core 的同一套类型与实现；需要在 React、Lit 或 Vanilla 中复用时，应直接使用 Core。

验证命令

在 libraries/html2pdf 根目录执行：

pnpm run lint:check
pnpm run format:check
pnpm run type-check
pnpm run test:run
pnpm run build
pnpm run docs:build
pnpm run type-check:playground
pnpm run playground:build

Vue 包和 Core 包均使用仓库统一的 @composy/builder + rolldown，并生成 dist、es、esm、lib 四套发布产物。