x_tdt_map足迹地图插件（20260928更新）

偶然间发现一个基于高德地图的wordpress插件，很实用，但是作者提醒：

建议各位寻求新的 WP 地图插件，高德 API 不能用于实际长期使用。持续使用官方会电话联系你询问用途并引导你购买付费授权，不付费的话会将你的服务停掉。

于是我借助Workbuddy改成了基于天地图的版本，并且加入了一些自己喜欢的新功能，演示地址：https://www.iclws.com/travel

这个插件能做什么

x-tdt-map 是一个轻量、合规、开箱即用的 WordPress 足迹地图插件。它不追求"满屏花哨的标记"，而是用一套清晰的分层交互，让你和访客都能一眼看懂"去过哪些省份、哪些城市、具体哪些点"：

• 全国视图：按省显示数量徽标——单地点省份红色、多地点省份橙色，带呼吸脉冲动画。

• 点省下钻：进入某省后，按地级市聚合，每个有足迹的地级市显示一个绿色市徽标（含数量）。

• 点市下钻：进入某地级市后，渲染该市的每一个足迹点，并自动将视野居中到该市范围。

• 直辖市直显：北京、上海、天津、重庆省级本身即"市"，点进去直接显示足迹点，不会出现空白。

交互全程只需"点省 → 点市 → 看点"，并随时可「返回全国」。

核心特性

• 省份聚合 + 省→市→点 三级下钻：国内最直观的足迹分层方式，避免一打开就满屏图钉看不清。

• 子景点挂父足迹：一个地点有多个景点时，不必逐条建足迹。在父足迹下维护一份「景点名 | 链接」清单即可，前台信息窗口统一列出；聚合计数只按父级算。

• 三种标记配色：默认标记（橙）、有链接标记（主题蓝）、无链接标记（醒目品红），一眼区分是否有延伸阅读。

• 自动识别省 / 市：添加足迹时自动逆地理编码并归属到省份与地级市；海外地址走 OpenStreetMap 解析，避免误落国内。

• 三种前端展示方式（任选）：

  1. 自定义地图路径——启用后生成独立全屏地图页（如 https://yoursite.com/map/）；

  2. 短代码——在任意文章/页面插入 [wp_tdt_map]；（wp改为x）

  3. Gutenberg 块——块编辑器内直接搜索「足迹地图」插入，侧栏可调高度 / 缩放 / 模式。

• 年份筛选：支持按年份查看某年的足迹（[wp_tdt_map year="2025"]）。（wp改为x）

• 服务端 + 浏览器双 Token：浏览器端 Token 负责前端渲染，服务端 Token 负责后台自动识别省/市。

• 数据独立、卸载可控：足迹存于自定义表 wp_footprints，设置存于 wp_footprints_settings，不污染 WP 核心表；卸载时可选择保留数据表。

• 开放许可：GPL-2.0-or-later，可自由使用、修改、再分发。

安装与配置

环境要求

• WordPress ≥ 6.8

• PHP ≥ 8.1

• 天地图开放平台 申请的 API Key（Token）

安装步骤

1. 将插件文件夹上传到站点的 /wp-content/plugins/ 目录；

2. 在 WordPress 后台 插件 页面找到 x-tdt-map，点击 激活；

3. 激活后，左侧菜单出现 足迹 管理入口。

获取并配置 Token

前往 天地图开放平台 登录后创建应用：

• 浏览器端 Token（必填）——用于前端地图渲染，创建应用时类型选"浏览器端"；

• 服务端 Token（可选）——用于后台自动识别省/市，类型选"服务端"。

建议两种都申请。进入 足迹 → 足迹设置 填入并保存。

使用流程

1. 添加足迹：进入 足迹 → 添加足迹，填写地点名称与访问日期，在地图上点击定位（或用地址搜索自动定位，海外地址走 OSM 解析），可选关联链接；

2. （可选）地图微调：若城市下拉定位不够精确，可在右侧天地图上点击 / 拖拽放置更准确的标记；

3. 前端展示：通过自定义路径 / 短代码 / Gutenberg 块任意一种方式嵌入地图；

4. 互动浏览：访客在地图上点省 → 点市 → 看点，或点标记查看名称、日期、描述与链接。

短代码参考

[wp_tdt_map]（wp改为x）
[wp_tdt_map year="2025"]（wp改为x）
[wp_tdt_map height="400px" zoom="3"]（wp改为x）

数据与安全

• 足迹数据存于自定义表 wp_footprints，设置存于 wp_footprints_settings，均与 WordPress 核心表隔离；

• 卸载插件默认删除两张表；如需保留，先到 足迹 → 足迹设置 勾选"卸载时保留足迹数据"；

• 前端信息窗口对标题/描述/链接做了转义与协议白名单，杜绝存储型 XSS；

• 省界等行政区划接口做了代码白名单校验，杜绝路径遍历；

• 地图底图使用天地图，符合国内地图服务相关法规。

常见问题

地图显示"天地图 API 未加载"？ 检查 Token 是否正确、且创建类型是否为"浏览器端"。

年份筛选串数据 / 不生效？ 年份维度已单独做缓存键隔离；若仍异常，尝试清除页面缓存或用隐身窗口查看。

删除插件后数据会怎样？ 默认卸载即删除数据表。如需保留，先在设置中勾选"卸载时保留足迹数据"再删除。

能否用于海外地点？ 支持。海外地址走 OpenStreetMap 解析，并做国别校验防止误落国内；但天地图底图仅覆盖国内，海外点会显示在空白底图上（已知限制，后续完善）。

下载地址：x_tdt_map