### Full Example: Annotator with Persistence and Slots

Source: https://inklayer.dev/zh-cn/docs/vue

A complete example demonstrating how to use the PdfAnnotator with data persistence and custom actions via slots.

```APIDOC
```vue
<script setup lang="ts">
import { ref } from 'vue'
import { PdfAnnotator } from 'inklayer-vue'
import 'inklayer-vue/style'
import type { Annotation } from 'inklayer-vue'

const annotatorRef = ref<InstanceType<typeof PdfAnnotator>>()
const annotations = ref<Annotation[]>([])

function handleSave(data: Annotation[]) {
  annotations.value = data
  // Send to backend
  fetch('/api/annotations', {
    method: 'POST',
    body: JSON.stringify(data),
  })
}
</script>

<template>
  <PdfAnnotator
    ref="annotatorRef"
    url="/document.pdf"
    locale="zh-CN"
    :layout-style="{ height: '96vh' }"
    :enable-range="true"
    :default-show-annotations-sidebar="true"
    :user="{ id: '9527', name: 'Lao Mai' }"
    :enable-native-annotations="true"
    :initial-annotations="[]"
    :default-options="defaultOptions"
    @save="handleSave"
    @load="() => console.log('PDF Loaded')"
    @annotation-added="(a) => console.log('Added:', a.id)"
    @annotation-deleted="(id) => console.log('Deleted:', id)"
    @annotation-updated="(a) => console.log('Updated:', a.id)"
    @annotation-selected="(a, isClick) => console.log('Selected:', a?.id, isClick)"
  >
    <template #actions="{ onSave, getAnnotations, exportToExcel, exportToPdf }">
      <button @click="onSave()">Save</button>
      <button @click="console.log(getAnnotations())">Get Annotations</button>
      <button @click="exportToExcel('my-export')">Export Excel</button>
      <button @click="exportToPdf('my-export')">Export PDF</button>
    </template>
  </PdfAnnotator>
</template>
```
```

--------------------------------

### PdfViewer Full Example

Source: https://inklayer.dev/zh-cn/docs/vue

A comprehensive example demonstrating the usage of the PdfViewer component with custom actions, toolbar, and event handling. It shows how to configure props like url, layout-style, and event callbacks.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { PdfViewer } from 'inklayer-vue'
import 'inklayer-vue/style'

function onEventBusReady(eventBus: any) {
  eventBus?.on('page-rendered', (e: any) => console.log('Page:', e.pageNumber))
}

function onDocumentLoaded(pdfViewer: any) {
  console.log('Document loaded:', pdfViewer)
}
</script>

<template>
  <PdfViewer
    :enable-range="false"
    title="PDF VIEWER CUSTOM"
    :url="pdfUrl"
    :layout-style="{ width: '100vw', height: '96vh' }"
    :show-text-layer="false"
    :show-annotations="true"
    :default-active-sidebar-key="null"
    :sidebar="customSidebar"
    @event-bus-ready="onEventBusReady"
    @document-loaded="onDocumentLoaded"
  >
    <template #actions="{ context }">
      <button @click="context.print()">打印</button>
      <button @click="context.download('test')">下载</button>
    </template>
    <template #toolbar="{ context }">
      <button @click="context.toggleSidebar()">切换侧边栏</button>
    </template>
  </PdfViewer>
</template>

```

--------------------------------

### Complete PdfAnnotator Example with Persistence

Source: https://inklayer.dev/zh-cn/docs/react

This example demonstrates how to use the PdfAnnotator component with state management for annotations, including saving to a backend API and initializing with existing annotations. It also shows how to customize actions and default options.

```javascript
import { PdfAnnotator } from 'inklayer-react'
import 'inklayer-react/style'
import type { Annotation } from 'inklayer-react'
import { useState, useCallback } from 'react'

export default function AnnotatorPage() {
  const [annotations, setAnnotations] = useState<Annotation[]>([])

  const handleSave = useCallback((annotations: Annotation[]) => {
    setAnnotations(annotations)
    // 将批注数据发送到后端
    fetch('/api/annotations', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(annotations),
    })
  }, [])

  return (
    <PdfAnnotator
      url="/document.pdf"
      locale="zh-CN"
      layoutStyle={{ height: '96vh' }}
      enableRange="auto"
      defaultShowAnnotationsSidebar={true}
      user={{ id: 'editor-1', name: '张三' }}
      initialAnnotations={annotations}
      defaultOptions={{
        colors: ['#FF0000', '#00FF00', '#0000FF'],
        signature: {
          defaultSignature: [],
          defaultFont: [{ label: '楷体', value: 'STKaiti', external: false }]
        },
        stamp: { defaultStamp: [] }
      }}
      onSave={handleSave}
      onLoad={() => console.log('PDF 加载完成')}
      onAnnotationAdded={(a) => console.log('新增批注:', a.id)}
      onAnnotationDeleted={(id) => console.log('删除批注:', id)}
      actions={(props) => (
        <>
          <button onClick={() => props.save()}>保存</button>
          <button onClick={() => console.log(props.getAnnotations())}>获取批注</button>
          <button onClick={() => props.exportToExcel('export')}>导出 Excel</button>
          <button onClick={() => props.exportToPdf('export')}>导出 PDF</button>
        </>
      )}
    />
  )
}
```

--------------------------------

### Install InkLayer React Package

Source: https://inklayer.dev/zh-cn/docs/quick-start

Install the InkLayer React package for manual integration into an existing React project. This package bundles all necessary dependencies.

```bash
npm install inklayer-react

