default··约 10 分钟读完·499 次观看

useTileCache 瓦片缓存工具使用文档

);
前端javascript缓存

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 等方法。你可以根据实际项目调整导入路径,或自行实现类似接口。

引入模块

typescript
      
        
          1
          
          import { useTileCache } from 'sunrise-utils';
        
      
    

配置参数

调用 useTileCache(config) 时可传入以下配置对象:

参数类型默认值描述
dbNamestring"TileCacheDB"IndexedDB 数据库名称
urlTemplatestring""瓦片 URL 模板,例如 "https://example.com/{z}/{x}/{y}.png"
maxzoomnumber18最大缩放级别(与地图源对应)
minzoomnumber0最小缩放级别
tileSizenumber512瓦片尺寸(像素)
debugbooleanfalse是否输出调试日志

返回对象方法

调用 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. 初始化缓存工具并创建自定义源

typescript
      
        
          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 地图

typescript
      
        
          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. 查看缓存统计

typescript
      
        
          1
          
          const stats = await tileCache.getCacheStats();
        
          2
          
          console.log(`缓存瓦片数量: ${stats.count}`);
        
          3
          
          console.log(`总大小: ${stats.sizeInMB}`);
        
      
    

4. 清除所有缓存

typescript
      
        
          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 浏览

这篇文章对你有帮助吗?