Core API 参考

⚠️ 公开 API 范围 InkLayer 只承诺对以下两个组件提供稳定的公开 API：

PdfAnnotator（React / Vue）

PdfViewer（React / Vue）

所有 Hook、Composable、Store、Adapter、内部工具函数均属于内部实现细节，不保证跨版本兼容，不推荐直接使用。

本篇文档覆盖 PdfAnnotator 和 PdfViewer 的完整 Props 参考，以及 Annotation 数据模型（持久化存储的唯一格式）。

顶层导出

// React — inklayer-react
export { PdfAnnotator, PdfViewer } from 'inklayer-react'
export type { PdfAnnotatorProps, PdfViewerProps, Annotation, User } from 'inklayer-react'

// Vue — inklayer-vue
export { PdfAnnotator, PdfViewer } from 'inklayer-vue'
export type { PdfAnnotatorProps, PdfViewerProps, Annotation, User } from 'inklayer-vue'

注意：inklayer-vue 额外导出了 PdfViewerProvider，这是 Vue 组合式 API 的实现细节，一般无需直接使用。

PdfAnnotator Props

Prop	类型	默认值	说明
`url`	`string \| ArrayBuffer \| Uint8Array`	必填	PDF 文档地址或数据
`user`	`User`	必填	当前用户信息
`initialAnnotations`	`Annotation[]`	`[]`	初始批注数据
`layoutStyle`	`React.CSSProperties` / `Vue.StyleValue`	React: `undefined` Vue: `{ width: '100vw', height: '100vh' }`	容器样式
`defaultOptions`	`DefaultOptions`	见下文	默认工具选项
`theme`	`ThemeConfig`	见下文	主题配置
`enableRange`	`boolean`	`false`	是否启用框选多选
`defaultShowAnnotationsSidebar`	`boolean`	`false`	是否默认显示批注侧边栏
`title`	`string`	React: `undefined` Vue: `'PDF ANNOTATOR'`	页面标题
`data` (React only)	`string`	`undefined`	等同于 `url`，优先级更低
`onSave`	`(annotations: Annotation[]) => void`	—	保存回调
`onDocumentLoaded` (PdfViewer)	`(pdfDocument: PDFDocumentProxy) => void`	—	PDF 文档加载完成
`onEventBusReady` (PdfViewer)	`(eventBus: EventBus) => void`	—	EventBus 就绪
`onAnnotationChanged`	`(annotations: Annotation[], type: 'add' \| 'update' \| 'delete') => void`	—	批注变更回调
`onPageChanged`	`(pageIndex: number) => void`	—	页面切换回调
`onZoomChanged`	`(scale: number) => void`	—	缩放变更回调
`onError`	`(error: Error) => void`	—	错误回调
`actions`	`React.ReactNode \| ((props: ActionsProps) => React.ReactNode)` / `Vue: #actions`	—	自定义操作区
`toolbar`	`React.ReactNode \| ((props: ToolbarProps) => React.ReactNode)` / `Vue: #toolbar`	—	自定义工具栏
`sidebar`	`React.ReactNode \| ((props: SidebarProps) => React.ReactNode)` / `Vue: #sidebar-search-sidebar` 等	—	自定义侧边栏

DefaultOptions

interface DefaultOptions {
  highlight?: {
    strokeColor?: string    // 默认高亮颜色
    opacity?: number        // 默认透明度
  }
  freetext?: {
    fontSize?: number       // 默认字体大小
    fontFamily?: string     // 默认字体
    strokeColor?: string    // 默认文字颜色
  }
  rectangle?: {
    strokeColor?: string    // 默认边框颜色
    fillColor?: string      // 默认填充颜色
    strokeWidth?: number    // 默认边框宽度
  }
  circle?: {
    strokeColor?: string
    fillColor?: string
    strokeWidth?: number
  }
  signature?: {
    type?: 'Draw' | 'Enter' | 'Upload'  // 默认签名方式
    strokeColor?: string
    fontSize?: number
    fontFamily?: string
    maxSize?: number        // 最大文件大小（字节）
    defaultSignature?: string  // 默认签名内容
  }
  stamp?: {
    stamps?: Array<{ id: string; url: string; name: string }>  // 预设印章列表
  }
}

ThemeConfig

interface ThemeConfig {
  token?: {
    colorPrimary?: string       // 主色
    colorSuccess?: string      // 成功色
    colorWarning?: string      // 警告色
    colorError?: string        // 错误色
    fontSize?: number          // 基础字号
    borderRadius?: number     // 圆角
  }
  components?: {
    Button?: object
    Input?: object
    // 支持大部分 antd / varlet 组件的 token 覆盖
  }
}

PdfViewer Props

PdfViewer 是只读 PDF 查看器，不支持批注编辑，其余 Props 与 PdfAnnotator 一致（不含批注相关回调）。

Prop	类型	默认值	说明
`url`	`string \| ArrayBuffer \| Uint8Array`	必填	PDF 文档地址或数据
`user`	`User`	—	用户信息（只读场景可选）
`initialPage`	`number`	`0`	初始页码
`initialScale`	`number \| 'auto'`	`'auto'`	初始缩放，`'auto'` = 自适应宽度
`layoutStyle`	`React.CSSProperties` / `Vue.StyleValue`	同 PdfAnnotator	容器样式
`onDocumentLoaded`	`(pdfDocument: PDFDocumentProxy) => void`	—	PDF 文档加载完成
`onEventBusReady`	`(eventBus: EventBus) => void`	—	EventBus 就绪
`onPageChanged`	`(pageIndex: number) => void`	—	页面切换回调
`onZoomChanged`	`(scale: number) => void`	—	缩放变更回调
`onError`	`(error: Error) => void`	—	错误回调

ActionsProps 接口

当 actions 以函数形式传入时，接收以下参数：

interface ActionsProps {
  save: () => void                              // 触发保存
  getAnnotations: () => Annotation[]             // 获取当前批注
  exportToExcel: () => void                     // 导出为 Excel（仅 Vue）
  exportToPdf: () => void                       // 导出为 PDF
}

PdfViewerContextValue 接口（React）

通过 PdfViewerContext 获取：

interface PdfViewerContextValue {
  pageIndex: number              // 当前页码
  scale: number                  // 当前缩放
  pdfDocument: PDFDocumentProxy | null  // PDF 文档实例
  goToPage: (pageIndex: number) => void
  zoomTo: (scale: number | 'auto') => void
  getAnnotations: () => Annotation[]
  save: () => void
}

SidebarPanel 类型（React）

type SidebarPanel = 'search' | 'annotations' | 'outline' | 'thumbnails'

Annotation 数据模型

详见批注系统。核心要点：

interface Annotation {
  id: string                  // 全局唯一 UUID
  kind: AnnotationKind        // 语义分类
  target: AnnotationTarget   // 锚点信息（含 geometry + pageIndex + coordinateSystem）
  payload?: AnnotationPayload // 语义内容
  appearance?: AnnotationAppearance  // 外观属性
  relations?: AnnotationRelations     // 关系
  meta?: AnnotationMeta             // 元数据
}

持久化建议：onSave 回调直接给出完整的 Annotation[]，你可以直接将此数组发送到自己的后端。无需使用任何内部存储工具函数。