thingsboard/summary/28-地图组件配置检查指南.md

# 地图组件配置检查指南

## 检查结果

从数据库和日志检查发现，DEMO 仪表盘中有一个地图组件配置，存在以下**配置错误**：

### 1. 位置数据类型配置错误 ⚠️ **关键问题**

**问题描述：**
- 地图配置中，X轴（纬度）和Y轴（经度）都设置为 `"type": "attribute"`（属性类型）
- X轴键名：`drone.latitude`
- Y轴键名：`drone.longitude`

**实际数据情况（从日志确认）：**
- 设备发送的位置数据是**遥测数据**（timeseries），不是属性
- 日志中可以看到：`"drone.longitude":112.96570521660297,"drone.latitude":25.70685363466869`
- 这些数据在遥测数据中，不在属性中

**问题原因：**
- 地图配置查找的是**属性**（attribute），但设备数据在**遥测**（timeseries）中
- 导致地图无法获取位置信息，设备无法显示在地图上

**地图组件支持的数据类型：**
- ✅ **timeseries**（遥测数据）- 支持
- ✅ **attribute**（属性）- 支持
- ✅ **function**（函数）- 支持

**结论：** 地图**不是只能用 attribute**，可以修改为 timeseries！

### 2. 默认中心位置配置

**当前配置：**
- `"defaultCenterPosition": "0,0"` - 这是赤道和本初子午线的交点（大西洋中部）
- `"useDefaultCenterPosition": false` - 已禁用，会尝试根据数据自动调整

**建议：**
- 如果设备位置数据存在，地图应该会自动调整到设备位置
- 如果看不到设备，可能是位置数据不存在或数据类型不匹配

### 3. 数据源配置

**当前配置：**
- `"dsType": "device"` - 直接关联到单个设备
- `"dsDeviceId": "fc1be8f0-b95d-11f0-8c0a-afd4d00ac98a"` - 设备ID：7CTDM7H00B5EM1

## 修复建议

### 方案1：检查数据实际类型

**在 ThingsBoard Web UI 中：**

1. 进入设备详情页：`7CTDM7H00B5EM1`
2. 查看 **Latest Telemetry** 标签页
3. 检查是否有 `drone.latitude` 和 `drone.longitude` 数据
4. 查看 **Attributes** 标签页
5. 检查是否有 `drone.latitude` 和 `drone.longitude` 属性

**根据实际情况：**
- 如果数据在 **Telemetry** 中 → 将地图配置中的 `type` 改为 `"timeseries"`
- 如果数据在 **Attributes** 中 → 保持 `type` 为 `"attribute"`

### 方案2：在 Web UI 中修正地图配置（推荐）

**确认：位置数据是遥测数据，需要在 Web UI 中修改配置**

**重要说明：**
1. 地图组件有 **Basic Mode** 和 **Advanced Mode** 两种配置模式
2. 在 **Basic Mode** 下可能无法直接配置数据键类型
3. 需要先切换到 **Advanced Mode**，然后才能配置标记点的数据键

**操作步骤：**

#### 步骤1：切换到 Advanced Mode

1. **打开地图组件配置：**
   - 在 DEMO 仪表盘中，点击地图组件
   - 点击编辑按钮（或右键 → 编辑）

2. **切换到 Advanced Mode：**
   - 在配置面板**顶部**找到切换按钮
   - 应该显示 **"Basic Mode"** 和 **"Advanced Mode"** 两个选项
   - 点击 **"Advanced Mode"** 切换到高级模式

#### 步骤2：配置 Markers 数据键

3. **进入 Markers 配置：**
   - 在 Advanced Mode 的配置面板中，找到 **"Overlays"**（覆盖层）部分
   - 应该可以看到 **Markers**、**Polygons**、**Circles** 等选项
   - 点击 **"Markers"** 标签

4. **编辑标记点配置：**
   - 找到标记点列表（应该有一个标记点）
   - 点击标记点右侧的**编辑按钮**（或点击标记点本身）
   - 这会打开标记点配置对话框

