XiaoTen-FootprintMap（小十足迹地图）
地址[url=https://github.com/Jiosanity/XiaoTen-FootprintMap]
一个基于高德地图的纯前端足迹地图组件，支持标记集群、分类筛选、照片轮播等功能。
简体中文 | 在线演示
项目地址：https://github.com/Jiosanity/XiaoTen-FootprintMap
✨ 特性
- 🗺️ 纯静态实现 - 纯前端，无需后端，仅需引入 JS/CSS 文件
- 🎯 智能标记集群 - 网格算法自动合并附近标记，提升大数据量展示性能
- 🏷️ 分类筛选 - 自动提取分类标签，支持一键筛选
- 🌓 主题自适应 - 完美适配亮色/暗色主题，自动同步切换
- 📸 照片展示 - 支持多图轮播和灯箱放大查看
- 📱 移动端优化 - 响应式设计，触控友好
- 🎨 自定义标记 - 6种预设渐变色 + 自定义颜色支持
- ⚡ 性能优化 - 精简代码（475行 JS），按需加载
- 🧭 自定义控件 - 在地图右上角（或移动端右下）提供「重载视图 / 全屏 / 放大 / 缩小」四个控件，避免和地图原生控件重叠并支持暗黑主题。
- 🔌 即插即用 - 支持任何网站：WordPress、Hexo、Jekyll、Hugo 等
📸 演示
在线演示：
https://footprintmap.xiaoten.com/
提示：演示页右上角“🔑 API Key”按钮可快速填写并保存你的高德 Key，页面会自动使用此 Key 加载地图。
🚀 快速开始
1. 引入文件（自动引导，无需写初始化代码）
在 HTML 页面中引入 CSS/JS，并放置一个容器元素。组件会自动扫描类名为 .footprint-map 的元素并初始化。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>我的足迹地图</title>
<!-- 引入 CSS（本地或 CDN，二选一） -->
<link rel="stylesheet" href="css/footprintmap.css">
<!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Jiosanity/XiaoTen-FootprintMap@v1.3.0/static/css/footprintmap.css"> -->
<style>
.footprint-map { width: 100%; height: 600px; }
</style>
<script>
// 可选：在运行时写入本地存储中的 Key（也可直接在容器 data-amap-key 上写）
localStorage.setItem('amapKey', '你的高德地图APIKey');
</script>
<!-- 引入 JS（本地或 CDN，二选一） -->
<script defer src="js/footprintmap.js"></script>
<!-- <script defer src="https://cdn.jsdelivr.net/gh/Jiosanity/XiaoTen-FootprintMap@v1.3.0/static/js/footprintmap.js"></script> -->
<!-- 无需单独引入高德地图脚本，组件会按需加载（仅支持高德 AMap） -->
<!-- 无需手写 new FootprintMap(...)，组件会自动初始化 -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="light dark">
<link rel="icon" href="data:,">
<link rel="preconnect" href="https://webapi.amap.com">
<link rel="dns-prefetch" href="https://webapi.amap.com">
<link rel="dns-prefetch" href="https://a.amap.com">
<link rel="dns-prefetch" href="https://vdata.amap.com">
<link rel="dns-prefetch" href="https://restapi.amap.com">
<link rel="dns-prefetch" href="https://lbs.amap.com">
<link rel="dns-prefetch" href="https://webapi.amap.com">
<link rel="dns-prefetch" href="https://jiosanity.github.io">
<link rel="dns-prefetch" href="https://cdn.jsdelivr.net">
<link rel="dns-prefetch" href="https://fastly.jsdelivr.net">
<link rel="dns-prefetch" href="https://gcore.jsdelivr.net">
</head>
<body>
<!-- 地图容器：至少提供数据源地址 data-json；amap-key 可选（也可走 localStorage） -->
<div class="footprint-map"
data-json="data/footprints.json"
data-amap-key="可选：直接写你的Key"></div>
</body>
</html>2. 准备数据
创建 data/footprints.json 文件：
{
"locations": [
{
"name": "北京",
"coordinates": "116.4074,39.9042",
"description": "中国的首都",
"date": "2024-05-01",
"categories": ["2024", "旅行"],
"markerColor": "sunset"
}
]
}3. 获取 API Key
前往 高德开放平台 注册并创建应用，获取 Web 端 JS API Key。
4. 完成！
直接打开 HTML 文件或通过本地服务器访问即可看到地图。详细文档请查看 安装指南。
📖 文档
🎨 标记颜色预设
| 预设名称 | 效果 | 使用方式 |
|---|---|---|
| sunset | "markerColor": "sunset" | |
| ocean | "markerColor": "ocean" | |
| violet | "markerColor": "violet" | |
| forest | "markerColor": "forest" | |
| amber | "markerColor": "amber" | |
| citrus | "markerColor": "citrus" |
也可以使用自定义颜色："markerColor": "#ff6b6b" 或 "markerColor": "rgb(255,107,107)"
🔧 使用要点
- 容器：使用类名
footprint-map的元素作为地图容器，建议通过 CSS 设定高度。 - 数据：通过
data-json指定 JSON 数据地址。 - Key：通过
data-amap-key或localStorage('amapKey')提供高德 Key。 - 初始化：无需手写 JS 初始化，组件会在 DOMContentLoaded 后自动扫描并挂载。
- 主题：当页面根节点存在
.dark类时自动切换为暗色地图样式。
🛠️ 技术栈
- 高德地图 Web JS API 2.0 - 地图服务
- Vanilla JavaScript (ES6+) - 无框架依赖
- CSS3 - 响应式样式
🐛 Bug修复
修复分类筛选时的视野过度缩放问题
- 问题现象: 当启用“集群模式”时，如果筛选的分类下的所有地点在地理上非常集中，它们会被聚合为一个或极少数几个集群点。此时地图的
setFitView功能会因目标过少而判断失误，导致地图被无限放大，视野崩溃。 - 解决方案: 重构了
renderMap函数的核心逻辑。创建了一个名为fitViewToPoints的辅助函数，该函数不再依赖于地图上实际渲染出的标记点或集群点来调整视野。而是基于筛选后的原始地理坐标数据，通过在地图上添加一个临时的、不可见的覆盖物（AMap.Polyline）来精确计算出能包含所有目标点的地理边界，然后命令地图缩放至此边界，完成后再移除该临时覆盖物。这从根本上解决了因集群聚合导致视野判断错误的问题，确保了在任何数据分布下都能提供稳定、正确的缩放体验。
📝 更新日志
查看 CHANGELOG.md 了解详细的版本更新历史。
最新版本 v1.3.0 (2025-11-19)
- 🚀 项目开源：源码已托管至
https://github.com/Jiosanity/XiaoTen-FootprintMap，包含示例数据、文档与演示页面。 - 🛠️ 新增可视化编辑器（editor.html）：提供本地交互式编辑体验，支持地图拾取坐标、添加/编辑地点、导入示例/JSON、生成并下载 JSON、复制到剪贴板以及即时预览（含聚类、筛选、主题同步）。
- 📱 编辑器移动端优化：修复按钮换行缩进、日期行在窄屏保持一行、图片查看器与轮播滚动优化等交互细节。
- ⚡ 其它若干细节修复与文档补充（CHANGELOG 中有完整记录）。
v1.2.0 (2025-11-19)
- ✨ 新增 2D 地图模式，禁用旋转和倾斜
- ⚡ 代码精简：JS 从 879 行优化到 475 行（减少 45.9%）
- 🎨 完善黑暗模式适配（缩放控件和比例尺）
- 🐛 修复多项 UI 细节问题
🤝 贡献
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 提交 Pull Request
📄 开源协议
本项目采用 MIT 协议开源。
🙏 致谢
- 灵感来源：王叨叨的足迹管理插件
- 地图服务：高德开放平台
📧 联系方式
- 作者：xiaoten
- 网站：xiaoten.com
- Issue：GitHub Issues
如果这个项目对你有帮助，请给个 ⭐️ Star 支持一下！
本文著作权归作者 [ 老段同学 ] 享有，未经作者书面授权，禁止转载，封面图片来源于 [ 互联网 ] ，本文仅供个人学习、研究和欣赏使用。如有异议，请联系博主及时处理。