syncfusion-react-pdf-viewer

Syncfusion React Pdfviewer – UI 示例生成器

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

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

触发关键词：“how to”“add pdfviewer”“code sample”“show me”“example”“snippet”“integrate”“component”“create sample”“react sample”。

**用途：**生成精简、可直接复制粘贴的 TS 和 HTML 代码，供用户直接集成到 React 项目中。

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

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

• 生成任何代码前必须进行以下检查：

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

• 严格执行 — 零容忍：

  • 不得使用自定义属性 — 仅使用参考文件表格中的属性
  • 不得虚构方法 — 仅使用参考文件表格中的方法
  • 不得使用未定义的 API 变通处理 — 禁止
  • 不得假设未记录的行为 — 禁止
  • 不得使用猜测的方式提供替代实现 — 禁止
  • 不得假装功能受支持 — 禁止

• 不支持功能时的必须回复内容：

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

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

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

• 参考文件层级：

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

• 审核生成内容：

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

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

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

• 使用 file_search 和 read_file 工具检查工作区项目文件：
  • package.json（项目配置和依赖项）
  • tsconfig.json（TypeScript 配置）
  • App.tsx 或 App.jsx（根组件）
  • vite.config.ts 或 webpack.config.js（构建配置）
  • src/ 文件夹中的任何现有 .tsx 或 .jsx 文件
• **输出：**在继续之前，确认检测到的应用类型是 React TypeScript 或 JavaScript 项目。

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

• 生成前： 确认步骤 1 已完成
• 阅读与所请求功能相关的 references/*.md 文件
• 对照这些表格核验每个 API、属性和方法
• 基于组件的实现方式（强制 — 仅适用于 REACT 模式）：
  • 使用 JSX/TSX 语法组合 React 组件
  • 将所有 PDF Viewer 属性直接配置为组件属性
  • 需要编程访问时使用 React hooks（useState、useRef、useEffect）
• 强制要求： 生成任何代码之前，验证参考文件存在且可访问
• 阅读与所请求功能相应的参考文件：
  • 对相关的 references/*.md 文件使用 read_file 工具
  • 确认文件包含方法/属性/事件表格
  • 验证表格完整且可读
• 如果参考文件缺失或无法读取：
  • 停止生成代码
  • 回复：“此功能的参考文件不可用。请确保 references/ 目录中包含所有参考文件。”
  • 列出缺失的参考文件名
• 此步骤为阻塞步骤： 未验证参考文件前，不得继续
• 如果 API/属性未出现在参考文件的表格中，请勿使用
• 请勿编造、猜测或建议参考文件中未明确列出的任何 API、方法、属性、类或命名空间

---

参考文件路由指南

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

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

生成代码前的检查清单

• 统计设置属性的数量： 1–3 个？→ 内联 | 4 个或更多？→ 使用常量
• 是否涉及枚举？ 是 → 必须使用带导入的类型化常量 | 否 → 可以内联
• 是否会在其他地方复用？ 是 → 使用常量 | 否 → 优先内联
• 是否需要类型安全？ 是 → 导入 type { SettingsModel } | 否 → 跳过类型导入
• 是否需要枚举？ 是 → 导入所需枚举 | 否 → 跳过枚举导入
• 组件属性是否足够简单？ 是 → 保持内联 | 否 → 提取为常量

🎯 核心设置与配置

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

📐 导航()与页面管理

文件	用途	用户询问以下内容时路由至
page-navigation.md	在页面之间导航（第一页、最后一页、下一页、上一页），跳转到指定页码。	“页面导航”、“转到页面”、“下一页”、“上一页”、“跳转到页面”
bookmark-navigation.md	使用 PDF 书签／目录面板中的书签进行导航。重要：所有书签方法都必须通过 viewerRef.current.bookmark.* 访问（例如，viewerRef.current.bookmark.openBookmarkPane()），不能直接通过 viewerRef.current 访问	“书签”、“书签”、“目录”、“目录导航”、“大纲面板”、“获取书签”、“检索书签”、“提取书签”、“以编程方式操作书签”、“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 事件的完整列表（文档加载、下载、批注、表单、搜索、导航）。	“事件列表”、“所有事件”、“可用事件”、“事件参考”、“事件处理程序”

快速入门示例

import * as ReactDOM from 'react-dom/client';
import * as React from 'react';
import './index.css';
import { 
  PdfViewerComponent, Toolbar, Magnification, Navigation, LinkAnnotation, 
  BookmarkView, ThumbnailView, Print, TextSelection, Annotation, TextSearch, 
  FormFields, FormDesigner, Inject 
} from '@syncfusion/ej2-react-pdfviewer';

function App() {
  return (
    <div>
      <div className='control-section'>
        <PdfViewerComponent
          id="container"
          documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
          style={{ 'height': '640px' }}>
          <Inject services={[ 
            Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, 
            BookmarkView, ThumbnailView, Print, TextSelection, TextSearch, 
            FormFields, FormDesigner 
          ]} />
        </PdfViewerComponent>
      </div>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('sample'));
root.render(<App />);

⚙️ 设置配置最佳实践

使用设置（toolbarSettings、annotationSettings、annotationSelectorSettings、arrowSettings、rectangleSettings 等）生成代码时，请遵循以下指南，避免不必要的导入和过度设计：

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

适用于以下情况：

• 仅配置 1-3 个属性
• 设置简单，不涉及复杂枚举或自定义类型
• 无需使用 TypeScript 类型化常量

示例（请这样做）：

<PdfViewerComponent
  id="container"
  documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
  annotationSelectorSettings={{
    selectionBorderColor: '#0000ff',
    selectionBorderThickness: 2,
    resizerBorderColor: '#ff0000',
    resizerFillColor: '#4070ff',
    resizerSize: 8,
  }}
  style={{ height: '640px' }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

优点：

• ✅ 无需额外导入
• ✅ 简单易读
• ✅ 减少代码杂乱
• ✅ 仍可进行类型检查

---

规则 2：复杂设置 → 定义为类型化常量（在组件外部）

适用于以下情况：

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

示例（仅在复杂情况下这样做）：

import { PdfViewerComponent, Inject, Annotation } from '@syncfusion/ej2-react-pdfviewer';
import type { AnnotationSelectorSettingsModel } from '@syncfusion/ej2-react-pdfviewer';
import { AnnotationResizerLocation, CursorType } from '@syncfusion/ej2-react-pdfviewer';

// Define constant OUTSIDE component 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,
};

export function App() {
  return (
    <PdfViewerComponent
      id="container"
      documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
      annotationSelectorSettings={annotationSelectorConfig}
      style={{ height: '640px' }}
    >
      <Inject services={[Annotation]} />
    </PdfViewerComponent>
  );
}

何时导入类型和枚举：

• 导入 type { SettingsNameModel } 以进行 TypeScript 类型检查
• 导入设置中用到的所有枚举（例如 AnnotationResizerLocation、CursorType）
• 尽量减少导入——仅导入设置中实际用到的内容

优点：

• ✅ 配置具备类型安全性
• ✅ 正确使用枚举
• ✅ 可在多个组件中复用
• ✅ 组件代码简洁

---

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

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

import { PdfViewerComponent, Inject, Annotation } from '@syncfusion/ej2-react-pdfviewer';
import type { ToolbarSettingsModel } from '@syncfusion/ej2-react-pdfviewer';

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

export function App() {
  return (
    <PdfViewerComponent
      toolbarSettings={toolbarSettings}
      // ... rest of props
    />
  );
}

✅ 应这样做（简单清晰）：

<PdfViewerComponent
  toolbarSettings={{ showTooltip: true }}
  // ... rest of props
/>

---