5. **修改 Latitude（纬度）配置：**
   - 在标记点配置对话框中，找到 **Latitude** 字段（显示 `drone.latitude`）
   - 点击字段右侧的 **"×"** 按钮，删除当前数据键
   - 在输入框中输入：`drone.latitude`
   - 系统会自动显示下拉列表，选择带有 **timeline 图标**（📈）的选项（表示 timeseries）
   - **不要选择带 "A" 图标**（表示 attribute）的选项

6. **修改 Longitude（经度）配置：**
   - 找到 **Longitude** 字段（显示 `drone.longitude`）
   - 点击字段右侧的 **"×"** 按钮，删除当前数据键
   - 在输入框中输入：`drone.longitude`
   - 系统会自动显示下拉列表，选择带有 **timeline 图标**（📈）的选项（表示 timeseries）
   - **不要选择带 "A" 图标**（表示 attribute）的选项

7. **保存配置：**
   - 点击标记点配置对话框底部的 **"应用"** 或 **"保存"** 按钮
   - 点击地图组件配置面板底部的 **"应用"** 按钮
   - 刷新仪表盘查看效果

**如果找不到切换按钮：**
- 检查配置面板顶部是否有 "Basic Mode" / "Advanced Mode" 切换开关
- 如果看不到切换按钮，可能是当前已经在 Advanced Mode 了
- 直接进入步骤2，在配置面板中查找 Markers 配置部分

**图标识别：**
- 📈 **timeline 图标** = Timeseries（遥测数据）- ✅ 选择这个
- 🔵 **"A" 图标** = Attribute（属性）- ❌ 不要选这个

**配置位置图示：**
```
地图组件配置
├── Markers
│   └── [标记点配置] → 点击编辑
│       ├── Latitude 字段
│       │   ├── 删除当前值（点击 ×）
│       │   ├── 输入: drone.latitude
│       │   └── 选择 📈 图标（Timeseries）← 重要！
│       └── Longitude 字段
│           ├── 删除当前值（点击 ×）
│           ├── 输入: drone.longitude
│           └── 选择 📈 图标（Timeseries）← 重要！
```

### 方案3：设置合适的默认中心位置

**如果设备位置在中国：**

1. 在地图配置中，设置：
   - `"useDefaultCenterPosition": true`
   - `"defaultCenterPosition": "35,110"` （中国中心位置，可根据实际情况调整）
   - `"defaultZoomLevel": 6` （合适的缩放级别）

## 配置检查清单

### ✅ 已检查项

- [x] 地图类型：`geoMap`（地理地图）
- [x] 地图提供商：`openstreet`（OpenStreetMap）
- [x] 数据源类型：`device`（设备）
- [x] 设备ID已配置：`fc1be8f0-b95d-11f0-8c0a-afd4d00ac98a`
- [x] 标记点配置存在
- [x] 标签显示：`${entityName}` ✓
- [x] 工具提示已配置 ✓

### ✅ 已确认项

- [x] **位置数据是遥测数据**：从日志确认，数据在 timeseries 中
- [x] **位置数据键名**：`drone.latitude` 和 `drone.longitude` ✓
- [x] **位置数据存在**：设备正在发送位置数据 ✓
- [x] **配置错误**：地图配置为 `attribute`，但数据是 `timeseries` ⚠️

### ⚠️ 需要修复项

- [ ] **修改数据类型**：
  1. 删除 Latitude 字段的当前数据键（点击 ×）
  2. 重新输入 `drone.latitude`，选择带 📈 图标的选项（Timeseries）
  3. 删除 Longitude 字段的当前数据键（点击 ×）
  4. 重新输入 `drone.longitude`，选择带 📈 图标的选项（Timeseries）
  5. 保存配置

## 常见问题

### Q1: 地图显示空白

