快速开始

本指南介绍如何安装依赖、运行开发服务器、构建生产产物，以及将 WebViewer 嵌入你自己的页面。

前置条件

• Node.js 18+
• pnpm（推荐）或 npm
• ComPDFKit 许可证密钥（可向 ComPDF 申请评估许可证）

安装

git clone <repository-url>
cd compdfkit-web-sdk
pnpm install

工作区包含两个包：

包	路径	说明
@compdfkit/core	packages/core	闭源 PDF 引擎；构建到 packages/webview/lib/。
@compdfkit/webview	packages/webview	开源 Vue 3 UI 层（本文档的重点）。

开发

# 开发服务器，访问 http://localhost:3032（代理 core 构建）
pnpm dev

# 开发 + core watch 模式（core 变更时重新构建引擎）
pnpm dev:core

开发服务器运行在 http://localhost:3032。在独立模式下（直接运行 webview 应用而非嵌入运行），loadConfig 会应用开发默认值，包括许可证和 renderLayerPermission: true。

生产构建

pnpm build          # 仅构建 webview（Vite → packages/webview/dist/）
pnpm build:core     # 构建 core 引擎（Rollup → packages/webview/lib/）
pnpm build:webviewer # 构建 webviewer.js（iframe 嵌入入口）
pnpm build:release  # 完整发布：core → webviewer → webview → release/

完整发布产物结构见 部署。

测试与 Lint

# 单元测试（仅 webview，Vitest + happy-dom）
pnpm --filter @compdfkit/webview test:unit

# Lint（仅 webview）
pnpm --filter @compdfkit/webview lint

没有工作区级别的统一测试入口。core 包除少量手动运行的 .test.js 文件外，没有测试基础设施。

嵌入 WebViewer

面向集成方的入口是 webviewer.js（packages/core/webviewer.js），构建为 packages/webview/lib/webviewer.js（ES）和 webviewer.global.js（UMD，全局变量名 ComPDFKitViewer）。

作为 ES 模块

import ComPDFKitViewer from '@compdfkit/core/webviewer';

ComPDFKitViewer.init(
  {
    path: '/lib',                              // webviewer/ 文件夹的托管路径
    pdfUrl: '/files/sample.pdf',               // 初始文档
    license: 'YOUR_LICENSE_KEY',
    theme: 'light',                            // 'light' | 'dark'
    showToolbarControl: true,
  },
  document.getElementById('viewer')            // 宿主元素
).then(instance => {
  const { UI, Core, docViewer } = instance;
  // 已就绪——参见各指南。
});

通过 <script> 标签（UMD）

<div id="viewer"></div>
<script src="/lib/webviewer.global.js"></script>
<script>
  ComPDFKitViewer.init({ path: '/lib', pdfUrl: '/files/sample.pdf' }, document.getElementById('viewer'))
    .then(instance => { /* instance.UI, instance.Core */ });
</script>

嵌入原理

1. ComPDFKitViewer.init(options, element) 创建一个 <iframe>，指向 webviewer/index.html?version=...#d=<initialDoc>&docId=<docId>，可选追加 &css=、&header=、&theme= 哈希参数。
2. iframe 内部，Vite 构建的 webview 应用启动：main.js → Suspenser.vue → App/index.vue。
3. App/index.vue 等待 i18next 就绪，然后与父窗口进行配置握手（loadConfig）：iframe 发送 requestConfig，父窗口回复集成方的 options（以及可选的 config 脚本 URL）。
4. Core 的 ComPDFKitViewer 由打包好的 lib/webview.min.js 构造，并注册为实例 1。
5. iframe 内定义 window.instance = { docViewer, Core, UI }。
6. iframe 向父窗口发送 viewerLoaded；webviewer.js 捕获 iframe.contentWindow.instance 并以此解析其 init Promise。

options 参考

选项	用途
path	webviewer/ 文件夹的托管基础 URL（自动补全末尾 /）。
pdfUrl	初始文档 URL。
config	可选的集成方 config 脚本 URL，在 iframe 内加载。
css	注入 iframe 的自定义样式表 URL。
showToolbarControl	boolean → 通过 &header= 哈希参数控制工具栏显隐。
theme	'dark' / 'light'。
backgroundColor	设置 iframe 背景色。
assetPath	设置 iframe 的 data-assetpath（URI 编码）。
license	传递给引擎的许可证密钥。
功能开关	isAnnotationPopup、renderLayerPermission、webviewerServer、autoJumpNextSign、disableDigitalSignature、disableElectronicSignature、enableReply、enableDefaultFont、webFontURL、isRenderAnnotations。

instance 对象

初始化后，instance 暴露三个接口：

instance.UI      // UI 层 API（setLanguage、setTheme、disableElements、setHeaderItems 等）
instance.Core    // 通过 core 桥接层转发的引擎 API
instance.docViewer // 底层 ComPDFKitViewer 文档查看器（实例 1）

instance.UI 是各指南中介绍的主要公共接口。继续阅读 UI 定制总览 或 API 参考。

下一步

• 架构 — 理解三层设计。
• UI 定制 — 开始定制界面。
• 头部与工具栏 — 修改工具栏。