# PDF 拖拽插入用户名功能说明

## 功能概述

在 PDF 文档中，通过拖拽按钮可以将用户名以批注、文本框或印章的形式插入到文档中。

## PDF 的特殊性

### 为什么 PDF 不同？
- PDF 是**只读格式**，不能直接编辑文本
- 但可以添加**批注**、**标记**、**印章**等
- WPS 提供了多种 PDF 标注方式

### 支持的插入方式
1. **文本批注**（FreeText）- 可编辑的文本框
2. **普通批注**（Comment）- 带作者信息的批注
3. **高亮标记**（Highlight）- 高亮显示文本
4. **文本印章**（Stamp）- 印章样式的文本

## 使用方法

### 方式 1：文本批注（推荐）

**操作步骤**：
1. 打开 PDF 文档
2. 拖拽"拖我到文档中"按钮到 PDF 页面
3. 松开鼠标
4. 用户名会以红色文本框形式出现在页面中心
5. 可以拖动文本框到任意位置
6. 可以双击编辑文本内容

**特点**：
- ✅ 可以自由移动位置
- ✅ 可以编辑文本
- ✅ 可以调整大小
- ✅ 显示效果好

**效果示例**：
```
┌─────────────────┐
│   张三          │  ← 红色文本框
└─────────────────┘
```

### 方式 2：普通批注

**操作步骤**：
1. 拖拽按钮到 PDF
2. 系统自动添加批注
3. 批注显示在页面右侧

**特点**：
- ✅ 带作者信息
- ✅ 带时间戳
- ✅ 可以回复
- ❌ 位置固定

**效果示例**：
```
📝 张三 (2025-12-29 10:30)
   张三
```

### 方式 3：高亮标记

**操作步骤**：
1. 先在 PDF 中选中一段文字
2. 拖拽按钮
3. 选中的文字会被高亮，并添加批注

**特点**：
- ✅ 突出显示
- ✅ 关联原文
- ❌ 需要先选中文字

**效果示例**：
```
这是一段文字 [黄色高亮]
批注：张三
```

### 方式 4：文本印章

**操作步骤**：
1. 拖拽按钮到 PDF
2. 用户名以印章形式显示

**特点**：
- ✅ 正式感强
- ✅ 不易修改
- ❌ 样式固定

**效果示例**：
```
╔═══════╗
║ 张三  ║  ← 红色印章
╚═══════╝
```

## 自动降级机制

代码会按顺序尝试以下方法，直到成功：

```
1. 尝试添加文本批注（FreeText）
   ↓ 失败
2. 尝试添加普通批注（Comment）
   ↓ 失败
3. 尝试添加高亮标记（Highlight）
   ↓ 失败
4. 尝试添加文本印章（Stamp）
   ↓ 失败
5. 提示使用 WPS 自带批注工具
```

## 技术实现

### 方法 1：文本批注
```typescript
const annotation = await currentPage.AddAnnotation({
  type: 'FreeText',
  rect: {
    left: pageWidth / 2 - 100,
    top: pageHeight / 2 - 20,
    right: pageWidth / 2 + 100,
    bottom: pageHeight / 2 + 20
  },
  contents: userName,
  color: { r: 255, g: 0, b: 0 },
  fontSize: 14
});
```

### 方法 2：普通批注
```typescript
await pdfDoc.AddComment({
  text: userName,
  author: userStore.userName || '审核人',
  color: '#FF0000'
});
```

### 方法 3：高亮标记
```typescript
const selection = await app.ActivePDF.Selection;
await selection.AddTextMarkup({
  type: 'Highlight',
  text: userName,
  color: '#FFFF00'
});
```

### 方法 4：文本印章
```typescript
await pdfDoc.AddStamp({
  text: userName,
  position: 'center',
  color: '#FF0000',
  fontSize: 14
});
```

## 使用场景

### 场景 1：审核签名
```
PDF 文档内容...

[文本框: 审核人：张三]
[文本框: 审核时间：2025-12-29]
```

### 场景 2：批注标记
```
PDF 文档内容...

📝 张三: 此处需要修改
```

### 场景 3：审批印章
```
PDF 文档内容...

╔═══════╗
║ 张三  ║
║ 已审核 ║
╚═══════╝
```

