# FootprintMap
**Repository Path**: ymz316/footprint-map
## Basic Information
- **Project Name**: FootprintMap
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# FootprintMap 百度足迹地图插件
Typecho 博客的百度地图足迹展示与管理插件。
## 功能
- **前端展示**：文章/页面中通过短代码 `[footprint]` 或模板函数嵌入百度地图
- **后台管理**：地图点选 + 列表表单增删改足迹，AJAX 无刷新保存
- **标记拖动**：后台直接拖拽标记调整坐标，松开即更新表单
- **列表拖拽排序**：右侧列表支持拖拽排序，松手自动保存
- **列表点击编辑**：点击列表行直接进入编辑模式（含飞到标记位置）
- **全屏地图**：右下角全屏切换按钮，全屏时自动调整布局
- **Fancybox 6 灯箱**：点击照片弹出灯箱浏览，左右按钮滑动切换，手势友好
- **移动端适配**：气泡内触摸事件完整支持，图片/按钮正常交互，点击气泡外关闭
- **自定义图标**：`resource/` 下 PNG/SVG 图标自动列出，存储文件名不依赖域名
- **Markdown 描述**：desc 字段支持 Markdown，链接自动 `target="_blank"`
- **个性化样式**：`resource/` 下 JSON 样式自动加载，内嵌页面无网络请求，自动校验有效性
- **半透明气泡**：InfoWindow 半透明白色背景，阴影修复
- **数据独立**：足迹数据存 `usr/uploads/footprintmap/foots.json`，换主题不丢失
## 安装
1. 将 `FootprintMap` 目录上传至 `usr/plugins/`
2. 后台 → 控制台 → 插件，启用「FootprintMap」
3. 插件设置填写**百度地图 AK**
4. 确保 `usr/uploads/footprintmap/` 可写
## 使用
### 短代码
在文章或页面中插入：
```text
[footprint]
```
### 模板函数
主题模板中调用：
```php
```
地图填满剩余高度：外层容器 `display:flex; flex-direction:column`，地图区域 `flex:1`。
### 后台管理
后台 → **管理 → 足迹地图**：
| 操作 | 方式 |
| ---- | ---- |
| 新增 | 点击地图空白处自动填坐标，填写表单保存 |
| 编辑 | 点击标记 / 列表行 / 编辑按钮 |
| 删除 | 列表右侧删除按钮 |
| 拖动坐标 | 直接拖拽地图上的标记到新位置 |
| 拖拽排序 | 按住列表项拖到目标位置，松手自动保存 |
| 搜索 | 列表输入框按名称过滤；地图左上角搜索地点定位 |
### 自定义图标
1. 将 PNG/SVG 放入 `usr/plugins/FootprintMap/resource/`
2. 后台图标下拉框自动列出
3. 选择「自定义 URL…」可用任意图标地址
图标存储为文件名，`resolveIcon()` 渲染时解析为完整 URL，兼容：
- 文件名 (`foot.png`) → 拼接插件 resource URL
- 绝对路径 (`/usr/themes/...`) → 拼接 siteUrl
- 完整 URL (`https://...`) → 直接使用
### 个性化地图样式
1. 百度地图开放平台 → 个性化地图 → 导出 JSON
2. 保存为 `.json` 放入 `resource/`
3. 插件设置 → 地图样式下拉选择
JSON 内嵌页面调用 `setMapStyleV2({ styleJson })`，零网络请求。加载时校验有效性，无效文件不会导致前端报错。
### Markdown 描述
desc 字段支持 Markdown：
| 语法 | 效果 |
| ---- | ---- |
| `**粗体**` | **粗体** |
| `*斜体*` | *斜体* |
| `[文字](url)` | 新标签页打开链接 |
| 空行 | 段落分隔 |
## 数据格式
`usr/uploads/footprintmap/foots.json`：
```json
{
"latLng": [34.56, 113.63],
"name": "郑州",
"desc": "**出差**1天",
"icon": "foot.png",
"photos": ["https://example.com/photo1.jpg"]
}
```
| 字段 | 必填 | 说明 |
| ---- | ---- | ---- |
| `latLng` | 是 | `[纬度, 经度]` |
| `name` | 是 | 地点名称 |
| `desc` | 否 | 文字描述，支持 Markdown |
| `icon` | 否 | 图标文件名或完整 URL |
| `photos` | 否 | 照片 URL 数组 |
## 插件设置
| 设置项 | 默认值 | 说明 |
| ----- | ----- | ----- |
| 百度地图 AK | — | **必填** |
| 地图中心纬度 | 34.56 | 默认视图中心 |
| 地图中心经度 | 113.63 | 默认视图中心 |
| 地图缩放级别 | 6 | 1–18 |
| 地图样式 | 默认样式 | resource/ 下的 JSON 样式文件 |
## 文件结构
```text
usr/plugins/FootprintMap/
├── Plugin.php # 主插件类（激活/配置/短代码/渲染/图标解析）
├── Action.php # CRUD + 排序（新增/更新/删除/排序）
├── manage-footprints.php # 后台管理页面
├── README.md
├── resource/ # 图标 + 样式 JSON
│ ├── foot.png
│ ├── home.png / home.svg
│ └── *.json # 个性化样式（自动扫描）
├── css/
│ ├── admin.css # 后台管理样式
│ └── frontend.css # 前端地图/气泡/画廊样式
└── js/
└── admin.js # 后台交互（标记拖动/列表拖拽/AJAX）
```
数据文件：`usr/uploads/footprintmap/foots.json`（激活时自动迁移旧数据）
## 气泡交互
| 场景 | 行为 |
| ---- | ---- |
| 点击标记 | 打开气泡 |
| 气泡内图片 | 触发 Fancybox 6 灯箱（直接 `onclick` 调用 `Fancybox.show()`） |
| 气泡内滚动按钮 | 照片 > 2 张时左右滑动 |
| 点击地图空白处 | 关闭气泡 |
| 移动端触摸气泡内 | `touchstart`/`touchend` 冒泡阶段拦截，防误关闭 |
| 移动端触摸气泡外 | 正常关闭气泡 |
## 依赖
| 依赖 | 说明 |
| ---- | ---- |
| PHP 7.4+ | — |
| Typecho 1.3+ | — |
| 百度地图 WebGL API v1.0 | 需要 AK |
| Fancybox 6 | 灯箱，主题需加载 `fancybox.umd.min.js` + `fancybox.min.css` |
### Fancybox 6 引入方式
在主题 `header.php` 的 `` 中加入：
```html
```
并在 `footer.php` 末尾绑定（插件会自动将气泡内图片纳入）：
```html
```
## 许可
MIT