syncfusion-vue-pdf-viewer

Syncfusion Vue Pdfviewer – UI 示例生成器

目标包：@syncfusion/ej2-vue-pdfviewer

为用户的项目生成代码 （默认）

触发关键词：“如何”“添加 pdfviewer”“代码示例”“给我看看”“示例”“代码片段”“集成”“组件”“创建示例”“Vue 示例”。

**用途：**生成精简、可直接复制粘贴的 Vue SFC（.vue）代码，供用户直接集成到 Vue 2 或 Vue 3 项目中。

工作流： ⚠️ 关键 — 功能支持策略（严格模式）：

**基本规则：**只能使用参考文件中明确列出的 API 和属性生成代码。任何偏离均属违规。

• 生成任何代码前必须检查：

  1. 在参考文件中搜索确切的 API／属性名称
  2. 确认其出现在方法参考、属性或事件表中
  3. 如果任何参考文件中都没有，立即停止
  4. 在任何情况下都不得生成或建议未记录的 API

• 严格执行 — 零容忍：

  • 不得使用自定义属性——只能使用参考文件表格中的属性
  • 不得杜撰方法——只能使用参考文件表格中的方法
  • 不得使用未定义 API 进行变通——严禁
  • 不得假设未记录的行为——严禁
  • 不得凭猜测提供替代实现——严禁
  • 不得假装功能受支持——严禁

• 不受支持功能的强制回复：

  • 如果任何参考文件中都未列出所请求的场景／功能／API，必须回复：

    "当前 Syncfusion Vue PDF Viewer 实现不支持此功能。"
    

  • 然后列出相应参考文件中确实支持的内容
  • 除非参考文件中有明确记录，否则绝不建议替代方案

• 参考文件层级：

  • 每个参考文件都包含其所属领域的完整权威文档
  • 表格（方法参考、属性、事件）是事实依据
  • 参考文件中这些表格以外的内容仅用于说明
  • 不得超出参考文件表格中列出的范围

• 审核生成内容：

  • 提供任何代码之前，确认使用的每个 API 都出现在参考文件表格中
  • 记录每个 API 来自哪个参考文件
  • 如果无法引用参考文件表格中的条目，请删除相应代码

• **这是关键要求。**违规会损害此技能的完整性和可靠性。

第 1 步 — 检测应用类型 （必需，不得跳过）

• 使用 file_search 和 read_file 工具检查工作区项目文件：
  • package.json（项目配置和依赖项）
  • vite.config.js 或 vite.config.ts（Vue 3 Vite 构建配置）
  • vue.config.js（Vue 2 Vue-CLI 配置）
  • App.vue（根组件）
  • main.js 或 main.ts（应用入口点——检查 Vue 2 是否使用 Vue.use(...)，或 Vue 3 是否使用 createApp(...)）
  • src/ 文件夹中的任何现有 .vue 文件
• **输出：**继续之前，确认检测到的应用类型为 Vue 2 或 Vue 3，因为组件注册和 API 模式各不相同。

第 2 步 — 仅根据参考文件生成代码 （必需）