```

--------------------------------

### Complete Highlight Annotation JSON Example

Source: https://inklayer.dev/zh-cn/docs/annotation

An example of a complete JSON object representing a highlight annotation, including its ID, kind, target geometry (quad), payload, appearance, and metadata.

```json
{
  "id": "ann-uuid-1234",
  "kind": "text-markup",
  "target": {
    "pageIndex": 0,
    "geometry": {
      "type": "quad",
      "quad": {
        "p1": { "x": 100, "y": 720 },
        "p2": { "x": 300, "y": 720 },
        "p3": { "x": 300, "y": 700 },
        "p4": { "x": 100, "y": 700 }
      }
    },
    "coordinateSystem": "pdf-user-space"
  },
  "payload": { "text": "这段话很重要" },
  "appearance": { "strokeColor": "#FFEB3B", "opacity": 0.6 },
  "meta": {
    "authorId": { "id": "user-1", "name": "张三" },
    "isNative": false,
    "source": "inklayer",
    "version": 1,
    "createdAt": "2025-01-01T10:00:00Z",
    "updatedAt": "2025-01-01T10:00:00Z"
  }
}

```

--------------------------------

### Full PdfAnnotator Example with Persistence and Slots

Source: https://inklayer.dev/zh-cn/docs/vue

This example demonstrates how to use the PdfAnnotator component with custom actions in the toolbar and data persistence. It shows how to handle save events, load PDF documents, and manage annotations.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { PdfAnnotator } from 'inklayer-vue'
import 'inklayer-vue/style'
import type { Annotation } from 'inklayer-vue'

const annotatorRef = ref<InstanceType<typeof PdfAnnotator>>()
const annotations = ref<Annotation[]>([])

function handleSave(data: Annotation[]) {
  annotations.value = data
  // 发送到后端
  fetch('/api/annotations', {
    method: 'POST',
    body: JSON.stringify(data),
  })
}
</script>

<template>
  <PdfAnnotator
    ref="annotatorRef"
    url="/document.pdf"
    locale="zh-CN"
    :layout-style="{ height: '96vh' }"
    :enable-range="true"
    :default-show-annotations-sidebar="true"
    :user="{ id: '9527', name: 'Lao Mai' }"
    :enable-native-annotations="true"
    :initial-annotations="[]"
    :default-options="defaultOptions"
    @save="handleSave"
    @load="() => console.log('PDF Loaded')"
    @annotation-added="(a) => console.log('Added:', a.id)"
    @annotation-deleted="(id) => console.log('Deleted:', id)"
    @annotation-updated="(a) => console.log('Updated:', a.id)"
    @annotation-selected="(a, isClick) => console.log('Selected:', a?.id, isClick)"
  >
    <template #actions="{ onSave, getAnnotations, exportToExcel, exportToPdf }">
      <button @click="onSave()">保存</button>
      <button @click="console.log(getAnnotations())">获取批注</button>
      <button @click="exportToExcel('my-export')">导出 Excel</button>
      <button @click="exportToPdf('my-export')">导出 PDF</button>
    </template>
  </PdfAnnotator>
</template>

```

--------------------------------

### Install InkLayer Vue Package

Source: https://inklayer.dev/zh-cn/docs/quick-start

Install the InkLayer Vue package for manual integration into an existing Vue project. This package bundles all necessary dependencies.

```bash
npm install inklayer-vue

```

--------------------------------

### Clone React Starter Template

Source: https://inklayer.dev/zh-cn/docs/quick-start

Use this command to clone the official InkLayer React starter template for a quick setup. It includes all SDK features without manual configuration.

```bash
git clone https://github.com/Laomai-codefee/inklayer-react-starter.git
cd inklayer-react-starter
npm install
npm run dev

```

--------------------------------

### Clone Vue Starter Template

Source: https://inklayer.dev/zh-cn/docs/quick-start

Use this command to clone the official InkLayer Vue starter template for a quick setup. It includes all SDK features without manual configuration.

```bash
git clone https://github.com/Laomai-codefee/inklayer-vue-starter.git
cd inklayer-vue-starter
npm install
npm run dev

```

--------------------------------

### PdfAnnotator layoutStyle Examples

Source: https://inklayer.dev/zh-cn/docs/react

