Android平台如何创建带标记的离线PDF地图视图？

阿华AIGC实验室

2026-5-15

嘿，刚好我之前研究过类似的需求，给你梳理下Android上实现PDF离线地图（带标记、缩放交互）的可行方案，帮你搞定坐标映射和标记叠加的问题！

Android实现PDF离线地图（带标记交互）的方案

一、自定义View从零实现（对应iOS Core Graphics的思路）

如果你想自己控制整个流程，类似iOS用Core Graphics的方式，可以通过自定义View结合PdfRenderer（API 21+）来实现，核心是处理PDF渲染、手势缩放/拖动、坐标映射、标记绘制这几个关键点：

1. 基础准备：加载并渲染PDF页面

用PdfRenderer加载PDF文件，把指定页面渲染到Canvas上：

private lateinit var pdfRenderer: PdfRenderer
private lateinit var currentPage: PdfRenderer.Page

// 初始化PDFRenderer（在onCreate或onViewCreated中）
val fileDescriptor = context.contentResolver.openFileDescriptor(pdfUri, "r") ?: return
pdfRenderer = PdfRenderer(fileDescriptor)
currentPage = pdfRenderer.openPage(0) // 打开第一页

2. 处理缩放与拖动手势

用ScaleGestureDetector和GestureDetector监听缩放、拖动手势，维护缩放比例(scale)、偏移量(offsetX/offsetY)：

private var scale = 1f
private var offsetX = 0f
private var offsetY = 0f
private val scaleGestureDetector = ScaleGestureDetector(context, object : ScaleGestureDetector.SimpleOnScaleGestureListener() {
    override fun onScale(detector: ScaleGestureDetector): Boolean {
        scale *= detector.scaleFactor
        // 限制缩放范围，比如最小0.5倍，最大5倍
        scale = scale.coerceIn(0.5f, 5f)
        invalidate()
        return true
    }
})

private val gestureDetector = GestureDetector(context, object : GestureDetector.SimpleOnGestureListener() {
    override fun onScroll(e1: MotionEvent?, e2: MotionEvent?, distanceX: Float, distanceY: Float): Boolean {
        offsetX -= distanceX
        offsetY -= distanceY
        // 限制偏移，防止PDF内容完全移出屏幕
        offsetX = offsetX.coerceIn(-(currentPage.width * scale - width), 0f)
        offsetY = offsetY.coerceIn(-(currentPage.height * scale - height), 0f)
        invalidate()
        return true
    }
})

override fun onTouchEvent(event: MotionEvent?): Boolean {
    scaleGestureDetector.onTouchEvent(event)
    gestureDetector.onTouchEvent(event)
    // 处理点击事件，判断是否点击到标记
    if (event?.action == MotionEvent.ACTION_UP) {
        checkMarkerClick(event.x, event.y)
    }
    return true
}

3. 核心：坐标映射（PDF ↔ 屏幕）

这是最关键的一步，要把PDF的原始坐标（单位：点）和屏幕坐标互相转换：

// 屏幕坐标转PDF坐标
fun screenToPdf(screenX: Float, screenY: Float): Pair<Float, Float> {
    val pdfX = (screenX - offsetX) / scale
    val pdfY = (screenY - offsetY) / scale
    return Pair(pdfX, pdfY)
}

// PDF坐标转屏幕坐标
fun pdfToScreen(pdfX: Float, pdfY: Float): Pair<Float, Float> {
    val screenX = pdfX * scale + offsetX
    val screenY = pdfY * scale + offsetY
    return Pair(screenX, screenY)
}

4. 绘制PDF与标记

在onDraw方法中，先绘制PDF页面，再根据坐标转换绘制标记：

override fun onDraw(canvas: Canvas?) {
    super.onDraw(canvas)
    canvas ?: return

    // 保存画布状态，应用缩放和偏移
    canvas.save()
    canvas.scale(scale, scale)
    canvas.translate(offsetX / scale, offsetY / scale)

    // 渲染PDF页面到Canvas
    val bitmap = Bitmap.createBitmap(currentPage.width, currentPage.height, Bitmap.Config.ARGB_8888)
    currentPage.render(bitmap, null, null, PdfRenderer.Page.RENDER_MODE_FOR_DISPLAY)
    canvas.drawBitmap(bitmap, 0f, 0f, null)
    bitmap.recycle()

    canvas.restore()

    // 绘制标记（假设markers是存储PDF坐标的列表）
    markers.forEach { marker ->
        val (screenX, screenY) = pdfToScreen(marker.pdfX, marker.pdfY)
        // 绘制标记图标，比如用Bitmap或者Shape
        canvas.drawBitmap(markerIcon, screenX - markerIcon.width/2, screenY - markerIcon.height/2, null)
    }
}

5. 标记点击弹窗

在checkMarkerClick方法中，把触摸的屏幕坐标转成PDF坐标，判断是否命中标记：

private fun checkMarkerClick(screenX: Float, screenY: Float) {
    val (pdfX, pdfY) = screenToPdf(screenX, screenY)
    markers.forEach { marker ->
        // 判断点击位置是否在标记范围内（比如以标记为中心，50点的半径）
        val distance = hypot(pdfX - marker.pdfX, pdfY - marker.pdfY)
        if (distance < 50) {
            // 弹出弹窗展示标记信息，比如用AlertDialog
            AlertDialog.Builder(context)
                .setTitle(marker.title)
                .setMessage(marker.content)
                .show()
            return
        }
    }
}

二、利用成熟类库快速实现

如果不想从零写，推荐用现成的PDF库来减少工作量，以下两个库都支持叠加标记和交互：

1. AndroidPdfViewer（基于PdfiumAndroid）

这个库封装了PDF的缩放、滚动、页面切换等功能，你可以通过添加OverlayView的方式来叠加标记：

集成库后，创建自定义的MarkerOverlayView，继承View，维护标记列表，在onDraw中绘制标记
把MarkerOverlayView和PDFView放在同一个FrameLayout中，让它们重叠
监听PDFView的OnScrollListener和OnZoomListener，实时更新OverlayView的标记位置（因为PDFView会自动处理缩放和滚动，你需要获取当前的缩放比例和偏移来计算标记的屏幕坐标）