如何在React中使用leaflet.offline实现Leaflet地图离线瓦片下载？

适配说明 #

目前没有专门为React封装的Leaflet离线瓦片下载专属库，但原生的leaflet.offline可以直接在react-leaflet技术栈下正常集成，不需要额外的适配层。

具体集成步骤 #

1. 依赖安装 #

首先安装核心依赖，执行命令：
npm install leaflet react-leaflet leaflet.offline
如果使用TypeScript开发，额外安装类型声明：
npm install @types/leaflet -D

2. 基础配置 #

首先在组件入口引入Leaflet全局样式以及相关依赖，注意leaflet.offline必须在leaflet之后导入：

import 'leaflet/dist/leaflet.css'
import L from 'leaflet'
import 'leaflet.offline'
import { MapContainer } from 'react-leaflet'
import { createLayerComponent, createControlComponent } from '@react-leaflet/core'

3. 封装离线瓦片图层 #

使用react-leaflet提供的自定义图层创建方法，封装离线瓦片图层，优先读取本地存储的瓦片，没有命中才请求线上：

const OfflineTileLayer = createLayerComponent(
  (props, context) => {
    const layer = L.tileLayer.offline(props.url, {
      ...props,
      // 配置瓦片存储名称，可自定义
      storeName: 'leaflet_offline_tiles'
    })
    return { instance: layer, context }
  },
  (instance, props, prevProps) => {
    if (props.url !== prevProps.url) {
      instance.setUrl(props.url)
    }
  }
)

4. 封装下载控制组件 #

封装自定义控制按钮，实现当前视图范围瓦片下载功能：

const DownloadControl = createControlComponent((props) => {
  const control = L.control({ position: 'topright' })
  control.onAdd = () => {
    const btn = L.DomUtil.create('button', 'download-tiles-btn')
    btn.textContent = '下载当前区域瓦片'
    btn.onclick = async () => {
      // 获取当前地图视图层级范围
      const map = control._map
      const bounds = map.getBounds()
      const minZoom = map.getMinZoom()
      const maxZoom = map.getMaxZoom()
      // 调用下载方法
      const tiles = map.getTileUrls(bounds, minZoom, maxZoom)
      map.downloadTiles(tiles, (loaded, total) => {
        console.log(`下载进度：${loaded}/${total}`)
      })
    }
    return btn
  }
  return control
})

5. 组件中使用 #

在地图组件中直接使用封装好的组件即可：

function MapPage() {
  return (
    <MapContainer center={[39.9, 116.3]} zoom={10} style={{ height: '100vh', width: '100%' }}>
      <OfflineTileLayer
        url="https://你的瓦片源地址/{z}/{x}/{y}.png"
        attribution="瓦片版权信息"
      />
      <DownloadControl />
    </MapContainer>
  )
}

常见问题说明 #

• 跨域限制：瓦片源服务端必须配置CORS规则允许你的站点访问，否则浏览器会拦截瓦片下载请求
• 存储上限：瓦片默认存储在浏览器IndexedDB中，存储容量受设备可用空间限制，建议下载前做容量校验
• 版本兼容：确保react-leaflet v4对应leaflet v1.8及以上版本，leaflet.offline对1.x版本的leaflet都兼容

内容的提问来源于stack exchange，提问作者Tmfwang