syncfusion-javascript-pdf-viewer

Syncfusion TypeScript PdfViewer – UI 示例生成器

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

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

**用途：**生成精简、可直接复制粘贴的 TypeScript（.ts）和 HTML 代码，供用户直接集成到 TypeScript EJ2 项目中。

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

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

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

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

• 严格执行 — 零容忍：

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

• 不支持的功能必须这样回复：

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

    "This feature is not supported in the current Syncfusion TypeScript PDF Viewer implementation."
    

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

• 参考文件层级：

  • 每个参考文件都包含其所属领域完整且权威的文档
  • 表格（方法参考、属性、事件）是唯一的事实来源
  • 参考文件中这些表格以外的内容仅用于解释
  • 不得超出参考文件表格中列出的内容

• 审查生成内容：

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

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

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

• 使用 file_search 和 read_file 工具检查工作区项目文件：
  • package.json（检查是否依赖 @syncfusion/ej2-pdfviewer 或 @syncfusion/ej2）
  • tsconfig.json（TypeScript 配置）
  • webpack.config.js（EJ2 快速入门使用 webpack）
  • src/index.ts 或 src/app.ts（主 TypeScript 入口文件）
  • src/index.html（HTML 容器文件）
• **输出：**确认检测到的应用类型是 TypeScript EJ2 webpack 项目（不是 React／Vue／Angular 项目），然后再继续。
• **关键：**此技能使用 EJ2 PdfViewer 类生成 原生 TypeScript 代码。不得生成 React、Angular 或 Vue 组件代码。

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