• **生成前：**确认第 1 步已完成
• 阅读与所需功能相关的 references/*.md 文件
• 对照这些表格核查每个 API、属性和方法
• 基于组件的方案（强制 — 仅限 Vue 模式）：
  • 使用 Vue SFC（.vue）语法，并包含 <template>、<script> 和 <style> 部分
  • 使用 <ejs-pdfviewer> 作为组件标签
  • 使用 Vue 的 :prop="value" 绑定语法绑定所有 PDF Viewer 属性
  • **Vue 2：**通过 components: { "ejs-pdfviewer": PdfViewerComponent } 注册组件，并通过 provide: { PdfViewer: [...] } 注入服务
  • **Vue 3 Composition API：**导入 PdfViewerComponent as EjsPdfviewer，并从 vue 中使用 provide('PdfViewer', [...])
  • **Vue 3 Options API：**像 Vue 2 一样使用 components + provide 选项，但入口使用 createApp
  • 使用 ref / $refs（Vue 2）或 ref() + 模板 ref 属性（Vue 3）以编程方式访问查看器
• **强制：**生成任何代码之前，验证参考文件是否存在且可访问
• 阅读所需功能对应的参考文件：
  • 使用 read_file 工具读取相关的 references/*.md 文件
  • 确认文件包含 Methods/Properties/Events 表格
  • 验证表格完整且可读
• 如果参考文件缺失或无法读取：
  • 停止生成代码
  • 回复：“此功能的参考文件不可用。请确保 references/ 目录中包含所有参考文件。”
  • 列出缺失的参考文件名
• **此步骤为阻塞步骤：**未经参考文件验证，不得继续
• 如果某个 API/属性未出现在参考文件表格中，不要使用它
• 不要编造、猜测或建议参考文件中未明确列出的任何 API、方法、属性、类或命名空间

---

参考文件路由

所有模板和操作代码片段都位于 references/*.md 中。每个文件都包含专用代码片段或模板，Agent 会在生成示例时将其组合使用。

**流程：**始终先从 getting-started.md 开始，然后将匹配的功能合并到其锚点（PROPS、EVENTS、UI_BUTTONS、HANDLERS）中。如果没有匹配的关键词，只返回基本示例。

生成代码前的检查清单

• **是否识别了 Vue 版本？**Vue 2 → 使用 data() + provide:{} | Vue 3 → 使用 ref()/reactive() + provide()
• **设置属性的数量：**1-3 个？→ 使用内联绑定 | 4 个或更多？→ 使用 data 常量
• **是否涉及枚举？**是 → 导入所需枚举 | 否 → 跳过枚举导入
• **是否会在其他地方复用？**是 → 使用 data/ref 常量 | 否 → 优先使用内联
• **组件属性是否足够简单？**是 → 保持内联 | 否 → 提取到 data/ref

🎯 核心设置与配置

文件	用途	用户询问以下内容时使用
getting-started.md	包含 documentPath、height 和 width 的最小化 PDFViewer。所有示例的基础模板。	“基本设置”、“最小示例”、“入门”、“如何加载 PDF”
general-properties.md	配置查看器核心属性（服务端 URL、文档路径、区域设置、资源基础路径）。	“配置”、“服务器设置”、“区域设置”、“文档路径设置”
enable-properties.md	启用或禁用特定功能（工具栏、批注、表单、导航、文本选择、下载、打印）。	“禁用工具栏”、“隐藏功能”、“启用/禁用”、“只读模式”、“限制功能”

📐 导航与页面管理

文件	用途	当用户询问以下内容时，查阅此文件
page-navigation.md	在页面间导航（首页、末页、下一页、上一页），跳转到指定页码。	“页面导航”、“转到页面”、“下一页”、“上一页”、“跳转到页面”
bookmark-navigation.md	使用书签面板中的 PDF 书签/目录进行导航。重要：所有书签方法都必须通过 this.$refs.pdfViewer.bookmark.*（Vue 2）或 pdfViewerRef.value.bookmark.*（Vue 3 Composition API）访问，不能直接在查看器实例上调用。	“书签”、“目录”、“目录导航”、“大纲面板”、“获取书签”、“检索书签”、“提取书签”、“以编程方式操作书签”、“getBookmarks”、“goToBookmark”、“书签 API”、“列出书签”、“打开书签”、“关闭书签”
hyperlink-navigation.md	配置 PDF 中的超链接导航行为和外部链接处理方式。	“超链接”、“外部链接”、“URL 导航”、“可点击链接”、“url”、“链接”
thumbnail-navigation.md	在缩略图面板中显示页面缩略图并通过缩略图进行导航。	“缩略图”、“预览页面”、“缩略图面板”、“页面预览”

🔍 查看与交互

文件	用途	当用户询问以下内容时，查阅此文件
magnification.md	配置缩放级别、缩放模式和放大控制（适合页面、适合宽度）。	“缩放”、“放大”、“适合页面”、“缩放级别”、“缩放文档”
interaction-mode.md	在选择模式（文本选择）和拖动模式（触控滚动）之间切换。	“文本选择”、“拖动”、“滚动模式”、“交互模式”、“触控导航”
text-selection.md	启用文本选择、文本复制和文本选择事件。	“选择文本”、“复制文本”、“选中要复制的文本”、“文本选择模式”
text-search.md	实现文本搜索功能，并提供搜索选项和导航。	“搜索文本”、“在 PDF 中查找”、“搜索功能”、“突出显示搜索结果”

🛠️ 工具栏与上下文菜单

工具栏配置

文件	用途	当用户询问以下内容时，查阅此文件
toolbar-settings.md	配置工具栏的可见性和工具提示行为，并自定义或移除工具栏项目。	“自定义工具栏”、“隐藏工具栏项目”、“移除工具栏按钮”、“工具栏配置”
toolbar-methods.md	以编程方式显示/隐藏工具栏，并在运行时启用/禁用工具栏项目。	“动态显示/隐藏工具栏”、“切换工具栏”、“以编程方式启用/禁用工具栏项目”

⚠️ 工具栏项目名称严格校验

生成工具栏配置时，必须遵循以下规则，以避免工具栏项目名称错误：

1. 始终引用 toolbar-settings.md 中的准确项目名称

   • 不要自行编造、猜测或假定工具栏项目名称
   • 不要根据命名模式推导名称
   • 仅使用 toolbar-settings.md 中“Available Primary Toolbar Items”、“Available Annotation Toolbar Items”和“Available Form Designer Items”部分列出的名称

2. 逐字符校验项目名称

   • 区分大小写：HighlightTool ≠ HighlightOption
   • 名称必须完全准确：AnnotationEditTool ≠ AnotatetionEditTool
   • 不得使用缩写或简写

3. 生成工具栏配置代码前：

   • 打开参考文件 toolbar-settings.md
   • 找到“Available Primary Toolbar Items”部分
   • 找到“Available Annotation Toolbar Items”部分
   • 找到“Available Form Designer Items”部分
   • 仅从这些部分复制准确名称
   • 逐字符交叉核对每个项目名称
   • 如果任何项目名称不在参考部分中，就不要使用
   • 如有疑问，请查阅 toolbar-settings.md 中的“❌ COMMON MISTAKES TO AVOID”表格

4. 需要避免的常见错误：

   • ❌ AnotatetionEditTool → ✅ AnnotationEditTool（拼写错误）
   • ❌ CalibrationOption → ✅ CalibrateTool（后缀错误）
   • ❌ ShapeAnnotationOption → ✅ ShapeTool（注释工具栏版本）
   • ❌ InkAnnotationOption → ✅ InkAnnotationTool（注释工具栏版本）
   • 完整的错误清单请参阅 toolbar-settings.md 中的“❌ COMMON MISTAKES TO AVOID”表格

上下文菜单自定义

文件	用途	当用户询问以下内容时参考
contextmenu.md	自定义上下文菜单项目并处理上下文菜单事件。	“右键菜单”、“上下文菜单”、“自定义上下文菜单”、“禁用上下文菜单项目”

📝 注释

文件	用途	当用户询问以下内容时参考
annotation-settings.md	配置所有注释类型的外观（颜色、不透明度、样式）和行为。	“注释颜色”、“注释样式”、“自定义注释外观”、“注释默认设置”
annotation-events.md	处理注释生命周期事件（添加、删除、移动、调整大小、选择、属性更改）。	“注释事件”、“添加注释时”、“注释更改检测”、“注释回调”
shape-label-settings.md	自定义形状和测量注释标签（位置、颜色、字体、可见性）。	“注释标签”、“形状标签”、“测量标签”、“标签自定义”
redaction-annotation.md	创建、配置和应用涂黑注释，以永久删除敏感内容。	“涂黑”、“涂黑内容”、“删除敏感数据”、“遮盖文本”、“永久删除”

📄 表单

文件	用途	当用户询问以下内容时参考
form-field-settings.md	配置表单字段（文本、复选框、单选框、下拉菜单、签名）的默认属性。	“表单字段默认设置”、“表单字段样式”、“配置表单字段”、“表单字段属性”
form-field-events.md	处理表单字段交互事件（焦点、失焦、值更改、验证）。	“表单字段事件”、“字段更改时”、“表单验证事件”、“字段交互回调”

📋 文档操作

文件	用途	用户询问以下内容时转至
download.md	启用/配置 PDF 下载功能并设置自定义文件名。	“下载 PDF”“保存 PDF”“导出文档”“下载按钮”
print.md	配置并触发 PDF 打印功能。	“打印 PDF”“打印文档”“打印选项”“打印按钮”
organize-pages.md	对 PDF 页面重新排序、旋转、插入、移除、复制、导入和提取。	“重新排列页面”“旋转页面”“添加空白页”“移除页面”“调整页面顺序”“合并 PDF”

⚙️ 高级功能

文件	用途	用户询问以下内容时转至
api-methods.md	程序化控制：加载文档、管理表单、批注、提取文本、撤销/重做、导航 API。	“以编程方式加载 PDF”“API 方法”“导出表单数据”“提取文本”“撤销/重做”“程序化控制”
events.md	PDFViewer 所有事件的完整列表（文档加载、下载、批注、表单、搜索、导航）。	“事件列表”“所有事件”“可用事件”“事件参考”“事件处理程序”

快速入门示例

<template>
  <ejs-pdfviewer
    ref="pdfViewer"
    :resourceUrl="resourceUrl"
    :documentPath="documentPath"
    style="height: 640px">
  </ejs-pdfviewer>
</template>

<script setup>
import { provide } from 'vue';
import { PdfViewerComponent as EjsPdfviewer, Toolbar, Magnification, Navigation, LinkAnnotation,
         BookmarkView, ThumbnailView, Print, TextSelection, TextSearch,
         Annotation, FormDesigner, FormFields } from '@syncfusion/ej2-vue-pdfviewer';

const resourceUrl = window.location.origin + "/asset/ej2-pdfviewer-lib";
const documentPath = 'https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf';

provide('PdfViewer', [ Toolbar, Magnification, Navigation, LinkAnnotation, BookmarkView, ThumbnailView,
                       Print, TextSelection, TextSearch, Annotation, FormDesigner, FormFields ]);
</script>

<style>
  /* Refer to the CSS Configuration section for the full import list */
  @import '../node_modules/@syncfusion/ej2-tailwind3-theme/styles/pdfviewer/index.css';
