Map Lifecycle

The map lifecycle refers to the entire process from map creation to destruction. Understanding the map lifecycle helps execute corresponding operations at the appropriate time.

Lifecycle Stages

1. Initialization Stage

When a map instance is created, the initialization process is triggered:

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

During initialization, the SDK will:

• Create map container
• Load map styles
• Initialize various managers (layer manager, GeoJSON manager, etc.)
• Register plugins

2. Loading Stage

After the map style is loaded, the load event is triggered:

sdk.on("load", () => {
  console.log("Map style loaded");
  // At this point, map styles can be safely manipulated
});

3. Completion Stage

After all initialization work is complete, the loadComplete event is triggered:

sdk.on("loadComplete", (event) => {
  console.log("Map initialization complete");
  console.log("NOTAM manager:", event.notam);
  console.log("ADSB manager:", event.adsb);
  
  // At this point, all features are ready and can be used
  setupLayerControlPanel();
});

The loadComplete event is triggered after the following operations are complete:

• Period setting complete
• All managers initialized
• Icons loaded
• Chart functionality initialized

4. Running Stage

During normal map operation, various events can be listened to:

// Zoom event
sdk.on("zoom", () => {
  console.log("Current zoom level:", sdk.getZoom());
});

// Move event
sdk.on("move", () => {
  console.log("Map center:", sdk.getCenter());
});

// Rotate event
sdk.on("rotate", () => {
  console.log("Map rotation angle:", sdk.getBearing());
});

5. Reinitialization

When you need to update the period or reload the map, reinitialization can be triggered:

sdk.on("reinit", (event) => {
  console.log("Map reinitialization complete, period:", event.period);
  // Reset layer control panel, etc.
});

6. Destruction Stage

When the map is no longer needed, the map instance should be destroyed to release resources:

sdk.destroy();

Destroying the map will:

• Remove all event listeners
• Clean up all layers and sources
• Release memory resources

Event Order

The typical event order of the map lifecycle:

1. Create Instance → new MapSDK()
2. Style Loading → load event
3. Initialization Complete → loadComplete event
4. During Operation → zoom, move, click and other events
5. Reinitialization → reinit event (optional)
6. Destruction → destroy() method

Best Practices

1. Operate Layers After loadComplete

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

// ❌ Wrong: Adding layers before loadComplete may fail
sdk.addBuiltInLayer("airport");

2. Listen to Error Events

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

3. Clean Up Resources

// Destroy map before page unload
window.addEventListener("beforeunload", () => {
  if (sdk) {
    sdk.destroy();
  }
});

Complete Example

let sdk;

async function initMap() {
  try {
    // 1. Create map instance
    sdk = new navMap.MapSDK({
      container: "map",
      center: [116.39, 39.9],
      zoom: 10,
    });

    // 2. Listen to style loading
    sdk.on("load", () => {
      console.log("Map style loaded");
    });

    // 3. Listen to initialization complete
    sdk.on("loadComplete", (event) => {
      console.log("Map initialization complete");
      
      // 4. Add layers
      sdk.addBuiltInLayer("airport");
      
      // 5. Set up event listeners
      setupEventListeners();
    });

    // 6. Listen to reinitialization
    sdk.on("reinit", (event) => {
      console.log("Map reinitialized, period:", event.period);
    });

  } catch (error) {
    console.error("Map initialization failed:", error);
  }
}

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

  sdk.on("zoom", () => {
    console.log("Zoom level:", sdk.getZoom());
  });
}

// Clean up when page unloads
window.addEventListener("beforeunload", () => {
  if (sdk) {
    sdk.destroy();
  }
});

initMap();