map

走哪啦 (ZounaLa) 开放地图插件中心

English

简体中文

这里是 走哪啦 (Zouna.la) 的开放地图插件生态库。 本项目通过 GitHub Pages 静态托管于 https://map.zouna.la/，向所有 ZounaLa 用户开放精选与社区共建的主题地图数据。

---

目录索引

• registry.json：全量插件索引清单，记录所有已收录的地图插件元数据。
• plugins/：各主题地图插件的具体点位 JSON 数据。
  • cn-three-mountains-five-peaks.json：中国三山五岳名山录（8 个名胜点位）
  • cn-provincial-capitals.json：中国省会与首府城市（34 个省级行政中心，包括台湾台北）

---

插件数据规范 (Schema)

每个插件对应 plugins/<plugin-id>.json，格式示例如下：

{
  "id": "cn-provincial-capitals",
  "version": "1.0.0",
  "title": "中国省会与首府城市",
  "description": "收录中国 34 个省级行政区的省会城市、自治区首府、直辖市与特别行政区地标（包括台湾台北）。",
  "contributor": "ZounaLa 探索社",
  "contributorLink": "https://github.com/zouna-la/map",
  "coordType": "wgs84",
  "category": "人文地理",
  "themeColor": "#3498DB",
  "points": [
    {
      "id": "hangzhou",
      "name": "杭州",
      "lat": 30.2741,
      "lon": 120.1551,
      "category": "华东省会",
      "badgeColor": "#1ABC9C",
      "description": "浙江省省会，“人间天堂”，全球领先的数字经济与互联网创新之城。",
      "boundaryType": "polygon",
      "boundary": [
        [120.1234, 30.1234],
        [120.1567, 30.1456],
        [120.1890, 30.1678],
        [120.1234, 30.1234]
      ]
    },
    {
      "id": "beijing",
      "name": "北京",
      "lat": 39.9042,
      "lon": 116.4074,
      "category": "直辖市",
      "badgeColor": "#E74C3C",
      "description": "中华人民共和国首都，全国政治、文化、国际交往和科技创新中心。"
    }
  ]
}

字段说明

• id: 插件全局唯一英文标识（短横线命名，如 cn-provincial-capitals）
• version: 语义化版本号，如 1.0.0
• coordType: 经纬度坐标系，支持 "wgs84"（GPS、谷歌地图、OSM 采集）或 "gcj02"（火星坐标系，高德、腾讯地图采集）。客户端会自动适配纠偏。
• themeColor: 插件主题色，在进度条及无独立点位颜色时作为兜底色。
• showDirectNames: 是否在地图上该点下方直接常驻显示地标名称（布尔值，默认 false。适合点位数量较少的主题地图，如三山五岳、名门帮会等）。
• points: 点位数组。每个点支持以下字段：
  • id: 点位唯一英文/拼音标识（必填）
  • name: 点位或区域名称（必填）
  • lat, lon: 中心点经纬度（必填，用于放置地标气泡、计算地图外接大盘视野）
  • category: 分类标签（可选）
  • badgeColor: 独立气泡/区域填充微标色（可选，如 #1ABC9C）
  • description: 介绍说明（可选）
  • boundaryType: 区域几何类型（可选，支持 "polygon" 闭合多边形）
  • boundary: 多边形顶点经纬度集合（可选，格式为 [[lon1, lat1], [lon2, lat2], ...]，遵循国际 GeoJSON 规范经度在前、纬度在后）

打卡判定算法机制

• 多边形区域模式：若点位配置了 boundaryType: "polygon" 且包含有效多边形坐标（$\ge 3$ 个顶点），客户端将采用射线交叉法（Ray-Casting Point-in-Polygon Algorithm）进行判断。用户的任意历史足迹落在该闭合多边形区域内，即刻判定为已探索打卡！地图上也会同时绘制半透明区域覆盖轮廓。
• 中心点物理距离模式：若未配置多边形，或足迹不在多边形内，客户端自动回退使用中心点球面物理距离判定（$\le 1000$ 米视为探索打卡）。

