syncfusion-aspnetcore-pdf-viewer

Syncfusion ASP.NET Core Pdfviewer – UI 示例生成器

NuGet： Syncfusion.EJ2.AspNet.Core

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

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

**用途：**生成精简、可直接复制粘贴的 Razor + HTML 代码（.cshtml），供用户直接集成到其 ASP.NET Core 项目中。

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

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

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

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

• 严格执行——零容忍：

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

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

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

    "This feature is not supported in the current Syncfusion ASP.NET Core PDF Viewer implementation."
    

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

• 参考文件层级：

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

• 审核生成内容：

  • 提供任何代码前，确认所用的每个 API 都出现在参考文件表格中
  • 记录每个 API 对应的参考文件
  • 如果无法引用参考文件中的表格条目，就删除该代码

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

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

• 阅读与请求功能相关的 references/*.md 文件
• 对照这些表格核实每个 API、属性和方法
• **必须：**生成任何代码前，确认参考文件存在且可访问
• 阅读与请求功能相关的适当参考文件：
  • 使用 read_file 工具读取相关的 references/*.md 文件
  • 确认文件包含方法／属性／事件表
  • 确认表格完整且可读
• 如果参考文件缺失或无法读取：
  • 停止生成代码
  • 回复：“此功能的参考文件不可用。请确保 references/ 目录中包含所有参考文件。”
  • 列出缺失的参考文件名
• **这是阻断步骤：**未验证参考文件前不得继续
• 如果某个 API／属性未出现在参考文件表格中，请勿使用
• 不得虚构、猜测或建议参考文件中未明确列出的任何 API、方法、属性、类或命名空间

---

参考文件路由指南

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

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

生成代码前的检查清单

• 统计设置属性： 1-3 个？→ 内联使用 | 4 个或更多？→ 使用单独的 razor 代码块
• 组件 prop 是否足够简单？ 是 → 保持内联 | 否 → 提取到单独的 razor 代码块
• 是否已明确设置属性的默认值？ 是 → 移除 | 否 → 保留

🎯 核心设置与配置

文件	用途
getting-started.md	最精简的 PDF Viewer，包含 documentPath、height 和 width。所有示例的基础模板。
enable-properties.md	启用或禁用特定功能（工具栏、注释、表单、导航、文本选择、下载、打印）。
general-properties.md	配置查看器核心属性和行为（documentPath、width/height、locale、zoom/initialRenderPages）、服务端/集成设置（serviceUrl、ajaxRequestSettings、serverActionSettings）、资源加载（resourceUrl、customFonts）以及性能/重试选项。

上下文菜单

文件	用途
contextmenu.md	为文本、注释和表单字段提供上下文相关的上下文菜单；通过 addCustomMenu 添加自定义项目，通过 customContextMenuSelect 处理点击，通过 customContextMenuBeforeOpen 动态显示/隐藏项目，并使用 contextMenuOption 禁用菜单。使用上下文菜单设置配置默认上下文菜单。

导航功能

文件	用途
navigation.md	启用/禁用页面导航（首页/末页/上一页/下一页/跳转到页面）、缩略图视图和导航、超链接支持（内部和外部链接）、目录导航、编程式导航方法以及导航相关事件。
bookmark-navigation.md	启用/禁用和显示/隐藏书签导航。以编程方式获取文档的书签

核心查看与交互

文件	用途
viewing-and-interaction.md	了解交互模式（文本选择/平移）、页面滚动和查看行为、平移操作、模块化架构中的功能模块、启用/禁用特定查看功能以及核心查看能力。
magnification.md	配置缩放级别和缩放百分比、缩放模式（适合页面/适合宽度/适合可见区域/自动）、自定义缩放控件、编程式缩放操作、缩放工具栏配置以及鼠标滚轮缩放行为。

工具栏配置

文件	用途
toolbar-customization.md	自定义 PDF Viewer 主工具栏、表单设计器工具栏和注释工具栏。以编程方式启用/禁用工具栏，启用/禁用和显示/隐藏工具栏项目。列出工具栏可用的项目。在初始化期间启用/禁用表单设计器、注释或主工具栏。创建自定义工具栏项目
toolbar-reference.md	使用工具栏 API 方法/属性显示/隐藏主工具栏/注释工具栏/导航工具栏/涂黑工具栏。
toolbar-customization-scenarios.md	常见的工具栏自定义场景

注释和标记

文件	用途
annotation-overview.md	有关墨迹／手绘、便签／评论、手写／数字签名注释以及以编程方式添加注释的信息。介绍注释的整体类型，并提供常见默认注释设置示例
text-markup-annotations.md	以编程方式添加文本标记注释（高亮、下划线、删除线、波浪线）。调整各类文本标记注释的默认设置
shape-annotations.md	有关形状注释（直线、箭头、矩形、圆形、多边形）的信息。以编程方式添加形状注释，并调整各类形状注释的默认设置
measurement-annotations.md	有关测量注释（距离、周长、面积、半径、体积）的信息。以编程方式添加测量注释，并调整各类测量注释的默认设置
stamp-annotation.md	有关印章注释及可用印章类型的信息。以编程方式添加印章注释
free-text-annotations.md	有关自由文本注释的信息。以编程方式添加自由文本注释
annotation-settings.md	配置所有注释类型的外观（颜色、不透明度、边框、样式）和行为（限制、锁定、打印）。全局应用设置或按注释类型应用设置。自定义注释选择器（调整大小控件、选中边框）。设置作者、主题和自定义数据。控制与注释相关的组件属性（工具栏可见性、签名设置、导出选项、绘图约束）。
annotation-events.md	处理注释生命周期事件（添加、删除、移动、调整大小、选择、属性更改）。
annotation-operations.md	以编程方式操作注释，例如选择、移动和调整大小、删除、锁定以及导入和导出注释
annotation-use-cases.md	以编程方式操作注释的常见场景
shape-label-settings.md	配置形状和测量注释标签的外观（填充颜色、字体、字号、不透明度）及默认内容（标签文本、备注）。
redaction-annotation.md	隐藏并永久删除 PDF 中的敏感信息。按区域或整页标记内容，配置覆盖文字和样式，不可逆地应用涂黑，搜索文本并自动涂黑，以及以编程方式管理涂黑注释。

表单管理

文件	用途
form-fields-overview.md	填写和设计 PDF 表单，管理表单字段（字段类型包括文本框／密码框／复选框／单选按钮／下拉框／列表框／签名），以编程方式创建字段，使用表单设计器工具栏／UI 交互，配置字段属性／自定义设置，应用验证规则和约束／设置，使用表单字段 API 方法，以及处理表单数据的导入／导出，包括自定义字段数据。
supported-form-fields.md	支持的表单字段类型，以及如何以编程方式添加每种类型
form-fields-props.md	列出表单字段的属性，包括通用属性和各字段的特定属性。调整表单字段设置
import-export-form-data.md	以编程方式导入和导出表单字段数据
form-operations.md	以编程方式操作表单字段，包括更新属性和值、移动和调整大小、删除、分组、添加自定义数据，以及检索表单字段数据
form-field-validation.md	启用／禁用表单字段验证。表单字段验证的编程流程和示例
form-field-settings.md	配置表单字段（文本、复选框、单选按钮、下拉框、签名）的默认属性。
form-field-events.md	处理表单字段交互事件（获得焦点、失去焦点、值更改、验证）。

文本操作

文件	用途
text-search.md	在 PDF 中实现文本搜索：搜索功能、搜索选项（区分大小写／全词匹配）、高亮搜索结果、查找下一个／上一个匹配项、以编程方式搜索文本的方法、搜索完成事件和自定义高亮颜色。配置文本提取选项／设置，并以编程方式从页面提取文本
text-selection.md	启用文本选择和文本提取：选择模式／行为、复制所选文本、文本选择事件、以编程方式选择，以及文本集合／边界。

文档操作

文件	用途
opening-pdfs.md	从 URL／本地路径／base64 加载 PDF，打开加密／受密码保护的 PDF，支持以编程方式加载文档，处理文档加载事件／生命周期，并管理加载失败／错误。
saving-and-downloading.md	下载 PDF，保存带批注／修改内容的 PDF，下载包含表单数据的 PDF，以 base64 格式获取 PDF，自定义下载事件，并设置自定义下载文件名。
printing-and-organizing.md	打印 PDF（包括页面范围／质量等打印选项和静默打印），处理打印事件，整理页面（概览／重新排列／排序／旋转／删除），将页面复制／复制一份／提取到新文档，并使用页面整理器工具栏以编程方式整理页面，以及在移动设备上整理页面。

⚙️ 高级功能

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

---

快速入门示例

@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div class="text-center">
    <ejs-pdfviewer id="pdfviewer" style="height:600px"
        documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
        annotationAdd="annotationAdded" >
    </ejs-pdfviewer>
</div>

⚙️ 设置配置最佳实践

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

规则 1：简单设置 → 定义为 Razor 内联代码

适用于以下情况：

• 仅配置 1-3 个属性
• 设置简单，无需自定义类型

示例（请这样做）：

<ejs-pdfviewer
    annotationSelectorSettings="@(new {
        selectionBorderColor = "blue",
        resizerBorderColor = "red",
        resizerFillColor = "#4070ff",
        resizerSize = 8,
        selectionBorderThickness = 1,
        resizerShape = "Circle",
        selectorLineDashArray = new int[] { 5, 6 },
        resizerLocation = "Corners|Edges",
        resizerCursorType = "grab"
    })">
</ejs-pdfviewer>

优点：

• ✅ 简单易读
• ✅ 减少代码杂乱
• ✅ 仍可进行类型检查

---

规则 2：复杂设置 → 在 HTML 外部定义为 Razor 代码块

适用于以下情况：

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

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

@{
    var annotationSelectorSettings = new {
        selectionBorderColor = "blue",
        resizerBorderColor = "red",
        resizerFillColor = "#4070ff",
        resizerSize = 8,
        selectionBorderThickness = 1,
        resizerShape = "Circle",
        selectorLineDashArray = new int[] { 5, 6 },
        resizerLocation = "Corners|Edges",
        resizerCursorType = "grab"
    };
}
<ejs-pdfviewer annotationSelectorSettings="@annotationSelectorSettings">
</ejs-pdfviewer>

---

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

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

@{
    var toolbarSettings = new Syncfusion.EJ2.PdfViewer.PdfViewerToolbarSettings  { ShowTooltip = true };
}
<ejs-pdfviewer
    toolbarSettings="@toolbarSettings"
>
</ejs-pdfviewer>

✅ 请这样做（简单整洁）：

<ejs-pdfviewer 
    toolbarSettings="@(new Syncfusion.EJ2.PdfViewer.PdfViewerToolbarSettings  { ShowTooltip = true })">
</ejs-pdfviewer>

---