突破PDF阅读限制：AndroidPdfViewer全功能批注系统开发指南

2026-02-05 05:25:36作者：伍霜盼Ellen

你是否还在为Android应用中PDF批注功能开发而烦恼？用户需要高亮重点、添加注释、手绘标记时，现有工具是否无法满足需求？本文将基于AndroidPdfViewer框架，从零构建完整的PDF批注系统，实现高亮、注释与绘图三大核心功能，让你的应用轻松支持专业级文档标注。

读完本文你将获得：

基于OnDrawListener实现批注图层绘制的完整方案
三种批注工具（高亮/注释/绘图）的实现代码
批注数据持久化存储与加载的最佳实践
与PDFView无缝集成的交互处理技巧

批注功能核心原理与架构设计

AndroidPdfViewer框架本身提供了基础的PDF渲染能力，但批注功能需要通过扩展实现。框架中PDFView.java的onDraw方法和OnDrawListener.java接口为自定义绘制提供了关键支持。

批注系统架构

graph TD
    A[PDFView渲染层] --> B[OnDrawListener回调]
    B --> C[批注管理层]
    C --> D[高亮工具]
    C --> E[注释工具]
    C --> F[绘图工具]
    C --> G[批注数据存储]
    D --> H[Canvas绘制]
    E --> H
    F --> H

核心实现基于以下技术点：

图层叠加机制：利用PDFView的enableAnnotationRendering(true)方法启用批注渲染
自定义绘制：通过实现OnDrawListener接口在PDF页面上绘制批注内容
坐标转换：将屏幕触摸坐标转换为PDF文档坐标
数据持久化：保存批注数据与PDF页面关联

环境配置与基础集成

启用批注渲染功能

在PDFView初始化时，必须启用批注渲染功能。参考PDFViewActivity.java中的实现：

pdfView.fromAsset(SAMPLE_FILE)
    .defaultPage(pageNumber)
    .onPageChange(this)
    .enableAnnotationRendering(true)  // 启用批注渲染
    .onLoad(this)
    .scrollHandle(new DefaultScrollHandle(this))
    .spacing(10)
    .onPageError(this)
    .pageFitPolicy(FitPolicy.BOTH)
    .load();

创建批注管理类

实现批注功能需要创建一个集中管理批注数据和绘制逻辑的类：

public class AnnotationManager implements OnDrawListener {
    private List<Annotation> annotations = new ArrayList<>();
    
    @Override
    public void onLayerDrawn(Canvas canvas, float pageWidth, float pageHeight, int displayedPage) {
        // 绘制所有批注
        for (Annotation annotation : annotations) {
            if (annotation.getPage() == displayedPage) {
                annotation.draw(canvas, pageWidth, pageHeight);
            }
        }
    }
    
    // 添加批注
    public void addAnnotation(Annotation annotation) {
        annotations.add(annotation);
    }
    
    // 保存批注到文件
    public void saveAnnotations(Context context, String pdfId) {
        // 实现持久化逻辑
    }
    
    // 从文件加载批注
    public void loadAnnotations(Context context, String pdfId) {
        // 实现加载逻辑
    }
}

高亮工具实现：文本选择与高亮绘制

文本选择实现

实现文本高亮首先需要处理文本选择逻辑，通过监听PDFView的触摸事件，确定用户选择的文本区域：

public class HighlightTool {
    private PDFView pdfView;
    private RectF selectedArea = null;
    private int currentPage = -1;
    
    public HighlightTool(PDFView pdfView) {
        this.pdfView = pdfView;
        setupTouchListener();
    }
    
