useTileCache 瓦片缓存工具使用文档
useTileCache 瓦片缓存工具使用文档
概述
useTileCache 是一个基于 IndexedDB 的地图瓦片缓存工具,专为 Mapbox GL JS 设计。它通过自定义栅格源(Custom Raster Source)将网络请求的瓦片(Tile)缓存到浏览器本地,大幅减少重复的网络请求,提升地图加载速度并支持离线场景。
功能特性
- 🗂️ IndexedDB 存储:使用浏览器内置的 IndexedDB 持久化存储瓦片数据,容量大且不会自动清除。
- 🌐 网络回退:缓存未命中时自动从网络加载,加载后自动存入缓存。
- 🧩 Mapbox 自定义源:提供符合 Mapbox GL JS 自定义源接口的对象,可直接作为地图的栅格源使用。
- 🔍 瓦片 URL 模板:支持
{z}、{x}、{y}占位符,灵活适配不同瓦片服务。 - 📊 缓存统计与清理:可获取缓存大小、格式化显示,并支持手动清除所有缓存。
- 🚦 请求中止支持:集成
AbortSignal,可配合地图的快速移动或缩放自动中止不必要的瓦片请求。
安装
依赖要求
- 项目需已集成
mapbox-gl(版本 ≥ 2.0) - 需要
useLocalStore模块(位于../../localStore),该模块是对 IndexedDB 的封装,提供getCacheByKey、setCacheToLocal、clearCache、getCacheSize等方法。你可以根据实际项目调整导入路径,或自行实现类似接口。
引入模块
1
import { useTileCache } from 'sunrise-utils';
配置参数
调用 useTileCache(config) 时可传入以下配置对象:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
dbName | string | "TileCacheDB" | IndexedDB 数据库名称 |
urlTemplate | string | "" | 瓦片 URL 模板,例如 "https://example.com/{z}/{x}/{y}.png" |
maxzoom | number | 18 | 最大缩放级别(与地图源对应) |
minzoom | number | 0 | 最小缩放级别 |
tileSize | number | 512 | 瓦片尺寸(像素) |
debug | boolean | false | 是否输出调试日志 |
返回对象方法
调用 useTileCache 后返回一个对象,包含以下方法:
getTileUrl(tileID: TileID): string
根据瓦片坐标生成完整的 URL。
参数:tileID 包含 z、x、y 属性。
返回:替换占位符后的 URL 字符串。
async loadTile(tileID: TileID, options?: { signal: AbortSignal }): Promise<ImageBitmap>
加载指定瓦片,优先从缓存获取,失败则从网络获取并缓存。
参数:
tileID:瓦片坐标。options.signal:可选的AbortSignal,用于取消正在进行的请求。
返回:解析为ImageBitmap对象的 Promise。
注意:若请求被中止,Promise 会 reject 一个AbortError,调用方可根据需要处理(例如忽略)。
unloadTile(tileID: TileID): void
卸载瓦片时的回调(当前仅打印调试日志,可按需扩展清理逻辑)。
async getCacheStats(): Promise<TileCacheStats>
获取缓存统计信息。
返回:对象包含 count(瓦片数量,当前恒为0,需扩展本地存储实现)、size(字节数)、sizeInMB(格式化后的大小字符串,如 "1.2 MB")。
async clearCache(): Promise<void>
清空整个 IndexedDB 缓存。
createRasterSource(): CustomSourceInterface<ImageBitmap>
创建一个符合 Mapbox GL JS 自定义栅格源规范的对象。该对象可直接通过 map.addSource('source-id', source) 添加到地图中。
使用示例
1. 初始化缓存工具并创建自定义源
1
import { useTileCache } from './useTileCache';
2
3
const tileCache = useTileCache({
4
urlTemplate: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
5
maxzoom: 19,
6
tileSize: 256,
7
debug: true,
8
});
9
10
const customRasterSource = tileCache.createRasterSource();
2. 添加到 Mapbox 地图
1
import mapboxgl from 'mapbox-gl';
2
3
mapboxgl.accessToken = 'YOUR_TOKEN';
4
5
const map = new mapboxgl.Map({
6
container: 'map',
7
style: 'mapbox://styles/mapbox/streets-v11',
8
center: [0, 0],
9
zoom: 2
10
});
11
12
map.on('load', () => {
13
map.addSource('osm-tiles', customRasterSource);
14
map.addLayer({
15
id: 'osm-tiles-layer',
16
type: 'raster',
17
source: 'osm-tiles',
18
minzoom: 0,
3. 查看缓存统计
1
const stats = await tileCache.getCacheStats();
2
console.log(`缓存瓦片数量: ${stats.count}`);
3
console.log(`总大小: ${stats.sizeInMB}`);
4. 清除所有缓存
1
await tileCache.clearCache();
注意事项
- 跨域问题:如果瓦片服务位于不同域,需确保服务器支持 CORS,否则
fetch可能失败。 - 缓存更新:当前策略是“一次缓存,永久使用”。若瓦片服务内容更新(例如卫星图定期更新),可能需要定期清理缓存或增加版本控制。
- 中止信号:Mapbox 在快速移动或缩放时会自动调用
loadTile并传入AbortSignal,loadTile中会监听该信号并中止fetch,避免无效请求占用带宽。你无需额外处理。 - 依赖模块
useLocalStore:本工具依赖于一个封装好的 IndexedDB 存储模块,请确保其导出以下方法:getCacheByKey(key: string): Promise<Blob | ArrayBuffer | ImageBitmap | null>setCacheToLocal(key: string, data: Blob): Promise<void>clearCache(): Promise<void>getCacheSize(): Promise<string>(返回如"1.2 MB"的字符串) 若你的项目中没有该模块,可根据 idb 等库自行实现,或直接使用本工具提供的简化版存储(可扩展)。
- 瓦片数量统计:当前
getCacheStats返回的count始终为 0,因为useLocalStore未提供计数接口。如有需要,可扩展本地存储实现以支持计数。
性能优化建议
- 合理设置
maxzoom:避免缓存超出实际需求的高缩放级别瓦片,节省存储空间。 - 预加载:可在用户进入某区域前提前调用
loadTile预缓存周边瓦片,但需注意控制并发数,避免请求过多。 - 结合
map.loadImage:如果瓦片需要作为地图的icon-image使用,可以将返回的ImageBitmap通过map.addImage添加到地图样式。
常见问题
Q:为什么地图不显示缓存的瓦片?
A:检查自定义源是否正确添加,并且图层引用了正确的源 ID。确认 debug: true 后查看控制台是否有缓存命中日志。
Q:缓存可以跨会话使用吗?
A:可以,IndexedDB 是持久化存储,关闭浏览器后重新打开,缓存依然存在。
Q:如何更新已过期的瓦片?
A:可扩展 loadTile 逻辑,例如在 URL 中添加时间戳参数绕过缓存,或定期调用 clearCache 清空所有缓存。
通过 useTileCache,你可以轻松为 Mapbox 地图添加高效、持久的瓦片缓存,显著提升用户体验。如有任何问题,欢迎反馈!
相关文章
查看同分类文章MAVLink 消息处理指南
MAVLink消息处理系统摘要 本系统实现了一套完整的MAVLink消息处理机制,用于无人机通信与控制。核心功能包括: 消息接收:通过UDP连接持续接收飞控消息,支持心跳维持机制 消息处理:分类处理多种MAVLink消息类型,包括心跳、位置、姿态和航点相关消息 航点管理:实现航点下载状态机,支持分片请求和接收航点数据 消息转发:将处理后的消息通过MQTT发布到指定主题 系统采用多线程架构,包含独立的消息接收线程和主处理循环,通过通道进行线程间通信。关键特性包括航点下载状态机、错误处理和日志记录机制,确保通信
304 浏览
M3U8 下载助手油猴脚本 - 技术实现解析
M3U8下载助手技术解析 该油猴脚本通过注入拦截脚本实现对M3U8链接的全面捕获。核心架构包括: 请求拦截层:劫持XHR、fetch和WebSocket请求 DOM监听层:通过MutationObserver监控动态元素变化 跨域通信:iframe间使用postMessage传递数据 UI展示层:提供浮动按钮等交互界面 关键技术点: 使用document-start确保早期注入 通过保存原始方法实现API劫持 在send时而非open时检测URL 全面覆盖各种属性(src/href/data-src等) 脚
362 浏览
我做了一个局域网传文件的小工具,记录一下
本文记录了作者开发局域网文件传输工具的过程。起因是工作中遇到大文件传输不便的问题,作者选择用Rust语言开发,解决了WebSocket状态管理、大文件上传限制等技术难点。最终成品通过浏览器即可使用,支持文字聊天和文件传输,内存占用低。同事们试用后反馈良好,建议增加拖拽上传等功能。作者认为Rust虽开发较繁琐但运行高效稳定,并将项目开源供社区参与改进。
291 浏览
局域网聊天工具
这是一个基于Rust和Axum框架开发的局域网实时聊天工具,支持文本聊天、图片和文件分享功能。项目采用WebSocket实现实时通信,前端使用Tailwind CSS构建界面。主要功能包括实时消息传递、文件上传下载(限制100MB)、在线用户显示和消息历史记录。部署简单,只需Rust环境,通过Cargo编译运行即可启动服务。系统架构清晰,包含后端处理、前端界面和文件存储模块,适合局域网内团队协作使用。
350 浏览