跳到主要内容

更新日志

记录 Mapjar 的所有重要更新和变更。

[0.4.3] - 2024-12-11​

📚 文档更新​

在线演示系统 🎯​

  • 完整的在线演示：为所有 9 个示例添加了完整的在线演示功能
    • 自托管 HTML 文件，加载速度快
    • 嵌入式 iframe 演示，直接在文档中交互
    • "在新窗口打开"链接，支持全屏体验
  • 真实数据演示：
    • 风场图层使用 NOAA GFS 全球风场数据（2016-11-20）
    • 热力图层使用相同数据计算全球风速分布
    • 实现了 EPSG:4326 到 EPSG:3857 的重投影
  • 示例文件：
    • static/examples/basic.html - 基础地图示例
    • static/examples/tile-layer.html - 瓦片图层示例（带底图切换）
    • static/examples/vector-layer.html - 矢量图层示例
    • static/examples/geojson-layer.html - GeoJSON 图层示例
    • static/examples/image-layer.html - 图像图层示例（带透明度控制）
    • static/examples/wind-layer.html - 风场图层示例（真实 GFS 数据）
    • static/examples/heatmap-layer.html - 热力图层示例（真实风速数据）
    • static/examples/overlay-layer.html - 覆盖层示例
    • static/examples/combined.html - 综合示例（带图层控制）

API 文档完善 📖​

  • 更新现有文档：
    • TileLayer API 文档新增 retainOldTiles 相关方法
    • VectorLayer API 文档新增完整的空间查询方法
    • OverlayLayer API 文档更新为最新的简化 API
    • MapEngine API 文档保持最新状态
  • 新增工具类文档：
    • WebGLUtils - WebGL 工具函数完整文档
    • TextRenderer - 文字渲染工具完整文档
    • Loader - 资源加载工具完整文档
    • ResourceManager - 资源管理工具完整文档
    • 更新 API 概览，包含所有最新工具类
  • 文档同步：确保所有 API 文档与最新的 index.d.ts 类型定义保持一致

[0.4.2] - 2024-12-04​

🐛 Bug 修复​

TileLayer retainOldTiles 设置修复​

  • 问题：多个 TileLayer 的 retainOldTiles 都是 true，没有按预期只启用第一个
  • 修复：
    1. 将设置逻辑移到 addLayer 和 removeLayer 方法中
    2. 改用检查特有方法来判断是否是 TileLayer
    3. 避免依赖类名，确保打包后也能正常工作
  • 效果：第一个 TileLayer 的 retainOldTiles 为 true，其他为 false

⚡ 性能优化​

瓦片加载时拖动流畅度优化 🎯​

  • 优化：
    • 批量渲染回调：使用 requestAnimationFrame 合并多个瓦片的渲染请求
    • 可见瓦片缓存：相机状态不变时直接返回缓存
    • 延迟清理：瓦片清理从每帧改为每秒最多一次
  • 效果：瓦片加载时拖动流畅，减少 50%+ 计算开销

按需渲染性能优化 🚀​

  • 优化：
    • 添加状态缓存：isLoading() 每 100ms 才检查一次
    • 空闲帧优化：静止 1 秒后，检查频率降低到原来的 1/10
  • 效果：静止时 CPU 占用从 50% 降至 < 1%

[0.3.7] - 2024-12-02​

重大改进 ✨​

TileLayer 瓦片保留优化 🎯​

解决白屏问题：缩放时不再出现白屏，保留旧瓦片直到新瓦片加载完成

分层渲染：

  • 先渲染旧瓦片（透明度 0.7，作为背景）
  • 再渲染新瓦片（带淡入动画）

智能清理：当所有新瓦片都加载完成后，自动清理旧瓦片

用户体验提升：

  • ✅ 缩放时无白屏
  • ✅ 旧瓦片作为背景
  • ✅ 新瓦片平滑淡入
  • ✅ 交互更流畅

[0.3.1] - 2024-12-02​

重大改进 ✨​

