Frequently Asked Questions (FAQ)

Basic Questions

Q: How to initialize the map?

A: Use the MapSDK class to create a map instance:

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

Q: What styles does the map container need?

A: The map container needs explicit width and height:

#map {
  width: 100%;
  height: 100vh; /* or other fixed height */
}

Q: How to import the SDK?

A: Can be imported via CDN or npm package:

CDN method:

<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 method:

npm install @your-org/nav-sdk

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

Layer Questions

Q: How to add built-in layers?

A: Use the addBuiltInLayer method:

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

Q: What to do if layer addition fails?

A: Ensure layers are added after the map loadComplete event:

sdk.on("loadComplete", async () => {
  // ✅ Correct: Add layers here
  await sdk.addBuiltInLayer("airport");
});

// ❌ Wrong: Adding before map load completes
await sdk.addBuiltInLayer("airport");

Q: How to remove layers?

A: Use the removeBuiltInLayer method:

sdk.removeBuiltInLayer("airport");

Q: How to toggle layer visibility?

A: Use the toggleBuiltInLayer method:

sdk.toggleBuiltInLayer("airport");

Marker Questions

Q: How to add point markers?

A: Use the addPoint method:

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

Q: How to delete point markers?

A: Use the removeLayer method:

sdk.removeLayer(featureId);

Q: How to update marker position?

A: Update GeoJSON source data:

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

Style Questions

Q: How to customize layer styles?

A: Use setStyle or updateLayerStyle methods:

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

Q: What to do if styles don't take effect?

A: Check the following:

1. Ensure the layer ID is correct
2. Ensure styles are applied after map loadComplete
3. Check if style properties match the layer type

Q: How to dynamically adjust styles based on zoom level?

A: Listen to the zoom event:

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

Event Questions

Q: How to listen to map click events?

A: Use the on method:

sdk.on("click", (e) => {
  console.log("Click position:", e.lngLat);
});

Q: How to listen to events on specific layers?

A: Specify the layer ID after the event name:

sdk.on("click", "airport", (e) => {
  console.log("Clicked airport:", e.features[0]);
});

Q: How to remove event listeners?

A: Use the off method:

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

Performance Questions

Q: How to optimize rendering of large numbers of points?

A: Use clustering functionality:

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

Q: How to enable LOD optimization?

A: Use the setLODEnabled method:

sdk.layerManager.setLODEnabled(true);

Q: What to do if the map is lagging?

A: Try the following optimizations:

1. Enable LOD configuration
2. Use clustering for large numbers of points
3. Simplify layer styles
4. Dynamically show/hide layers based on zoom level

3D Mode Questions

Q: How to enable 3D mode?

A: Set projection after map load event:

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

Q: What to do if 3D mode doesn't display?

A: Ensure:

1. Projection is set after map load event
2. Browser supports WebGL
3. Appropriate tilt angle is set

Plugin Questions

Q: How to use the measurement plugin?

A: Create a plugin instance and use it:

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

Q: How to develop custom plugins?

A: Implement the IPlugin interface:

class MyPlugin implements IPlugin {
  name = "my-plugin";
  
  install(sdk) {
    // Plugin installation logic
  }
  
  uninstall(sdk) {
    // Plugin uninstallation logic
  }
}

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

Error Handling

Q: How to handle map errors?

A: Listen to the error event:

sdk.on("error", (error) => {
  console.error("Map error:", error);
  // Handle error
});

Q: What to do if map initialization fails?

A: Check:

1. Whether the container element exists
2. Whether the container has explicit width and height
3. Whether SDK files are loaded correctly
4. Whether there are error messages in the browser console

Other Questions

Q: How to get the current map state?

A: Use the corresponding methods:

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

Q: How to set the map center?

A: Use setCenter or flyTo methods:

// Direct setting
sdk.setCenter([116.39, 39.9]);

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

Q: How to fit bounds?

A: Use the fitBounds method:

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

Getting Help

If the above questions cannot solve your problem, you can:

1. Check the API Reference Manual
2. Check the Example Code
3. Submit an Issue to the project repository
4. Contact technical support(anzhongqi@casc.com.cn)