    private void setupTouchListener() {
        pdfView.setOnTouchListener(new View.OnTouchListener() {
            private PointF start = null;
            
            @Override
            public boolean onTouch(View v, MotionEvent event) {
                if (event.getAction() == MotionEvent.ACTION_DOWN) {
                    start = new PointF(event.getX(), event.getY());
                    currentPage = pdfView.getCurrentPage();
                } else if (event.getAction() == MotionEvent.ACTION_UP) {
                    PointF end = new PointF(event.getX(), event.getY());
                    selectedArea = new RectF(Math.min(start.x, end.x), Math.min(start.y, end.y),
                                           Math.max(start.x, end.x), Math.max(start.y, end.y));
                    // 转换为PDF坐标
                    RectF pdfArea = convertToPdfCoordinates(selectedArea, currentPage);
                    // 创建高亮批注
                    addHighlightAnnotation(pdfArea, currentPage);
                }
                return true;
            }
        });
    }
    
    private RectF convertToPdfCoordinates(RectF screenArea, int page) {
        // 实现屏幕坐标到PDF坐标的转换逻辑
        // 参考PDFView.java中的坐标转换方法
        float zoom = pdfView.getZoom();
        return new RectF(
            screenArea.left / zoom,
            screenArea.top / zoom,
            screenArea.right / zoom,
            screenArea.bottom / zoom
        );
    }
    
    private void addHighlightAnnotation(RectF area, int page) {
        HighlightAnnotation annotation = new HighlightAnnotation(area, page, Color.YELLOW);
        annotationManager.addAnnotation(annotation);
        pdfView.invalidate();  // 触发重绘
    }
}

高亮批注绘制

创建高亮批注类实现具体绘制逻辑：

public class HighlightAnnotation extends Annotation {
    private RectF area;
    private int color;
    
    public HighlightAnnotation(RectF area, int page, int color) {
        super(page);
        this.area = area;
        this.color = color;
    }
    
    @Override
    public void draw(Canvas canvas, float pageWidth, float pageHeight) {
        Paint paint = new Paint();
        paint.setColor(color);
        paint.setAlpha(100);  // 半透明效果
        paint.setStyle(Paint.Style.FILL);
        
        // 根据页面尺寸缩放批注区域
        float scaleX = pageWidth;
        float scaleY = pageHeight;
        
        RectF scaledArea = new RectF(
            area.left * scaleX,
            area.top * scaleY,
            area.right * scaleX,
            area.bottom * scaleY
        );
        
        canvas.drawRect(scaledArea, paint);
    }
}

注释工具实现：添加文本注释与弹窗交互

注释工具允许用户在PDF页面特定位置添加文本注释，需要解决注释框定位、文本输入和显示问题。

注释工具核心代码

public class NoteTool {
    private PDFView pdfView;
    private AnnotationManager annotationManager;
    private Context context;
    
    public NoteTool(PDFView pdfView, AnnotationManager annotationManager, Context context) {
        this.pdfView = pdfView;
        this.annotationManager = annotationManager;
        this.context = context;
        setupTouchListener();
    }
    
    private void setupTouchListener() {
        pdfView.setOnTouchListener(new View.OnTouchListener() {
            @Override
            public boolean onTouch(View v, MotionEvent event) {
                if (event.getAction() == MotionEvent.ACTION_UP) {
                    float x = event.getX();
                    float y = event.getY();
                    int page = pdfView.getCurrentPage();
                    
                    // 显示文本输入对话框
                    showNoteInputDialog(x, y, page);
                    return true;
                }
                return false;
            }
        });
    }
    
    private void showNoteInputDialog(float x, float y, int page) {
        AlertDialog.Builder builder = new AlertDialog.Builder(context);
        builder.setTitle("添加注释");
        
        final EditText input = new EditText(context);
        builder.setView(input);
        
        builder.setPositiveButton("保存", new DialogInterface.OnClickListener() {
            @Override
            public void onClick(DialogInterface dialog, int which) {
                String text = input.getText().toString();
                if (!text.isEmpty()) {
                    // 转换坐标并创建注释
                    PointF pdfPoint = convertToPdfCoordinates(x, y, page);
                    addNoteAnnotation(pdfPoint, page, text);
                }
            }
        });
        
        builder.setNegativeButton("取消", null);
        builder.show();
    }
    