OverlayLayer API 简化 🎯​

单一覆盖层设计：一个 layer 只包含一个 overlay，简化使用

新增 API：

  • setOverlay(overlay) - 设置覆盖层
  • updateOverlay(updates) - 更新覆盖层参数
  • clearOverlay() - 清空覆盖层
  • getOverlay() - 获取覆盖层

使用示例：

// 设置覆盖层
overlayLayer.setOverlay({
  element: myElement,
  position: { lon: 116.4, lat: 39.9 }
});

// 更新位置
overlayLayer.updateOverlay({
  position: { lon: 116.5, lat: 40.0 }
});

// 清空
overlayLayer.clearOverlay();
向后不兼容

需要更新现有代码以使用新 API

[0.3.0] - 2024-11-20​

新增功能 ✨​

OverlayLayer 覆盖层图层 🎯​

在地图上叠加任意 HTML 元素，支持完整的 HTML/CSS 样式和 DOM 事件。

核心特性：

  • 基于经纬度定位
  • 支持像素偏移和锚点配置
  • 统一的 DPI 管理
  • 自动跟随地图平移和缩放

应用场景：

  • 地图标注（Marker）
  • 信息弹窗（Popup）
  • 自定义控件
  • 富文本内容展示

[0.2.9] - 2024-11-20​

改进 ✨​

MapEngine 自动初始化和启动​

  • 自动初始化：构造时自动调用 init()
  • 自动启动：自动开始渲染循环
  • 简化 API：移除 autoInit 和 autoStart 选项
  • 更好的开发体验：创建后即可直接使用

事件坐标优化​

双坐标系统：

  • screenX/screenY：真实屏幕像素坐标
  • canvasX/canvasY：Canvas 内部坐标（考虑 devicePixelRatio）

[0.2.4] - 2024-11-19​

修复 🐛​

WindLayer 闪烁问题完全修复​

  • 随机初始年龄，避免所有粒子同时消亡
  • 随机生命周期，增加视觉变化
  • 移除定期清理逻辑，避免闪烁
  • 完全消除闪烁，动画更加平滑自然

[0.2.2] - 2024-11-19​

新增功能 ✨​

VectorLayer Point 描边支持​

Point 现在支持 strokeColor 和 strokeWidth 属性，使用片段着色器实现平滑的圆形描边效果。

const vectorLayer = new VectorLayer('vector', {
  fillColor: [1.0, 0.0, 0.0, 1.0],      // 红色填充
  strokeColor: [0.0, 0.0, 0.0, 1.0],    // 黑色描边
  strokeWidth: 2.0,                      // 2像素描边
  pointSize: 10.0
});

统一 DPI 管理 🎯​

在 MapOptions 中添加 devicePixelRatio 参数，所有图层使用统一的 DPI 值。

// 使用默认 DPI
const engine = new MapEngine('#map', {
  center: [116.4074, 39.9042],
  zoom: 10
});

// 自定义 DPI
const engine = new MapEngine('#map', {
  center: [116.4074, 39.9042],
  zoom: 10,
  devicePixelRatio: 2.0
});

[0.2.0] - 2024-11-19​

重大更新 🎉​

高 DPI 支持 📱​

  • 自动 DPI 缩放，使用 Math.sqrt(dpr) 避免过度放大
  • 所有图层自动适配
  • 在 Retina 屏幕和移动设备上显示更清晰

项目架构优化 🏗️​

  • 完整的 TypeScript 类型定义
  • 统一的导出接口
  • 模块化设计
  • 文档完善

[0.1.2] - 2024-11-18​

新增功能 ✨​

HeatmapLayer 热力图层 🌡️​

专门用于渲染温度、降水、气压等连续数值场。

核心特性：

  • 高效图片纹理，直接上传到 GPU
  • 灵活的颜色映射（字符串数组或 ColorStop 数组）
  • 支持透明度通道
  • 跨世界渲染支持