• **生成代码之前：**确认第 1 步已完成
• 阅读与所请求功能相关的 references/*.md 文件
• 将每个 API、属性和方法与这些表格交叉核对
• 基于类的方式（强制要求 — 仅限 TypeScript EJ2 模式）：
  • 从 @syncfusion/ej2-pdfviewer 导入 PdfViewer 和所需的模块类
  • 使用 PdfViewer.Inject(...) 注入所需的功能模块
  • 使用 new PdfViewer({ ... }) 或 new PdfViewer() 实例化，并设置属性
  • 使用 viewer.appendTo('#ElementId') 挂载到 DOM
  • 绝不使用 JSX、TSX、React hooks 或基于组件的语法
  • 绝不使用 <PdfViewerComponent>、<Inject services={...}>、useState、useRef 或 useEffect
• **强制要求：**生成任何代码之前，验证参考文件存在且可访问
• 阅读与所请求功能对应的参考文件：
  • 使用 read_file 工具读取相关的 references/*.md 文件
  • 确认文件包含 Methods/Properties/Events 表格
  • 验证表格完整且可读
• 如果参考文件缺失或无法读取：
  • 停止生成代码
  • 回复：“此功能的参考文件不可用。请确保 references/ 目录中包含所有参考文件。”
  • 列出缺失的参考文件名
• **此步骤是阻断项：**未完成参考文件验证前不得继续
• 如果 API 或属性未出现在参考文件表格中，请勿使用
• 不要编造、猜测或建议参考文件中未明确列出的任何 API、方法、属性、类或命名空间

---

参考文件路由指南

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

**流程：**始终从 getting-started.md 开始，然后将匹配的功能合并到其中的锚点。如果没有匹配的关键词，则仅返回基本示例。

生成代码前的检查清单

• **设置属性的数量：**1–3 个？→ 在构造函数中内联传入 | 4 个及以上？→ 提取到类型化常量
• **是否涉及枚举？**是 → 必须使用带有枚举导入的类型化常量 | 否 → 可以内联传入
• **是否会在其他地方复用？**是 → 使用常量 | 否 → 优先内联
• **是否需要类型安全？**是 → 导入模型类型 | 否 → 跳过模型类型导入
• **是否需要枚举？**是 → 从 @syncfusion/ej2-pdfviewer 导入所需枚举 | 否 → 跳过枚举导入
• **包名是否正确？**始终从 @syncfusion/ej2-pdfviewer 导入 — 绝不从 @syncfusion/ej2-typescript-pdfviewer 导入

🎯 核心设置与配置

文件	用途	用户提出以下问题时使用
getting-started.md	最精简的 PdfViewer 设置：克隆快速入门项目、安装包、导入 CSS、创建包含 documentPath 和 resourceUrl 的 PdfViewer 实例，并将其挂载到 HTML 容器。	“基本设置”、“最小示例”、“入门”、“如何加载 PDF”
general-properties.md	配置查看器的核心属性（宽度、高度、文档路径、区域设置、resourceUrl、serviceUrl、AJAX 设置、滚动设置、commandManager）。	“配置”、“服务器设置”、“区域设置”、“文档路径设置”、“宽度和高度”
enable-properties.md	启用或禁用特定功能（工具栏、批注、表单、导航、文本选择、下载、打印）。	“禁用工具栏”、“隐藏功能”、“启用/禁用”、“只读模式”、“限制功能”

📐 导航与页面管理

文件	用途	用户询问以下内容时转到此文件
page-navigation.md	在页面之间导航（首页、末页、下一页、上一页），跳转到指定页码。	“页面导航”、“转到页面”、“下一页”、“上一页”、“跳转到页面”
bookmark-navigation.md	使用书签面板中的 PDF 书签／目录进行导航。关键：书签 API 方法可直接通过 pdfviewer 实例访问（例如，pdfviewer.bookmark.openBookmarkPane()）。需要注入 BookmarkView 并设置 enableBookmark: true。	“书签”、“书签”、“目录”、“目录导航”、“大纲面板”、“获取书签”、“检索书签”、“提取书签”、“以编程方式操作书签”、“getBookmarks”、“goToBookmark”、“书签 API”、“列出书签”、“打开书签”、“关闭书签”
hyperlink-navigation.md	配置 PDF 中的超链接导航行为和外部链接处理方式。	“超链接”、“外部链接”、“URL 导航”、“可点击链接”、“url”、“链接”
thumbnail-navigation.md	在缩略图面板中显示页面缩略图并使用缩略图导航。	“缩略图”、“预览页面”、“缩略图面板”、“缩略图”、“页面预览”

� 评论与面板

文件	用途	用户询问以下内容时转到此文件
general-properties.md	配置查看器的核心属性，包括通过 isCommandPanelOpen 以编程方式显示／隐藏评论面板。请参阅“控制命令面板（评论面板）”部分。**要求：**必须设置 enableAnnotation: true，命令面板才能正常工作。属性：isCommandPanelOpen 是可读写的布尔值（不是只读）。	“显示评论面板”、“隐藏评论面板”、“切换评论显示”、“命令面板”、“显示／隐藏评论”、“isCommandPanelOpen”、“评论面板”、“批注评论”

�🔍 查看与交互

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

🛠️ 工具栏与上下文菜单

工具栏配置

文件	用途	用户询问以下内容时转到此文件
toolbar-settings.md	使用 toolbarSettings 配置工具栏可见性、工具提示行为，并自定义／移除工具栏项。	“自定义工具栏”、“隐藏工具栏项”、“移除工具栏按钮”、“工具栏配置”
toolbar-methods.md	使用 showToolbar() 等方法以编程方式显示／隐藏工具栏，并在运行时启用／禁用工具栏项。	“动态显示／隐藏工具栏”、“切换工具栏”、“以编程方式启用／禁用工具栏项”

⚠️ 工具栏项名称的严格验证

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

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”表格

上下文菜单自定义

文件	用途	用户询问以下内容时的路由指引
context-menu.md	自定义上下文菜单项并处理上下文菜单事件。	“右键菜单”、“上下文菜单”、“自定义上下文菜单”、“禁用上下文菜单项”

📝 注释

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

📄 表单

文件	用途	当用户询问以下内容时，转到此处
form-field-settings.md	配置表单字段（文本、复选框、单选按钮、下拉列表、签名）的默认属性。使用 TextFieldSettings、CheckBoxFieldSettings、RadioButtonFieldSettings 等进行正确的类型转换。重要： 表单字段边界使用首字母大写的属性（X、Y、Width、Height），而非小写属性。时机至关重要： 始终在 documentLoad 事件回调中添加表单字段；在文档加载前调用会导致“formFieldCollections is not a function”错误。	“表单字段默认值”、“表单字段样式”、“配置表单字段”、“表单字段属性”、“添加文本字段”、“添加表单字段”、“添加文本框”、“添加复选框”、“以编程方式添加字段”、“addFormField”、“TextFieldSettings”
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 所有事件的完整列表（文档加载、下载、注释、表单、搜索、导航）。	“事件列表”、“所有事件”、“可用事件”、“事件参考”、“事件处理程序”

---

快速入门示例

import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation,
         ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView,
                BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.resourceUrl = "https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib";
pdfviewer.appendTo('#PdfViewer');

🔄 文档生命周期要求（重要）

何时使用 documentLoad 事件

某些操作必须在 documentLoad 事件回调中执行，而不是在实例化后立即执行：

需要使用 documentLoad 的操作：

• ✅ 以编程方式添加表单字段（formDesigner.addFormField()）
• ✅ 添加注释（annotation.addAnnotation()）
• ✅ 访问表单字段集合（formFieldCollections）
• ✅ 访问文档元数据
• ✅ 修改依赖于文档的属性

可在实例化时安全执行的操作：

• ✅ 设置 enableToolbar、enableAnnotation 等
• ✅ 设置查看器属性，如 width、height
• ✅ 配置设置对象

示例：表单字段的正确添加时机

❌ 错误——会导致“formFieldCollections.findIndex is not a function”：

let pdfviewer = new PdfViewer({
  documentPath: 'https://...',
  resourceUrl: 'https://...'
});
pdfviewer.appendTo('#PdfViewer');

// ERROR! formFieldCollections not yet initialized
pdfviewer.formDesigner.addFormField('Textbox', { ... });

✅ 正确——在 documentLoad 回调中执行：

let pdfviewer = new PdfViewer({
  documentPath: 'https://...',
  resourceUrl: 'https://...',
  documentLoad: () => {
    // SAFE - Document fully loaded, formFieldCollections initialized
    pdfviewer.formDesigner.addFormField('Textbox', { ... });
  }
});
pdfviewer.appendTo('#PdfViewer');

---

⚙️ 设置配置最佳实践

使用设置（toolbarSettings、annotationSettings、annotationSelectorSettings、arrowSettings、rectangleSettings 等）生成代码时，请遵循以下指南：

规则 1：简单设置 → 直接传递给 PdfViewer 构造函数

在以下情况下使用此方法：

• 仅配置 1-3 个属性
• 设置简单明了，不涉及复杂枚举或自定义类型

示例（请这样做）：

import { PdfViewer, Toolbar, Annotation } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Annotation);

let pdfviewer: PdfViewer = new PdfViewer({
  documentPath: 'https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf',
  resourceUrl: 'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib',
  annotationSelectorSettings: {
    selectionBorderColor: '#0000ff',
    resizerBorderColor: '#ff0000',
    resizerSize: 8
  }
});
pdfviewer.appendTo('#PdfViewer');

优点：

• ✅ 无需额外导入
• ✅ 简单易读
• ✅ 代码更简洁
• ✅ 仍可进行类型检查

---

规则 2：复杂设置 → 定义为类型化常量（在实例化之外）

在以下情况下使用此方法：

• 配置 4 个或更多属性，或配置多个相关设置
• 使用枚举或复杂配置
• 需要在多个位置重复使用相同配置
• 设置足够复杂，值得单独定义

示例（仅用于复杂情况）：

import { PdfViewer, Toolbar, Annotation, AnnotationResizerLocation, CursorType } from '@syncfusion/ej2-pdfviewer';
import { AnnotationSelectorSettingsModel } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Annotation);

// Define constant OUTSIDE instantiation with proper types and enums
const annotationSelectorConfig: AnnotationSelectorSettingsModel = {
  selectionBorderColor: '#0000ff',
  selectionBorderThickness: 2,
  resizerBorderColor: '#ff0000',
  resizerFillColor: '#4070ff',
  resizerSize: 8,
  resizerShape: 'Square',
  selectorLineDashArray: [5, 6],
  resizerLocation: AnnotationResizerLocation.Corners | AnnotationResizerLocation.Edges,
  resizerCursorType: CursorType.grab
};

let pdfviewer: PdfViewer = new PdfViewer({
  documentPath: 'https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf',
  resourceUrl: 'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib',
  annotationSelectorSettings: annotationSelectorConfig
});
pdfviewer.appendTo('#PdfViewer');

何时导入类型和枚举：

• 导入模型类型（例如，AnnotationSelectorSettingsModel）以进行 TypeScript 类型检查
• 导入设置中使用的任何枚举（例如，AnnotationResizerLocation、CursorType）
• 尽量减少导入，只导入实际使用的内容

优点：

• ✅ 类型安全的配置
• ✅ 正确使用枚举
• ✅ 可在多个查看器实例之间重复使用
• ✅ 实例化代码简洁明了

---

规则 3：切勿对简单情况过度设计

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

import { PdfViewer, Toolbar } from '@syncfusion/ej2-pdfviewer';
import { ToolbarSettingsModel } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar);

// Unnecessary constant for 2 simple properties
const toolbarSettings: ToolbarSettingsModel = {
  showTooltip: true
};

let pdfviewer: PdfViewer = new PdfViewer({
  toolbarSettings: toolbarSettings
});
pdfviewer.appendTo('#PdfViewer');

✅ 应该这样做（简单明了）：

import { PdfViewer, Toolbar } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar);

let pdfviewer: PdfViewer = new PdfViewer({
  documentPath: 'https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf',
  resourceUrl: 'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib',
  toolbarSettings: { showTooltip: true }
});
pdfviewer.appendTo('#PdfViewer');

常见问题及修正方法

• 提取页面 API 的位置：extractPages() 是 PdfViewer 的方法，而不是 pageOrganizer 的方法。请调用 pdfviewer.extractPages('1-3')，而不是 pdfviewer.pageOrganizer.extractPages('1-3')。PageOrganizer 服务用于启用 UI 和相关功能，但程序化提取应使用查看器实例。

• 加载已提取/序列化的 PDF：pdfviewer.load(document, password?) 接受两个参数。加载 extractPages(...) 返回的输出时，如果文档未受保护，请将密码参数设为空字符串，例如：pdfviewer.load(extractedPdf, '')。仅对受密码保护的 PDF 提供实际密码。

• 与文档相关操作的事件时机：请在 documentLoad 中执行批注和表单字段操作，以避免初始化错误（例如，formFieldCollections 尚不可用）。

---