Demonstrates correct usage of the `layoutStyle` prop for PdfAnnotator and PdfViewer. It emphasizes that all CSS values must be strings with units, and provides common layout patterns like full-screen, fixed-height container, and adjusting for top navigation.

```javascript
// ✅ 正确（PdfViewer 和 PdfAnnotator 均适用）
<PdfViewer layoutStyle={{ width: '100%', height: '600px' }} url="/doc.pdf" />
<PdfAnnotator layoutStyle={{ width: '100vw', height: '100vh' }} ... />

// ❌ 错误（数值不带单位，组件无法正确计算尺寸）
<PdfAnnotator layoutStyle={{ width: 800, height: 600 }} ... />
```

```javascript
// 方案 A：全屏占满
<PdfAnnotator layoutStyle={{ width: '100vw', height: '100vh' }} ... />

// 方案 B：嵌入有固定高度的容器
<div style={{ height: '600px' }}>
  <PdfViewer layoutStyle={{ width: '100%', height: '100%' }} url="/doc.pdf" />
</div>

// 方案 C：减去顶部导航栏高度
<PdfAnnotator layoutStyle={{ width: '100%', height: 'calc(100vh - 64px)' }} ... />
```

--------------------------------

### React PdfViewer Component

Source: https://inklayer.dev/zh-cn/docs/quick-start

A minimal example of using the PdfViewer component in React. It displays a PDF from a given URL and takes up the full viewport.

```jsx
import { PdfViewer } from 'inklayer-react'
import 'inklayer-react/style'

export default function App() {
  return (
    <PdfViewer
      url="https://inklayer.dev/inklayer-demo.pdf"
      layoutStyle={{ width: '100vw', height: '100vh' }}
    />
  )
}

```

--------------------------------

### Vue PdfViewer Component

Source: https://inklayer.dev/zh-cn/docs/quick-start

A minimal example of using the PdfViewer component in Vue. It displays a PDF from a given URL and takes up the full viewport. Ensure the plugin is registered.

```vue
<script setup>
import { PdfViewer } from 'inklayer-vue'
import 'inklayer-vue/style'
</script>

<template>
  <PdfViewer
    url="https://inklayer.dev/inklayer-demo.pdf"
    :layout-style="{ width: '100vw', height: '100vh' }"
  />
</template>

```

--------------------------------

### React PdfAnnotator Component

Source: https://inklayer.dev/zh-cn/docs/quick-start

A minimal example of using the PdfAnnotator component in React. It displays a PDF with full annotation capabilities, including user identification.

```jsx
import { PdfAnnotator } from 'inklayer-react'
import 'inklayer-react/style'

export default function App() {
  return (
    <PdfAnnotator
      url="https://inklayer.dev/inklayer-demo.pdf"
      user={{ id: 'user-1', name: 'Demo User' }}
      layoutStyle={{ width: '100vw', height: '100vh' }}
    />
  )
}

```

--------------------------------

### Vue PdfAnnotator Component

Source: https://inklayer.dev/zh-cn/docs/quick-start

A minimal example of using the PdfAnnotator component in Vue. It displays a PDF with full annotation capabilities, including user identification. Ensure the plugin is registered.

```vue
<script setup>
import { PdfAnnotator } from 'inklayer-vue'
import 'inklayer-vue/style'
</script>

<template>
  <PdfAnnotator
    url="https://inklayer.dev/inklayer-demo.pdf"
    :user="{ id: 'user-1', name: 'Demo User' }"
    :layout-style="{ width: '100vw', height: '100vh' }"
  />
</template>

```

--------------------------------

### 自定义工具栏 (Vue)

Source: https://inklayer.dev/zh-cn/docs/faq

在Vue中，可以使用toolbar和actions插槽来定制工具栏的显示内容，包括添加自定义按钮或替换现有组件。

```html
<PdfAnnotator>
  <template #toolbar>
    <!-- Custom toolbar content -->
  </template>
  <template #actions>
    <!-- Custom actions content -->
  </template>
</PdfAnnotator>
```

--------------------------------

### 注册自定义批注 Adapter (React)

Source: https://inklayer.dev/zh-cn/docs/architecture

演示如何使用 AdapterRegistry 为自定义批注类型注册渲染、更新和提取逻辑。

```javascript
import { AdapterRegistry } from 'inklayer-react/core'

const registry = AdapterRegistry.getInstance()

// 为自定义批注类型注册 Adapter
registry.register('custom-kind', {
  render(annotation, context) {
    // 自定义渲染逻辑
  },
  update(node, annotation, context) {
    // 自定义更新逻辑
  },
  extract(node, context) {
    // 自定义提取逻辑
  }
})

```

--------------------------------

### React导入样式

Source: https://inklayer.dev/zh-cn/docs/faq

确保在React项目中正确导入InkLayer的样式文件，以避免样式丢失或组件没有样式的问题。

```javascript
import 'inklayer-react/style';
```

--------------------------------

### React组件设置高度

Source: https://inklayer.dev/zh-cn/docs/faq

