react-pdf-highlighter介绍

react-pdf-highlighter 是一个 React 组件库，用于在 Web 项目中实现 PDF 文档的阅读、文字选中高亮、批注（Annotation）和高亮区域跳转 的功能。它基于 PDF.js 渲染 PDF，并提供了交互层来处理高亮和注释。

适合用在：在线文档阅读器、知识标注、批注系统、学习笔记工具、电子合同标记 等场景。

1. 核心功能

PDF 渲染
- 使用 PDF.js 在浏览器渲染 PDF
文字高亮（Highlighting）
- 用户可以用鼠标拖选文本并创建高亮
矩形高亮（Area Highlight）
- 选中 PDF 上任意区域进行框选高亮（适合图片或扫描件）
注释/评论
- 每个高亮可绑定元数据（如评论、标签、ID）
高亮列表 & 跳转
- 通过高亮 ID 快速跳转到对应页面和位置
受控组件
- 高亮数据完全由外部状态管理，可存储到后端或本地

2. 安装

npm install react-pdf-highlighter

依赖：需要先安装 react、react-dom 和 pdfjs-dist。

3. 基本用法

1) 渲染 PDF 并支持高亮

import React, { useState } from "react";
import {
  PdfLoader,
  PdfHighlighter,
  Tip,
  Highlight,
  Popup
} from "react-pdf-highlighter";

function PDFViewer() {
  const [highlights, setHighlights] = useState([]);

  const url = "https://arxiv.org/pdf/1708.08021.pdf"; // PDF 文件地址

  return (
    <PdfLoader url={url} beforeLoad={<div>Loading PDF...</div>}>
      {pdfDocument => (
        <PdfHighlighter
          pdfDocument={pdfDocument}
          highlights={highlights} // 当前所有高亮
          onSelectionFinished={(position, content, hideTipAndSelection) => {
            const newHighlight = {
              id: String(Math.random()),
              position,
              content
            };
            setHighlights([...highlights, newHighlight]);
            hideTipAndSelection(); // 隐藏选择框
          }}
          highlightTransform={(highlight, index, setTip, hideTip) => (
            <Highlight
              key={index}
              isScrolledTo={false}
              position={highlight.position}
              comment={highlight.content.text}
            />
          )}
        />
      )}
    </PdfLoader>
  );
}

export default PDFViewer;

上面例子说明了核心概念：

PdfLoader：加载并解析 PDF 文件
PdfHighlighter：主渲染组件，负责高亮逻辑
onSelectionFinished：用户完成选中时触发，返回坐标和内容
Highlight：渲染单个高亮
highlights：受控高亮数组，类似于 React state

4. 高亮数据结构

官方示例的高亮对象通常包含：

{
  id: "highlight-id-1",
  position: {
    pageNumber: 1,
    boundingRect: {...},        // 单个选区矩形
    rects: [...],               // 多个选区矩形
    usePdfCoordinates: true
  },
  content: {
    text: "选中的文字",
    image: null
  },
  comment: {
    text: "批注",
    emoji: "⭐️"
  }
}

position 和 content 是核心，用于确定高亮区域和显示文字。

5. 常用 Props

Prop	说明
`pdfDocument`	PDF.js 的文档对象（由 `PdfLoader` 提供）
`highlights`	高亮数组（受控）
`onSelectionFinished`	用户完成选中时的回调
`highlightTransform`	自定义每个高亮的渲染方式
`scrollRef`	获取滚动容器 ref，用于跳转
`enableAreaSelection`	支持矩形区域选择高亮
`onScrollChange`	页面滚动时触发，可记录阅读进度

6. 典型应用场景

在线文档批注系统
- 类似 Kindle、Notion、PDF Expert 的高亮和注释
学习笔记/标记工具
- 对 PDF 论文进行高亮标记、做笔记
合同或文件审批
- 在文档中高亮关键条款并添加批注
电子书或内部文档阅读器
- 结合用户登录，实现个人高亮和跨端同步

7. 优缺点

优点：

专注于 PDF 高亮和注释
提供文字与矩形高亮两种模式
高亮受控，可存储与同步

缺点：

样式较基础，需要自定义 UI
对大文件性能一般（底层是 PDF.js 渲染）
不支持 PDF 编辑或导出带高亮的 PDF（只能记录数据）