---

辅助开发工具：获取与精简多边形边界 (Helpful Tooling)

开发涉及景区、公园、城市等大区域多边形（boundary）插件时，推荐使用以下两个免费开源的工具快速制备高水准数据：

1. 获取区域边界：Overpass Turbo (OpenStreetMap)

• 在线工具：Overpass Turbo (overpass-turbo.eu)
• 使用方法：在左侧代码编辑器中输入查询语句，以检索“黄山风景区”为例：

  [out:json][timeout:60];
  (
    relation["name"~"黄山风景区"];
    way["name"~"黄山风景区"];
  );
  out geom;
  

• 导出数据：点击界面左上角 「Run（运行）」，右侧地图高亮后点击顶部 「Export（导出）」 $\rightarrow$「GeoJSON」 即可下载多边形数据文件。
• (小技巧：也可直接使用 OSM 官方接口一行获取：https://nominatim.openstreetmap.org/search?q=地名&format=geojson&polygon_geojson=1)。

2. 抽稀与精简点位：Mapshaper

• 在线工具：Mapshaper (mapshaper.org)
• 为什么需要抽稀：OSM 导出的原始边界往往包含数千个高密点位（几十至上百 KB），直接放入插件会导致 JSON 文件冗余庞大并增加手机解析开销。
• 操作步骤：
  1. 将下载的 GeoJSON 文件直接拖拽入 Mapshaper 网页；
  2. 点击右上角 「Simplify」（使用默认 Douglas-Peucker 算法）；
  3. 将滑块调节至 5% ~ 10%（点数将从数千点智能精简至 100 ~ 250 个核心特征点，在手机地图上呈现毫厘不差，体积缩减 90% 以上）；
  4. 点击右上角 「Export」 $\rightarrow$「GeoJSON」 导出，将坐标数组复制到插件的 boundary: [[lon, lat], ...] 即可。

---

社区提交规范与内容红线 (Community Guidelines)

为保障广大走哪啦（ZounaLa）用户的探索体验与数据健康，所有提交或修改的地图插件必须严格遵守以下规范。违规内容将直接被拒绝合并（Close PR）：

1. 严禁发布商业广告与导流推广：
   • 严禁在点位名称、描述说明、外部链接或贡献者署名中夹带任何商业广告、推广软文、微信/公众号引流、优惠促销、虚假宣传或跳转外链；
   • 地图标注点应具备广泛的公共探索价值、人文历史底蕴、自然景观或纯粹的地理文化特色。
2. 严禁宣传暴力、违法违规与违背公序良俗的内容：
   • 严禁宣扬暴力恐吓、血腥残忍、恐怖主义、极端主义、霸凌、自残或唆使违法犯罪行为；
   • 严禁包含淫秽色情、低俗庸俗、赌博、毒品、封建迷信以及任何侵犯他人隐私或违背公序良俗的内容。
3. 地理地标真实合规与保密红线：
   • 严禁收录涉及国防军事禁区、国家涉密工程、科研未公开设施等敏感地理信息；
   • 地理标注名称、行政归属与边界描述必须准确严肃，严格遵守国家测绘地理信息法律法规；
   • 经纬度坐标必须经过真实地理验证，严禁伪造坐标或故意偏移恶搞。
4. 版本迭代与维护：
   • 插件修正或扩充点位时，请按规范递增 version 版本号（如 1.0.0 → 1.0.1），以便客户端自动感知并静默同步最新数据。

---

如何贡献新的地图插件？

1. Fork 本仓库；
2. 在 plugins/ 目录下添加你的插件数据文件，如 plugins/my-cool-map.json；
3. 在 registry.json 的 plugins 列表中追加一条你的插件索引信息；
4. 提交 Pull Request 到 main 分支，并在 PR 描述中简述地图主题；
5. 审核通过合并后，GitHub Pages 会自动更新发布，ZounaLa App 端用户即可在“设置 -> 足迹 -> 地图插件”中发现并添加你的主题地图！