当组件渲染后页面是空白的，请检查是否为PdfAnnotator组件设置了明确的高度。此代码展示了如何在React中通过layoutStyle prop设置高度。

```javascript
<PdfAnnotator
  layoutStyle={{ width: '100%', height: '600px' }}
/>
```

--------------------------------

### 自定义工具栏 (React)

Source: https://inklayer.dev/zh-cn/docs/faq

在React中，可以使用actions prop添加自定义按钮到工具栏右侧，或使用children prop完全替换工具栏。

```javascript
// React
<PdfAnnotator
  actions={[
    // Custom action button configuration
  ]}>
  {/* Or completely replace the toolbar with custom children */}
</PdfAnnotator>
```

--------------------------------

### Basic Imports for Vue Components and Types

Source: https://inklayer.dev/zh-cn/docs/vue

Import the necessary components, styles, and types from the inklayer-vue package.

```typescript
// 组件
import { PdfViewer, PdfAnnotator } from 'inklayer-vue'
import 'inklayer-vue/style'

// 类型
import type { PdfViewerProps, PdfAnnotatorProps, User, Annotation } from 'inklayer-vue'

```

--------------------------------

### Coordinate System Comparison

Source: https://inklayer.dev/zh-cn/docs/annotation

Illustrates the difference between PDF user space coordinates and Canvas/screen coordinates. InkLayer handles automatic conversion during rendering.

```text
PDF 坐标系                     Canvas/屏幕坐标系
(0,h)────────(w,h)           (0,0)────────(w,0)
  │              │               │              │
  │  ↑Y         │               │  ↓Y         │
  │              │               │              │
(0,0)────────(w,0)          (0,h)────────(w,h)
    X →                          X →
原点：左下角                   原点：左上角
Y 轴：向上为正                  Y 轴：向下为正
```

--------------------------------

### Vue导入样式

Source: https://inklayer.dev/zh-cn/docs/faq

确保在Vue项目中正确导入InkLayer的样式文件，以避免样式丢失或组件没有样式的问题。

```javascript
import 'inklayer-vue/style';
```

--------------------------------

### Vue组件设置高度

Source: https://inklayer.dev/zh-cn/docs/faq

当组件渲染后页面是空白的，请检查是否为PdfAnnotator组件设置了明确的高度。此代码展示了如何在Vue中通过layout-style prop设置高度。

```html
<PdfAnnotator
  :layout-style="{ width: '100%', height: '600px' }"
/>
```

--------------------------------

### 设置国际化语言 (en-US)

Source: https://inklayer.dev/zh-cn/docs/faq

通过locale prop将InkLayer的界面语言设置为英文。

```javascript
locale="en-US"
```

--------------------------------

### PdfAnnotator Props

Source: https://inklayer.dev/zh-cn/docs/vue

Configuration options for the PdfAnnotator component.

```APIDOC
## PdfAnnotator Props

### url
- **Type**: `string | URL`
- **Description**: The URL address of the PDF file.

### data
- **Type**: `string | number[] | ArrayBuffer | Uint8Array | Uint16Array | Uint32Array`
- **Description**: The binary data of the PDF.

### theme
- **Type**: See theme color table below
- **Default**: `'violet'`
- **Description**: The UI theme color.

### title
- **Type**: `string`
- **Default**: `'PDF ANNOTATOR'`
- **Description**: The title of the annotator.

### locale
- **Type**: `'zh-CN' | 'en-US'`
- **Default**: `'zh-CN'`
- **Description**: The interface language.

### initialScale
- **Type**: `'auto' | 'page-actual' | 'page-fit' | 'page-width' | number`
- **Default**: `'auto'`
- **Description**: The initial zoom scale.

### layoutStyle
- **Type**: `CSSProperties`
- **Default**: `{ width: '100vw', height: '100vh' }`
- **Description**: Container style (Vue version has default values).

### user
- **Type**: `{ id: string, name: string }`
- **Default**: `{ id: 'null', name: 'unknown' }`
- **Description**: Current user information.

### enableNativeAnnotations
- **Type**: `boolean`
- **Default**: `false`
- **Description**: Whether to enable PDF.js native annotations.

### enableRange
- **Type**: `boolean | 'auto'`
- **Default**: `'auto'`
- **Description**: PDF range loading mode.

### defaultOptions
- **Type**: `Partial<PdfAnnotatorOptions>`
- **Description**: Default annotation configuration.

### initialAnnotations
- **Type**: `Annotation[]`
- **Default**: `[]`
- **Description**: Initial annotation data.

### defaultShowAnnotationsSidebar
- **Type**: `boolean`
- **Default**: `false`
- **Description**: Whether the annotation sidebar is expanded by default.

#### Theme Color Options
- **gray**: Gray
- **gold**: Gold
- **bronze**: Bronze
- **brown**: Brown
- **yellow**: Yellow
- **amber**: Amber
- **orange**: Orange
- **tomato**: Tomato
- **red**: Red
- **ruby**: Ruby
- **crimson**: Crimson
- **pink**: Pink
- **plum**: Plum
- **purple**: Purple
- **violet**: Violet (default)
- **iris**: Iris
- **indigo**: Indigo
- **blue**: Blue
- **cyan**: Cyan
- **teal**: Teal
- **jade**: Jade
- **green**: Green
- **grass**: Grass
- **lime**: Lime
- **mint**: Mint
- **sky**: Sky
```