    private void addNoteAnnotation(PointF position, int page, String text) {
        NoteAnnotation annotation = new NoteAnnotation(position, page, text);
        annotationManager.addAnnotation(annotation);
        pdfView.invalidate();
    }
}

注释批注绘制实现

public class NoteAnnotation extends Annotation {
    private PointF position;
    private String text;
    private static final float ICON_SIZE = 30;
    private static final float NOTE_BOX_WIDTH = 200;
    private static final float NOTE_BOX_HEIGHT = 100;
    
    public NoteAnnotation(PointF position, int page, String text) {
        super(page);
        this.position = position;
        this.text = text;
    }
    
    @Override
    public void draw(Canvas canvas, float pageWidth, float pageHeight) {
        Paint paint = new Paint();
        
        // 绘制注释图标
        paint.setColor(Color.BLUE);
        canvas.drawCircle(position.x * pageWidth, position.y * pageHeight, ICON_SIZE, paint);
        
        // 绘制注释文本框
        paint.setColor(Color.WHITE);
        paint.setStyle(Paint.Style.FILL);
        RectF noteBox = new RectF(
            position.x * pageWidth + ICON_SIZE,
            position.y * pageHeight - NOTE_BOX_HEIGHT/2,
            position.x * pageWidth + ICON_SIZE + NOTE_BOX_WIDTH,
            position.y * pageHeight + NOTE_BOX_HEIGHT/2
        );
        canvas.drawRect(noteBox, paint);
        
        // 绘制文本
        paint.setColor(Color.BLACK);
        paint.setTextSize(14);
        float textY = noteBox.top + 20;
        for (String line : text.split("\n")) {
            canvas.drawText(line, noteBox.left + 10, textY, paint);
            textY += 20;
        }
    }
}

绘图工具实现：自由手绘与笔触控制

绘图工具允许用户在PDF页面上自由绘制线条，需要处理路径记录、笔触样式设置等功能。

绘图工具实现代码

public class DrawingTool {
    private PDFView pdfView;
    private AnnotationManager annotationManager;
    private Path currentPath;
    private boolean isDrawing = false;
    private Paint drawingPaint;
    private int currentPage;
    
    public DrawingTool(PDFView pdfView, AnnotationManager annotationManager) {
        this.pdfView = pdfView;
        this.annotationManager = annotationManager;
        setupDrawingPaint();
        setupTouchListener();
    }
    
    private void setupDrawingPaint() {
        drawingPaint = new Paint();
        drawingPaint.setColor(Color.RED);
        drawingPaint.setStyle(Paint.Style.STROKE);
        drawingPaint.setStrokeWidth(5);
        drawingPaint.setAntiAlias(true);
    }
    
    private void setupTouchListener() {
        pdfView.setOnTouchListener(new View.OnTouchListener() {
            @Override
            public boolean onTouch(View v, MotionEvent event) {
                float x = event.getX();
                float y = event.getY();
                currentPage = pdfView.getCurrentPage();
                
                switch (event.getAction()) {
                    case MotionEvent.ACTION_DOWN:
                        startDrawing(x, y);
                        break;
                    case MotionEvent.ACTION_MOVE:
                        continueDrawing(x, y);
                        break;
                    case MotionEvent.ACTION_UP:
                        finishDrawing();
                        break;
                }
                return true;
            }
        });
    }
    
    private void startDrawing(float x, float y) {
        currentPath = new Path();
        PointF pdfPoint = convertToPdfCoordinates(x, y, currentPage);
        currentPath.moveTo(pdfPoint.x, pdfPoint.y);
        isDrawing = true;
    }
    
    private void continueDrawing(float x, float y) {
        if (isDrawing && currentPath != null) {
            PointF pdfPoint = convertToPdfCoordinates(x, y, currentPage);
            currentPath.lineTo(pdfPoint.x, pdfPoint.y);
            pdfView.invalidate();
        }
    }
    