</style>

⚙️ 设置配置最佳实践

使用设置（toolbarSettings、annotationSettings、annotationSelectorSettings、arrowSettings、rectangleSettings 等）生成代码时，请遵循以下指南，避免不必要的复杂性：

规则 1：简单设置 → 在组件绑定中内联定义

适用于以下情况：

• 只配置 1-3 个属性
• 设置简单，不涉及复杂枚举或自定义类型
• 无需单独定义数据常量

示例（推荐）：

<template>
  <ejs-pdfviewer
    id="container"
    documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
    :annotationSelectorSettings="{
      selectionBorderColor: '#0000ff',
      selectionBorderThickness: 2,
      resizerBorderColor: '#ff0000',
    }"
    style="height: 640px"
  />
</template>

优点：

• ✅ 无需额外的数据属性
• ✅ 简单易读
• ✅ 减少代码冗余

---

规则 2：复杂设置 → 在 data() / ref() 中定义（在模板之外）

适用于以下情况：

• 配置 4 个或更多属性，或多个相关设置
• 使用枚举或复杂配置
• 需要在多个组件中复用相同配置

示例 — Vue 2 Options API（仅适用于复杂情况）：

<template>
  <ejs-pdfviewer
    id="container"
    :documentPath="documentPath"
    :annotationSelectorSettings="annotationSelectorConfig"
    style="height: 640px"
  />