--------------------------------

### 自定义侧边栏 (Vue)

Source: https://inklayer.dev/zh-cn/docs/architecture

演示如何在 PdfAnnotator 组件中使用 sidebar-header 和 sidebar-content 插槽来定制侧边栏内容。

```vue
<PdfAnnotator url="/doc.pdf">
  <template #sidebar-header>
    <MyCustomHeader />
  </template>
  <template #sidebar-content>
    <MyCustomAnnotationList :annotations="store.annotations" />
  </template>
</PdfAnnotator>

```

--------------------------------

### 保存批注数据 (React)

Source: https://inklayer.dev/zh-cn/docs/faq

通过onSave事件获取批注数据数组，并将其发送到后端进行存储。此代码段展示了在React中如何实现批注数据的保存。

```javascript
// React
<PdfAnnotator
  onSave={(annotations) => {
    fetch('/api/save', {
      method: 'POST',
      body: JSON.stringify(annotations),
    })
  }}
/>
```

--------------------------------

### 自定义工具栏 (React)

Source: https://inklayer.dev/zh-cn/docs/architecture

展示如何在 PdfAnnotator 组件中使用 actions 插槽来渲染自定义的保存按钮。

```jsx
<PdfAnnotator
  url="/doc.pdf"
  actions={({ save, annotations }) => (
    <button onClick={save}>
      保存 ({annotations.length} 个批注)
    </button>
  )}
/>

```

--------------------------------

### 设置国际化语言 (zh-CN)

Source: https://inklayer.dev/zh-cn/docs/faq

通过locale prop将InkLayer的界面语言设置为中文（简体）。这是默认语言。

```javascript
locale="zh-CN"
```

--------------------------------

### PdfAnnotator Expose Methods

Source: https://inklayer.dev/zh-cn/docs/vue

Methods exposed by the PdfAnnotator component that can be called via a ref.

```APIDOC
## PdfAnnotator Expose Methods

### save()
- **Description**: Triggers the save operation.

### getAnnotations()
- **Description**: Retrieves the current annotation data.
```

--------------------------------

### 保存批注数据 (Vue)

Source: https://inklayer.dev/zh-cn/docs/faq

通过@save事件获取批注数据数组，并调用自定义函数将其发送到后端进行存储。此代码段展示了在Vue中如何实现批注数据的保存。

```html
// Vue
<PdfAnnotator
  @save="(annotations) => saveToServer(annotations)"
/>
```

--------------------------------

### InkLayer 数据流图

Source: https://inklayer.dev/zh-cn/docs/architecture

展示了 InkLayer 的写入和读取数据流向，强调了从 Core 向外层传递的单向数据流。

```text
写入路径:
  用户操作 → Konva Node 创建/修改
    → Painter Editor 处理
    → Adapter.extract() 提取 Annotation
    → Store.commit() 更新状态
    → Integration 序列化 → 后端持久化

读取路径:
  后端数据 → Integration.parse() 反序列化
    → Annotation[] 对象
    → Store.load() 载入状态
    → Adapter.render() 生成 Konva Node
    → Canvas 渲染显示

```

--------------------------------

### Geometry Types for Annotation Targeting

Source: https://inklayer.dev/zh-cn/docs/annotation

Defines the supported geometric shapes for anchoring annotations, such as rectangles, quadrilaterals, paths, and lines, using PDF coordinate system values.

```typescript
interface RectGeometry {
  type: 'rect'
  rect: {
    x: number       // 左下角 x（PDF 坐标系）
    y: number       // 左下角 y（PDF 坐标系，向上为正）
    width: number
    height: number
  }
}

```

```typescript
interface PathGeometry {
  type: 'path'
  points: PdfPoint[]  // 连续路径点
  closed?: boolean      // 是否闭合路径
}

```

```typescript
interface LineGeometry {
  type: 'line'
  line: {
    start: PdfPoint
    end: PdfPoint
  }
}

```

```typescript
interface PolyGeometry {
  type: 'poly'
  poly: {
    vertices: PdfPoint[]
  }
}

```

--------------------------------

### Annotation Appearance Interface

Source: https://inklayer.dev/zh-cn/docs/annotation

Defines the properties for customizing the visual style of an annotation, such as colors, line widths, and text formatting. Ensure 'strokeColor' and 'fillColor' are valid hex strings.