**可能原因：**
1. 位置数据类型不匹配（配置为 attribute，但数据是 timeseries）
2. 位置数据键名不正确
3. 设备没有发送位置数据

**解决方法：**
1. 检查设备实际发送的数据（在设备详情页查看 Latest Telemetry）
2. 确认键名和类型
3. 在地图配置中删除并重新选择数据键，确保选择 timeseries 类型（📈 图标）

### Q1.1: 找不到配置的地方 / 找不到类型选择下拉框

**问题：** 在地图配置中找不到配置 Latitude/Longitude 的地方，或者找不到类型选择下拉框

**可能原因：**
1. 当前在 **Basic Mode**，Basic Mode 可能不显示详细的数据键配置
2. 数据类型是在选择数据键时自动识别的，不是单独的下拉框配置

**解决方法：**

**方法1：切换到 Advanced Mode（推荐）**
1. 在配置面板顶部找到 **"Basic Mode" / "Advanced Mode"** 切换按钮
2. 切换到 **"Advanced Mode"**
3. 在 Advanced Mode 中，找到 **"Overlays"** 部分
4. 点击 **"Markers"** 标签
5. 编辑标记点，修改 Latitude 和 Longitude 数据键

**方法2：如果仍找不到配置**
1. 确认是否在编辑模式下（点击了地图组件的编辑按钮）
2. 检查配置面板是否完全展开
3. 尝试滚动配置面板，查看是否有更多配置选项
4. 如果确实找不到，可能需要检查 ThingsBoard 版本是否支持此功能

**关于类型选择：**
- 数据类型**不是单独的下拉框**，而是在输入数据键名时自动识别的
- 删除当前数据键，重新输入键名
- 在下拉列表中选择正确的类型：
  - 📈 timeline 图标 = Timeseries（遥测数据）- ✅ 选择这个
  - 🔵 "A" 图标 = Attribute（属性）- ❌ 不要选这个
- 系统会根据设备实际数据自动识别，如果设备有该键的遥测数据，会显示 timeseries 选项

### Q2: 地图显示但设备位置不对

**可能原因：**
1. 经纬度数据顺序错误（纬度/经度搞反）
2. 数据单位问题（度 vs 弧度）
3. 数据格式问题

**解决方法：**
1. 检查实际数据的经纬度值
2. 确认数据格式正确
3. 可能需要调整坐标转换

### Q3: 地图显示默认位置（0,0）

**可能原因：**
1. 设备没有位置数据
2. 位置数据类型配置错误
3. 位置数据键名不匹配

**解决方法：**
1. 检查设备是否有位置数据
2. 确认配置中的键名和类型
3. 设置合适的默认中心位置

## 验证步骤

1. **检查设备数据：**
   - 进入设备详情页
   - 查看 Latest Telemetry 和 Attributes
   - 确认位置数据的键名和类型

2. **检查地图配置：**
   - 打开地图组件编辑
   - 检查 Markers 配置
   - 确认 X轴和Y轴的键名和类型

3. **测试地图：**
   - 刷新仪表盘
   - 查看地图是否显示设备位置
   - 如果仍不显示，检查浏览器控制台错误信息

## 当前配置摘要

```json
{
  "mapType": "geoMap",
  "markers": [{
    "dsType": "device",
    "dsDeviceId": "fc1be8f0-b95d-11f0-8c0a-afd4d00ac98a",
    "xKey": {
      "name": "drone.latitude",
      "type": "attribute"  // ⚠️ 需要确认实际数据类型
    },
    "yKey": {
      "name": "drone.longitude",
      "type": "attribute"  // ⚠️ 需要确认实际数据类型
    }
  }],
  "useDefaultCenterPosition": false,
  "defaultCenterPosition": "0,0",
  "fitMapBounds": true  // ✓ 会自动调整到设备位置
}
```

## 下一步操作

1. **在 Web UI 中检查设备数据**
2. **根据实际数据类型修正地图配置**
3. **如果数据不存在，检查设备是否正确发送位置数据**