    private void finishDrawing() {
        if (isDrawing && currentPath != null) {
            DrawingAnnotation annotation = new DrawingAnnotation(currentPath, currentPage, 
                                                                drawingPaint.getColor(), 
                                                                drawingPaint.getStrokeWidth());
            annotationManager.addAnnotation(annotation);
            currentPath = null;
            isDrawing = false;
            pdfView.invalidate();
        }
    }
}

批注数据持久化与加载

批注数据需要保存到设备存储中，以便下次打开PDF时恢复批注内容。最佳实践是使用JSON格式存储批注数据。

批注数据模型与存储

public class AnnotationManager {
    // ... 其他代码 ...
    
    // 保存批注到文件
    public void saveAnnotations(Context context, String pdfId) {
        try {
            File file = new File(context.getFilesDir(), pdfId + "_annotations.json");
            FileWriter writer = new FileWriter(file);
            
            JSONArray jsonAnnotations = new JSONArray();
            for (Annotation annotation : annotations) {
                JSONObject json = new JSONObject();
                json.put("type", annotation.getType());
                json.put("page", annotation.getPage());
                
                // 根据批注类型存储不同数据
                if (annotation instanceof HighlightAnnotation) {
                    HighlightAnnotation highlight = (HighlightAnnotation) annotation;
                    json.put("left", highlight.getArea().left);
                    json.put("top", highlight.getArea().top);
                    json.put("right", highlight.getArea().right);
                    json.put("bottom", highlight.getArea().bottom);
                    json.put("color", highlight.getColor());
                } else if (annotation instanceof NoteAnnotation) {
                    // 处理注释批注...
                } else if (annotation instanceof DrawingAnnotation) {
                    // 处理绘图批注...
                }
                
                jsonAnnotations.put(json);
            }
            
            writer.write(jsonAnnotations.toString());
            writer.close();
        } catch (Exception e) {
            Log.e("AnnotationManager", "保存批注失败", e);
        }
    }
    
    // 从文件加载批注
    public void loadAnnotations(Context context, String pdfId) {
        annotations.clear();
        
        try {
            File file = new File(context.getFilesDir(), pdfId + "_annotations.json");
            if (!file.exists()) return;
            
            FileReader reader = new FileReader(file);
            JSONArray jsonAnnotations = new JSONArray(new JSONTokener(reader));
            
            for (int i = 0; i < jsonAnnotations.length(); i++) {
                JSONObject json = jsonAnnotations.getJSONObject(i);
                String type = json.getString("type");
                int page = json.getInt("page");
                
                switch (type) {
                    case "highlight":
                        RectF area = new RectF(
                            (float) json.getDouble("left"),
                            (float) json.getDouble("top"),
                            (float) json.getDouble("right"),
                            (float) json.getDouble("bottom")
                        );
                        int color = json.getInt("color");
                        annotations.add(new HighlightAnnotation(area, page, color));
                        break;
                    // 加载其他类型批注...
                }
            }
        } catch (Exception e) {
            Log.e("AnnotationManager", "加载批注失败", e);
        }
    }
}

完整集成与交互处理

将三种批注工具整合到应用中，并处理工具切换、用户交互等问题。

批注工具管理器实现

public class AnnotationToolManager {
    public enum ToolType { HIGHLIGHT, NOTE, DRAWING, SELECT }
    
    private ToolType currentTool = ToolType.SELECT;
    private HighlightTool highlightTool;
    private NoteTool noteTool;
    private DrawingTool drawingTool;
    private PDFView pdfView;
    private AnnotationManager annotationManager;
    private Context context;
    
    public AnnotationToolManager(PDFView pdfView, Context context) {
        this.pdfView = pdfView;
        this.context = context;
        this.annotationManager = new AnnotationManager();
        
        // 初始化所有工具
        highlightTool = new HighlightTool(pdfView, annotationManager);
        noteTool = new NoteTool(pdfView, annotationManager, context);
        drawingTool = new DrawingTool(pdfView, annotationManager);
        
        // 设置默认工具
        setCurrentTool(ToolType.SELECT);
    }
    