```typescript
interface AnnotationAppearance {
  strokeColor?: string      // 描边颜色（十六进制）
  fillColor?: string       // 填充颜色
  opacity?: number        // 透明度 0-1
  strokeWidth?: number    // 线条宽度（pt）
  dashArray?: number[]    // 虚线样式（如 [5, 5]）
  textAlign?: string      // 文字对齐（left/center/right）
  zIndex?: number         // 图层顺序
  fontSize?: number       // 字体大小（pt）
  fontFamily?: string     // 字体族
}
```

--------------------------------

### Vue Plugin Registration

Source: https://inklayer.dev/zh-cn/docs/quick-start

Register the InkLayer Vue plugin in your main application entry point (`main.ts`). This step is mandatory before using InkLayer Vue components.

```javascript
import { createApp } from 'vue'
import { inklayerVuePlugin } from 'inklayer-vue'
import App from './App.vue'

const app = createApp(App)
app.use(inklayerVuePlugin)
app.mount('#app')

```

--------------------------------

### Annotation Relations Interface

Source: https://inklayer.dev/zh-cn/docs/annotation

Specifies how annotations can be related to each other, supporting features like replies, popups, and general linking. Use 'parentId' for direct replies.

```typescript
interface AnnotationRelations {
  parentId?: string      // 父批注 ID（回复关联）
  popupFor?: string     // Popup 注释 ID
  replies?: string[]   // 子回复 ID 列表
  linkedAnnotationIds?: string[]  // 关联批注 ID 列表
}
```

--------------------------------

### ActionsProps Interface

Source: https://inklayer.dev/zh-cn/docs/api

Interface defining actions available when 'actions' is passed as a function. Includes save, getAnnotations, exportToExcel, and exportToPdf.

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

```

--------------------------------

### ActionsProps Interface

Source: https://inklayer.dev/zh-cn/docs/api

Interface for actions when `actions` is passed as a function. It defines methods for saving, retrieving annotations, and exporting.

```APIDOC
## ActionsProps Interface

When `actions` is passed as a function, it receives the following parameters:

```typescript
interface ActionsProps {
  save: () => void                              // Trigger save
  getAnnotations: () => Annotation[]             // Get current annotations
  exportToExcel: () => void                     // Export to Excel (Vue only)
  exportToPdf: () => void                       // Export to PDF
}
```
```

--------------------------------

### Annotation Metadata Interface

Source: https://inklayer.dev/zh-cn/docs/annotation

Contains essential metadata for an annotation, including author information, source, version, and timestamps. The 'authorId' can be a simple string or an object with more details.

```typescript
interface AnnotationMeta {
  authorId: string | { id: string; name?: string; avatarUrl?: string }  // 作者信息
  isNative?: boolean      // 是否 PDF.js 原生批注
  source?: 'inklayer' | 'pdfjs' | 'import'  // 数据来源
  version?: number        // 数据版本
  createdAt?: string      // 创建时间（ISO 8601）
  updatedAt?: string      // 更新时间（ISO 8601）
}
```

--------------------------------

### InkLayer 分层架构图

Source: https://inklayer.dev/zh-cn/docs/architecture

展示了 InkLayer 从用户 API 到基础设施层的整体架构划分。

```text
┌─────────────────────────────────────────────┐
│                  用户 API 层                 │
│   PdfAnnotator / PdfViewer 组件              │
│   (React: FC + Provider、Vue: SFC + Slots)    │
├─────────────────────────────────────────────┤
│             扩展系统 (Extensions)             │
│   Toolbar / Sidebar / SelectionBar           │
│   Painter (Konva 绘制引擎)                    │
│   Editor (批注编辑器: 14 种类型)               │
│   Transform (坐标编解码器)                    │
│   Store (状态管理: Zustand / Pinia)           │
├─────────────────────────────────────────────┤
│            核心抽象层 (Core)                  │
│   Annotation Core (框架无关数据模型)          │
│   Adapter (Konva / PDF.js 适配器接口)        │
│   Integration (存储/加载/导入/导出)           │
│   Store Mapper (新旧格式双向映射)              │
├─────────────────────────────────────────────┤
│              基础设施层                       │
│   PDF.js (~4.3) - PDF 渲染引擎              │
│   Konva (9.0)   - Canvas 2D 图形            │
│   pdf-lib       - PDF 操作                  │
│   ExcelJS       - Excel 导出                │
└─────────────────────────────────────────────┘

```

--------------------------------

### Annotation Data Model Structure

Source: https://inklayer.dev/zh-cn/docs/annotation

Defines the core fields for an annotation object, including its unique ID, semantic classification, anchoring information, content, appearance, and metadata.

```typescript
interface Annotation {
  id: string                  // 全局唯一 UUID
  kind: AnnotationKind        // 语义分类
  target: AnnotationTarget   // 锚点信息
  payload?: AnnotationPayload // 语义内容（可选）
  appearance?: AnnotationAppearance  // 外观属性
  relations?: AnnotationRelations     // 关系（回复/Popup/引用）
  meta?: AnnotationMeta             // 元数据
  extensions?: Record<string, unknown>  // 扩展字段
}

