Modify pdf toolbar in vue-pdf

近日，随着 Vue 生态中 PDF 预览需求的持续升温，开发者对核心组件 vue-pdf 的工具栏定制化呼声愈发高涨。默认情况下，vue-pdf 内置了一套标准工具栏，包含翻页、缩放、下载等按钮，但样式固定、功能冗余，难以满足企业级应用的 UI 统一与交互定制需求。如何高效修改工具栏，已成为前端社区热议的技术焦点。

默认工具栏的“尴尬”

vue-pdf 以其轻量、易用著称，默认导出一个 <pdf> 组件，并自动生成位于顶部的工具栏。该工具栏集成了页码输入框、缩放滑块、全屏切换及下载入口。然而，实际项目中常面临三大痛点：

视觉冲突：默认工具栏使用 Material Design 风格图标与浅灰背景，与深色主题、扁平化设计等企业应用格格不入。
功能冗余：部分应用仅需翻页或仅需注释功能，但无法单独禁用某一按钮。
交互受限：无法添加自定义操作（如旋转、打印、书签），也无法绑定业务逻辑。

破解之道：从“隐藏”到“重建”

经技术社区与 GitHub Issue 讨论，目前主流的改造方案可归纳为三类：

方案一：完全禁用内置工具栏 + 自行实现

借助 vue-pdf 的 :toolbar prop（部分版本为 show-toolbar），可将默认工具栏完全隐藏：

<template>
  <pdf
    :src="pdfUrl"
    :toolbar="false"
    ref="pdf"
  />
  <div class="custom-toolbar">
    <button @click="prevPage">上一页</button>
    <span>{{ currentPage }} / {{ totalPages }}</span>
    <button @click="nextPage">下一页</button>
  </div>
</template>

随后，开发者可完全自定义 HTML 结构与样式，并通过组件暴露的 currentPage、totalPages 及方法 prevPage()、nextPage() 实现交互。该方案最为灵活，但需要自行实现缩放、下载等高级功能（可借助 pdfjsLib 或后端接口）。

方案二：CSS 覆盖与隐藏

若不愿放弃内置功能，仅需调整视觉，可通过全局样式或深度选择器修改。例如隐藏缩放滑块：

.pdf-toolbar .zoom-input { display: none; }

但此方案依赖内部类名，可能随版本升级失效。建议使用 ::v-deep 穿透（Vue 2）或 :deep()（Vue 3）。部分高级按钮（如下载）在源码中不可见，仍需通过隐藏原生按钮后再用自定义图标覆盖。

方案三：升级至 `vue-pdf-embed` 并利用 slot

社区新秀 vue-pdf-embed 提供了更完善的插槽（slot）机制，允许开发者将自定义工具栏嵌入指定区域。例如：

<vue-pdf-embed :source="pdfUrl">
  <template #toolbar>
    <div class="my-toolbar">...</div>
  </template>
</vue-pdf-embed>

该库基于 PDF.js 最新版本，且支持注释层，是面向未来的推荐选择。

实战技巧：联动业务逻辑

修改工具栏时，常需结合用户权限与文档状态。例如：

角色控制：仅管理员显示“删除”按钮，普通用户仅可预览。
文档保护：禁止下载时，在自定义工具栏的下载按钮中检查 user.canDownload。
响应式适配：移动端移除缩放滑块，改用手势双指缩放。

此类逻辑可轻松在自定义工具栏组件中通过 v-if / v-show 实现，而无需 hack 原生代码。

兼容性与性能考量

实施自定义工具栏时需注意：

版本一致性：vue-pdf 4.x 与 5.x 的 API 有较大差异，建议锁定版本。
内存泄漏：手动绑定的事件（如 window resize）需在 beforeUnmount 中解绑。
渲染性能：若每页加载大量自定义元素，建议仅渲染当前页，并使用 keep-alive 缓存。

未来趋势：组件化与标准化

随着 Vue 3 的普及和 Web Components 的发展，预计 PDF 预览组件将提供更细粒度的 API。例如 @click:download 事件替代隐藏按钮的方式，或允许开发者传入自定义按钮数组。目前，vue-pdf 的 GitHub 仓库已有多项相关 PR 等待合入，社区开发者正推动这一进程。

结语

修改 vue-pdf 工具栏不再是“不可能的任务”。从隐藏重建到 CSS 覆盖，再到插槽升级，开发者可根据项目需求选择最适合的路径。无论采用哪种方案，核心目标始终不变：在保持 PDF 预览稳定性的同时，赋予前端团队完整的交互控制权。这不仅是技术实现，更是用户体验精细化的必然要求。