    public void setCurrentTool(ToolType toolType) {
        currentTool = toolType;
        
        // 重置所有工具的触摸监听
        pdfView.setOnTouchListener(null);
        
        // 为当前选中的工具设置触摸监听
        switch (toolType) {
            case HIGHLIGHT:
                highlightTool.enable();
                break;
            case NOTE:
                noteTool.enable();
                break;
            case DRAWING:
                drawingTool.enable();
                break;
            case SELECT:
                // 恢复默认的PDFView触摸行为
                pdfView.resetTouchHandling();
                break;
        }
    }
    
    public void saveAnnotations(String pdfId) {
        annotationManager.saveAnnotations(context, pdfId);
    }
    
    public void loadAnnotations(String pdfId) {
        annotationManager.loadAnnotations(context, pdfId);
        pdfView.invalidate();
    }
}

在Activity中集成批注功能

参考PDFViewActivity.java的实现，添加批注工具集成代码：

public class PDFViewActivity extends AppCompatActivity implements OnPageChangeListener, OnLoadCompleteListener {
    private PDFView pdfView;
    private AnnotationToolManager annotationToolManager;
    private String currentPdfId;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        pdfView = findViewById(R.id.pdfView);
        annotationToolManager = new AnnotationToolManager(pdfView, this);
        
        // 加载PDF文件
        currentPdfId = "sample"; // 实际应用中应使用唯一ID
        displayFromAsset(SAMPLE_FILE);
        
        // 加载批注
        annotationToolManager.loadAnnotations(currentPdfId);
        
        // 设置批注工具切换按钮
        setupToolButtons();
    }
    
    private void setupToolButtons() {
        Button highlightBtn = findViewById(R.id.btn_highlight);
        Button noteBtn = findViewById(R.id.btn_note);
        Button drawBtn = findViewById(R.id.btn_draw);
        Button selectBtn = findViewById(R.id.btn_select);
        
        highlightBtn.setOnClickListener(v -> annotationToolManager.setCurrentTool(AnnotationToolManager.ToolType.HIGHLIGHT));
        noteBtn.setOnClickListener(v -> annotationToolManager.setCurrentTool(AnnotationToolManager.ToolType.NOTE));
        drawBtn.setOnClickListener(v -> annotationToolManager.setCurrentTool(AnnotationToolManager.ToolType.DRAWING));
        selectBtn.setOnClickListener(v -> annotationToolManager.setCurrentTool(AnnotationToolManager.ToolType.SELECT));
    }
    
    @Override
    protected void onPause() {
        super.onPause();
        // 保存批注
        annotationToolManager.saveAnnotations(currentPdfId);
    }
    
    // ... 其他现有代码 ...
}

性能优化与最佳实践

减少绘制开销

限制批注数量：避免在单页添加过多批注，超过50个时考虑分页加载
使用缓存：缓存已绘制的批注图层，避免重复绘制
按需绘制：只绘制当前可见区域的批注内容

坐标转换精确性

PDFView的缩放和滚动会影响坐标转换精度，建议使用以下方法确保批注定位准确：

private RectF convertToPdfCoordinates(RectF screenArea, int page) {
    float zoom = pdfView.getZoom();
    SizeF pageSize = pdfView.getPageSize(page);
    float displayWidth = pdfView.getWidth();
    
    // 计算水平偏移比例
    float horizontalOffset = (displayWidth - pageSize.getWidth() * zoom) / (2 * zoom);
    
    return new RectF(
        (screenArea.left / zoom) - horizontalOffset,
        screenArea.top / zoom,
        (screenArea.right / zoom) - horizontalOffset,
        screenArea.bottom / zoom
    );
}

处理PDF页面大小变化

当PDF页面大小变化（如旋转屏幕）时，需要重新计算批注位置：

@Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    // 重新计算所有批注位置
    annotationManager.recalculatePositions(pdfView);
}