</template>

<script>
import { PdfViewerComponent, Annotation,
         AnnotationResizerLocation, CursorType } from '@syncfusion/ej2-vue-pdfviewer';

export default {
  name: 'App',
  components: { 'ejs-pdfviewer': PdfViewerComponent },
  data() {
    return {
      documentPath: 'https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf',
      annotationSelectorConfig: {
        selectionBorderColor: '#0000ff',
        selectionBorderThickness: 2,
        resizerBorderColor: '#ff0000',
        resizerFillColor: '#4070ff',
        resizerSize: 8,
        resizerShape: 'Square',
        selectorLineDashArray: [5, 6],
        resizerLocation: AnnotationResizerLocation.Corners | AnnotationResizerLocation.Edges,
        resizerCursorType: CursorType.grab,
      },
    };
  },
  provide: { PdfViewer: [Annotation] },
};
</script>

示例 — Vue 3 Composition API（仅适用于复杂情况）：

<script setup>
import { provide } from 'vue';
import { PdfViewerComponent as EjsPdfviewer, Annotation,
         AnnotationResizerLocation, CursorType } from '@syncfusion/ej2-vue-pdfviewer';

const documentPath = 'https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf';
const annotationSelectorConfig = {
  selectionBorderColor: '#0000ff',
  selectionBorderThickness: 2,
  resizerBorderColor: '#ff0000',
  resizerFillColor: '#4070ff',
  resizerSize: 8,
  resizerShape: 'Square',
  selectorLineDashArray: [5, 6],
  resizerLocation: AnnotationResizerLocation.Corners | AnnotationResizerLocation.Edges,
  resizerCursorType: CursorType.grab,
};

provide('PdfViewer', [Annotation]);
</script>

何时导入枚举：

• 导入设置中用到的所有枚举（例如，AnnotationResizerLocation、CursorType）
• 尽量减少导入项——只导入设置中用到的内容

优点：

• ✅ 正确使用枚举
• ✅ 可在多个组件中复用
• ✅ 模板代码简洁

---

规则 3：简单情况绝不要过度设计

❌ 不要这样做（过度设计）：

<script>
import { PdfViewerComponent } from '@syncfusion/ej2-vue-pdfviewer';
export default {
  components: { 'ejs-pdfviewer': PdfViewerComponent },
  data() {
    return {
      // Unnecessary data property for 1 simple prop
      toolbarSettings: { showTooltip: true },
    };
  },
};
</script>

✅ 应该这样做（简单整洁）：

<ejs-pdfviewer :toolbarSettings="{ showTooltip: true }" ... />

---