```

--------------------------------

### SidebarPanel Type Definition

Source: https://inklayer.dev/zh-cn/docs/vue

Defines the structure for custom sidebar panels in the PDF viewer. Each panel requires a unique key, title, icon, and a render function.

```typescript
interface SidebarPanel {
  key: string                    // 面板唯一 key
  title: string                  // 面板标题
  icon: Vue.VNode                // 面板图标
  render: (context: PdfViewerContextValue) => Vue.VNode  // 面板内容渲染函数
}
```

--------------------------------

### SidebarPanel Type Definition

Source: https://inklayer.dev/zh-cn/docs/react

Defines the structure for custom sidebar panels. Each panel requires a unique key, title, icon, and a render function that receives the PdfViewerContextValue.

```typescript
interface SidebarPanel {
  key: string                    // Panel unique key
  title: React.ReactNode        // Panel title
  icon: React.ReactNode         // Panel icon
  render: (context: PdfViewerContextValue) => React.ReactNode  // Panel content render function
}
```

--------------------------------

### Handle Annotation Save in React

Source: https://inklayer.dev/zh-cn/docs/react

The onSave callback is triggered when the user clicks the save button. It receives the complete Annotation array, which can be directly saved. This snippet shows how to send the annotations to a backend API.

```javascript
const handleSave = (annotations: Annotation[]) => {
  // annotations is already in the complete format, can be sent directly
  fetch('/api/annotations', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(annotations),
  })
}
```

--------------------------------

### PdfAnnotatorOptions Type Definition

Source: https://inklayer.dev/zh-cn/docs/vue

Defines options for customizing the default behavior of the PDF annotator, including color palettes, signature settings, and stamp configurations.

```typescript
interface PdfAnnotatorOptions {
  colors?: string[]  // 可用颜色列表

  signature?: {
    colors?: string[]                    // 签名可选颜色列表
    type?: 'Draw' | 'Enter' | 'Upload'   // 签名类型（首字母大写）
    maxSize?: number                     // 签名图片最大文件大小（字节）
    accept?: string                      // 接受的图片格式
    defaultSignature?: string[]          // 默认签名列表
    defaultFont?: {
      label: string
      value: string
      external?: boolean
      url?: string                     // 外部字体 URL
    }[]
  }

  stamp?: {
    maxSize?: number                     // 印章图片最大文件大小
    accept?: string                      // 接受的图片格式
    defaultStamp?: string[]              // 默认印章列表
    editor?: {
      defaultBackgroundColor?: string
      defaultBorderColor?: string
      defaultBorderStyle?: 'none' | 'solid' | 'dashed'
      defaultTextColor?: string
      defaultFont?: {
        label: string
        value: string
      }[]
    }
  }
}
```

--------------------------------

### PdfAnnotator Events

Source: https://inklayer.dev/zh-cn/docs/vue

Events emitted by the PdfAnnotator component.

```APIDOC
## PdfAnnotator Events

### save
- **Parameters**: `(annotations: Annotation[])`
- **Trigger**: User clicks save.

### load
- **Parameters**: `()`
- **Trigger**: PDF loading is complete.

### annotation-added
- **Parameters**: `(annotation: Annotation)`
- **Trigger**: A new annotation is created.

### annotation-deleted
- **Parameters**: `(id: string)`
- **Trigger**: An annotation is deleted.

### annotation-selected
- **Parameters**: `(annotation: Annotation | null, isClick: boolean)`
- **Trigger**: An annotation is selected or deselected.

### annotation-updated
- **Parameters**: `(annotation: Annotation)`
- **Trigger**: An annotation is updated.
```

--------------------------------

### Annotation Interface Definition

Source: https://inklayer.dev/zh-cn/docs/api

Defines the structure of an annotation object, including its unique ID, semantic classification, anchor information, and optional content, appearance, relations, and metadata.

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

```

--------------------------------

### Coordinate Conversion Functions

Source: https://inklayer.dev/zh-cn/docs/annotation

Functions for converting points between PDF user space and Canvas space. These are automatically called by InkLayer during rendering and annotation extraction.

```javascript
// PDF 空间 → Canvas 空间（渲染时自动调用）
pdfToCanvasPoint(pdfPoint, viewportCtx): CanvasPoint

// Canvas 空间 → PDF 空间（提取批注时自动调用）
canvasToPdfPoint(canvasPoint, viewportCtx): PdfPoint
```

--------------------------------

### PdfViewerContextValue Interface (React)

Source: https://inklayer.dev/zh-cn/docs/api

Interface for PdfViewer context value in React. Provides access to pageIndex, scale, pdfDocument, and methods like goToPage, zoomTo, getAnnotations, and save.

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

```

--------------------------------

### SidebarPanel Type (React)

Source: https://inklayer.dev/zh-cn/docs/api

Type definition for the `SidebarPanel` in React, specifying the possible panels that can be displayed in the sidebar.

```APIDOC
## SidebarPanel Type (React)

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