## 注意事项

### 1. WPS PDF 编辑器必须支持批注功能
- 确保使用的是完整版 WPS
- 部分精简版可能不支持批注

### 2. 插入位置
- 文本批注：默认在页面中心
- 普通批注：在页面右侧
- 高亮标记：需要先选中文字
- 文本印章：在页面中心

### 3. 移动和编辑
- 文本批注可以拖动和编辑
- 普通批注位置固定
- 印章不可编辑

### 4. 保存
- 批注会保存在 PDF 文件中
- 其他人打开也能看到
- 可以导出带批注的 PDF

## 常见问题

### Q1: 拖拽后没有反应？
**可能原因**：
1. WPS PDF 编辑器不支持批注
2. PDF 文件被保护
3. 权限不足

**解决方法**：
1. 检查 WPS 版本
2. 检查 PDF 是否可编辑
3. 尝试使用 WPS 自带的批注工具

### Q2: 提示"PDF 操作失败"？
**原因**：
- WPS API 不支持当前操作
- PDF 文件格式问题

**解决方法**：
1. 查看浏览器控制台的详细错误
2. 尝试使用 WPS 桌面版
3. 使用 WPS 自带的批注工具手动添加

### Q3: 文本框位置不对？
**原因**：
- 默认在页面中心
- 页面大小计算可能不准确

**解决方法**：
- 插入后手动拖动到目标位置
- 或者使用 WPS 工具栏的批注功能

### Q4: 可以修改文本框的样式吗？
**答案**：
- 可以！插入后：
  - 右键点击文本框
  - 选择"属性"
  - 修改颜色、字体、大小等

### Q5: 批注会保存吗？
**答案**：
- 会！批注是 PDF 的一部分
- 保存文档后，批注会一起保存
- 其他人打开也能看到

## 备用方案

### 如果自动插入失败

**方案 1：使用 WPS 工具栏**
1. 点击 WPS 工具栏的"批注"按钮
2. 选择"文本框"或"便签"
3. 在文档中点击要添加的位置
4. 输入用户名

**方案 2：使用快捷键**
1. 按 `Ctrl + Alt + M` 添加批注
2. 输入用户名
3. 点击确定

**方案 3：使用印章功能**
1. 点击 WPS 工具栏的"印章"按钮
2. 选择"文本印章"
3. 输入用户名
4. 点击文档添加

## WPS PDF API 参考

### 常用 API
```typescript
// 获取 PDF 文档对象
const pdfDoc = await app.ActivePDF;

// 获取当前页面
const currentPage = await pdfDoc.CurrentPage;

// 添加批注
await currentPage.AddAnnotation({...});

// 添加评论
await pdfDoc.AddComment({...});

// 添加印章
await pdfDoc.AddStamp({...});
```

### 批注类型
- `FreeText` - 自由文本
- `Text` - 便签批注
- `Highlight` - 高亮
- `Underline` - 下划线
- `StrikeOut` - 删除线
- `Stamp` - 印章

## 浏览器兼容性

| 浏览器 | 支持情况 | 备注 |
|--------|---------|------|
| Chrome 90+ | ✅ 完全支持 | 推荐使用 |
| Edge 90+ | ✅ 完全支持 | 推荐使用 |
| Firefox 88+ | ⚠️ 部分支持 | 某些 API 可能不可用 |
| Safari 14+ | ⚠️ 部分支持 | 某些 API 可能不可用 |

## 未来改进

### 计划中的功能
- [ ] 支持自定义批注颜色
- [ ] 支持自定义字体大小
- [ ] 支持批注模板
- [ ] 支持批注位置记忆
- [ ] 支持批量添加批注

### 用户体验优化
- [ ] 拖拽时显示预览
- [ ] 插入位置智能推荐
- [ ] 批注样式预设
- [ ] 快捷键支持

## 总结

PDF 拖拽插入用户名功能：
- ✅ 支持多种插入方式
- ✅ 自动降级机制
- ✅ 可以移动和编辑
- ✅ 批注会保存在文件中
- ⚠️ 依赖 WPS API 支持

如果自动插入失败，可以使用 WPS 自带的批注工具手动添加！