常见问题（FAQ）

基础问题

Q: 如何初始化地图？

A: 使用 MapSDK 类创建地图实例：

const sdk = new navMap.MapSDK({
  container: "map",
  center: [116.39, 39.9],
  zoom: 10,
});

Q: 地图容器需要什么样式？

A: 地图容器需要有明确的宽高：

#map {
  width: 100%;
  height: 100vh; /* 或其他固定高度 */
}

Q: 如何引入 SDK？

A: 可以通过 CDN 或 npm 包引入：

CDN 方式：

<link href="https://aips.siniswift.com/sdk/sdk.style.css" rel="stylesheet" />
<script src="https://aips.siniswift.com/sdk/nav-sdk.min.js"></script>

npm 方式：

npm install @your-org/nav-sdk

import { MapSDK } from '@your-org/nav-sdk';

图层问题

Q: 如何添加内置图层？

A: 使用 addBuiltInLayer 方法：

sdk.on("loadComplete", async () => {
  await sdk.addBuiltInLayer("airport");
});

Q: 图层添加失败怎么办？

A: 确保在地图 loadComplete 事件后再添加图层：

sdk.on("loadComplete", async () => {
  // ✅ 正确：在这里添加图层
  await sdk.addBuiltInLayer("airport");
});

// ❌ 错误：在地图加载完成前添加
await sdk.addBuiltInLayer("airport");

Q: 如何移除图层？

A: 使用 removeBuiltInLayer 方法：

sdk.removeBuiltInLayer("airport");

Q: 如何切换图层显示？

A: 使用 toggleBuiltInLayer 方法：

sdk.toggleBuiltInLayer("airport");

标记问题

Q: 如何添加点标记？

A: 使用 addPoint 方法：

const featureId = sdk.addPoint(
  [116.3974, 39.9093],
  { name: "北京" },
  {
    paint: {
      "circle-radius": 10,
      "circle-color": "#ff0000",
    },
  }
);

Q: 如何删除点标记？

A: 使用 removeLayer 方法：

sdk.removeLayer(featureId);

Q: 如何更新标记位置？

A: 更新 GeoJSON 源数据：

const feature = sdk.geoJSONManager.getFeature(featureId);
feature.geometry.coordinates = [121.4737, 31.2304];
sdk.getSource("source-id").setData(updatedGeoJSON);

样式问题

Q: 如何自定义图层样式？

A: 使用 setStyle 或 updateLayerStyle 方法：

sdk.setStyle({
  "airport": {
    paint: {
      "icon-color": "#ff0000",
    },
  },
});

Q: 样式不生效怎么办？

A: 检查以下几点：

1. 确保图层ID正确
2. 确保在地图 loadComplete 后应用样式
3. 检查样式属性是否与图层类型匹配

Q: 如何根据缩放级别动态调整样式？

A: 监听 zoom 事件：

sdk.on("zoom", () => {
  const zoom = sdk.getZoom();
  sdk.setStyle({
    "airport-label": {
      paint: {
        "text-size": zoom < 12 ? 12 : 16,
      },
    },
  });
});

事件问题

Q: 如何监听地图点击事件？

A: 使用 on 方法：

sdk.on("click", (e) => {
  console.log("点击位置:", e.lngLat);
});

Q: 如何监听特定图层的事件？

A: 在事件名后指定图层ID：

sdk.on("click", "airport", (e) => {
  console.log("点击了机场:", e.features[0]);
});

Q: 如何移除事件监听？

A: 使用 off 方法：

const handler = (e) => console.log(e);
sdk.on("click", handler);
sdk.off("click", handler);

性能问题

Q: 如何优化大量点的渲染？

A: 使用聚类功能：

sdk.addGeoJSON("points-source", geojson, {
  cluster: true,
  clusterRadius: 50,
  clusterMaxZoom: 16,
});

Q: 如何启用 LOD 优化？

A: 使用 setLODEnabled 方法：

sdk.layerManager.setLODEnabled(true);

Q: 地图卡顿怎么办？

A: 尝试以下优化：

1. 启用 LOD 配置
2. 使用聚类显示大量点
3. 简化图层样式
4. 根据缩放级别动态显示/隐藏图层

3D模式问题

Q: 如何启用3D模式？

A: 在地图 load 事件后设置投影：

sdk.on("load", () => {
  sdk.map.setProjection({
    type: "globe",
  });
});

Q: 3D模式不显示怎么办？

A: 确保：

1. 在地图 load 事件后设置投影
2. 浏览器支持 WebGL
3. 设置了合适的倾斜角度

插件问题

Q: 如何使用测量插件？

A: 创建插件实例并使用：

const measurePlugin = new navMap.MeasurePlugin();
sdk.use(measurePlugin);
measurePlugin.enable("distance");

Q: 如何开发自定义插件？

A: 实现 IPlugin 接口：

class MyPlugin implements IPlugin {
  name = "my-plugin";
  
  install(sdk) {
    // 插件安装逻辑
  }
  
  uninstall(sdk) {
    // 插件卸载逻辑
  }
}

const plugin = new MyPlugin();
sdk.use(plugin);

错误处理

Q: 如何处理地图错误？

A: 监听 error 事件：

sdk.on("error", (error) => {
  console.error("地图错误:", error);
  // 处理错误
});

Q: 地图初始化失败怎么办？

A: 检查：

1. 容器元素是否存在
2. 容器是否有明确的宽高
3. SDK 文件是否正确加载
4. 浏览器控制台是否有错误信息

其他问题

Q: 如何获取地图当前状态？

A: 使用相应的方法：

const center = sdk.getCenter();
const zoom = sdk.getZoom();
const bounds = sdk.getBounds();
const bearing = sdk.getBearing();
const pitch = sdk.getPitch();

Q: 如何设置地图中心？

A: 使用 setCenter 或 flyTo 方法：

// 直接设置
sdk.setCenter([116.39, 39.9]);

// 带动画
sdk.flyTo({
  center: [116.39, 39.9],
  zoom: 12,
  duration: 1000,
});

Q: 如何适应边界范围？

A: 使用 fitBounds 方法：

sdk.fitBounds(
  [[116.0, 39.0], [117.0, 40.0]],
  {
    padding: 50,
    duration: 1000,
  }
);

获取帮助

如果以上问题无法解决你的问题，可以：

1. 查看 API 参考手册
2. 查看 示例代码
3. 提交 Issue 到项目仓库
4. 联系技术支持(anzhongqi@casc.com.cn)