应用场景：

  • 温度场可视化
  • 降水量分布图
  • 气压场显示
  • 污染物浓度图

WindLayer 风场动画图层 💨​

使用 GPU 加速的粒子系统实现流畅的风场动画。

核心特性：

  • 粒子系统渲染
  • 颜色渐变（根据风速）
  • 拖尾效果
  • 缩放自适应
  • 交互优化

应用场景：

  • 气象数据可视化
  • 风场模拟演示
  • 流场可视化

EventEmitter 事件系统 🎯​

统一的事件管理系统，类型安全。

新 API：

  • on(eventName, listener) - 添加事件监听器
  • once(eventName, listener) - 添加一次性监听器
  • off(eventName, listener) - 移除事件监听器
  • removeAllListeners(eventName?) - 移除所有监听器

[未发布] - 2024-11-16​

🚨 严重内存泄漏修复（紧急）​

TileLayer LRU 缓存​

问题：瓦片缓存无限增长，浏览 30 分钟 → 1.8 GB 内存

修复：

  • 实现 LRU 缓存策略
  • 限制最大瓦片数量为 500 个
  • 缓存满时自动删除最旧的 20% 瓦片

效果：内存从 2 GB → 250 MB（降低 87%）

TextRenderer Float32Array 复用​

问题：每帧创建大量 Float32Array 对象，导致垃圾回收频繁

修复：

  • 缓存 Float32Array 对象
  • 每帧只修改值，不创建新对象
  • 对象创建从 180,000/秒降至 0/秒

效果：性能提升 10-100x，FPS 从 < 10 → 60

架构改进 🏗️​

CanvasLayer 和 TextRenderer 分离​

将 Canvas 2D 和 WebGL 代码分离，创建独立的 TextRenderer 工具类。

优点：

  • 职责分离
  • 更清晰的继承关系
  • 更好的复用性
  • 更容易测试和维护

WebGL 工具函数抽离​

将 WebGL 资源创建逻辑抽离到 WebGLUtils。

新增工具函数：

  • createShader - 创建着色器
  • createProgram - 创建着色器程序
  • createTexture - 创建纹理
  • createBuffer - 创建缓冲区
  • createVAO - 创建顶点数组对象
  • setupAttribute - 设置顶点属性

RasterLayer 基类抽象​

从 TileLayer 中抽象出通用的栅格渲染逻辑，为所有栅格图层提供一致的渲染管线。

核心功能 🎯​

渲染系统​

  • WebGL2 高性能渲染
  • 相机系统（平移、缩放、旋转、flyTo、fitBounds）
  • 多图层管理
  • 响应式 canvas 尺寸

投影系统​

  • EPSG:3857 (Web Mercator) 投影
  • 坐标转换
  • 瓦片坐标计算

图层系统​

  • 瓦片图层
  • 矢量图层
  • GeoJSON 图层
  • 图像图层
  • 风场图层
  • 热力图层
  • 覆盖层图层

交互功能​

  • 鼠标拖拽平移
  • 滚轮缩放
  • 双击放大/缩小
  • 触摸拖拽
  • 触摸双击

性能提升 🚀​

指标优化前优化后提升
瓦片加载时间2.5s1.8s28% ↓
主线程阻塞150ms20ms87% ↓
帧率下降15 fps3 fps80% ↓
交互响应30ms< 16ms47% ↓
纹理上传次数每帧仅一次99% ↓
渲染时间8ms3ms62% ↓

浏览器兼容性 🌐​

  • Chrome 56+
  • Firefox 51+
  • Safari 15+
  • Edge 79+

覆盖 97%+ 的现代浏览器。

版本说明​

语义化版本​

本项目遵循 语义化版本 2.0.0

  • 主版本号：不兼容的 API 修改
  • 次版本号：向下兼容的功能性新增
  • 修订号：向下兼容的问题修正

贡献​

感谢所有为 Mapjar 做出贡献的开发者！

如有问题或建议，请访问 GitHub 提交 Issue 或 Pull Request。