--------------------------------

### AnnotationTarget: PDF Anchoring Information

Source: https://inklayer.dev/zh-cn/docs/annotation

Specifies where an annotation is located on a PDF page, including the page index and geometric details within the PDF user space coordinate system.

```typescript
interface AnnotationTarget {
  pageIndex: number      // 所在页码（从 0 开始）
  geometry: Geometry     // 几何图形
  coordinateSystem: 'pdf-user-space'  // 坐标系标识（仅此一个值）
}

```

--------------------------------

### PdfAnnotator Slots

Source: https://inklayer.dev/zh-cn/docs/vue

Custom content slots available in the PdfAnnotator component.

```APIDOC
## PdfAnnotator Slots

### actions
- **Slot Props**: `{ onSave, getAnnotations, exportToExcel, exportToPdf }`
- **Description**: Custom actions area, rendered on the right side of the toolbar.
```

--------------------------------

### PdfViewerContextValue Interface (React)

Source: https://inklayer.dev/zh-cn/docs/api

Interface for the context value obtained through `PdfViewerContext` in React. It provides access to viewer state and control methods.

```APIDOC
## PdfViewerContextValue Interface (React)

Obtained via `PdfViewerContext`:

```typescript
interface PdfViewerContextValue {
  pageIndex: number              // Current page number
  scale: number                  // Current zoom level
  pdfDocument: PDFDocumentProxy | null  // PDF document instance
  goToPage: (pageIndex: number) => void
  zoomTo: (scale: number | 'auto') => void
  getAnnotations: () => Annotation[]
  save: () => void
}
```
```

--------------------------------

### SidebarPanel Type

Source: https://inklayer.dev/zh-cn/docs/api

Type definition for the SidebarPanel component in React. Specifies the possible panels: 'search', 'annotations', 'outline', 'thumbnails'.

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

```

--------------------------------

### PdfViewerContextValue Type Definition

Source: https://inklayer.dev/zh-cn/docs/react

Defines the context value provided to functions within the sidebar, actions, and toolbar. It includes PDF viewer instance, pagination, zoom level, and various control actions.

```typescript
interface PdfViewerContextValue {
  pdfViewer: PDFViewer | null    // PDFViewer instance
  currentPage: number           // Current page number (0-based)
  totalPages: number            // Total number of pages
  scale: number                 // Current zoom scale
  print: () => void           // Print function
  download: (filename?: string) => void  // Download function
  toggleSidebar: () => void   // Toggle sidebar function
  scrollPageIntoView: (opts: { pageNumber: number }) => void  // Scroll to a specific page function
}
```

--------------------------------

### PdfViewer Props

Source: https://inklayer.dev/zh-cn/docs/api

Props for the PdfViewer component. It is a read-only PDF viewer and does not support annotation editing. Other props are consistent with PdfAnnotator, excluding annotation-related callbacks.

```APIDOC
## PdfViewer Props

`PdfViewer` is a read-only PDF viewer that does not support annotation editing. Its other props are consistent with `PdfAnnotator` (excluding annotation-related callbacks).

| Prop | Type | Default Value | Description |
|---|---|---|---|
| `url` | `string | ArrayBuffer | Uint8Array` | Required | URL or data of the PDF document |
| `user` | `User` | — | User information (optional for read-only scenarios) |
| `initialPage` | `number` | `0` | Initial page number |
| `initialScale` | `number | 'auto'` | `'auto'` | Initial zoom level, `'auto'` = fit to width |
| `layoutStyle` | `React.CSSProperties / Vue.StyleValue` | Same as PdfAnnotator | Container style |
| `onDocumentLoaded` | `(pdfDocument: PDFDocumentProxy) => void` | — | Callback when the PDF document is loaded |
| `onEventBusReady` | `(eventBus: EventBus) => void` | — | Callback when the EventBus is ready |
| `onPageChanged` | `(pageIndex: number) => void` | — | Callback when the page changes |
| `onZoomChanged` | `(scale: number) => void` | — | Callback when the zoom level changes |
| `onError` | `(error: Error) => void` | — | Callback for errors |
```

--------------------------------

### PdfViewerContextValue Type Definition

Source: https://inklayer.dev/zh-cn/docs/vue

Represents the context value passed to slots or functions for actions, toolbar, and sidebar. It provides access to the PDFViewer instance and various control methods.

```typescript
interface PdfViewerContextValue {
  pdfViewer: PDFViewer | null    // PDFViewer 实例
  currentPage: number           // 当前页码（0-based）
  totalPages: number            // 总页数
  scale: number                 // 当前缩放比例
  print: () => void           // 打印
  download: (filename?: string) => void  // 下载
  toggleSidebar: () => void   // 切换侧边栏
  scrollPageIntoView: (opts: { pageNumber: number }) => void  // 滚动到指定页
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.