Interaction & Events

The SDK provides rich map interaction features and an event system, supporting various interaction methods including mouse, touch, keyboard, etc.

Mouse Interactions

Click Event

// Listen to map click
sdk.on("click", (e) => {
  console.log("Click position:", e.lngLat);
  console.log("Clicked features:", e.features);
  
  // Query features at click position
  const features = sdk.queryRenderedFeatures(e.point);
  console.log("Queried features:", features);
});

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

Double Click Event

sdk.on("dblclick", (e) => {
  // Double click to zoom in
  sdk.zoomIn();
});

Context Menu

sdk.on("contextmenu", (e) => {
  e.preventDefault();
  
  // Show custom context menu
  showContextMenu(e.lngLat);
});

Mouse Hover

// Mouse enter
sdk.on("mouseenter", "airport", (e) => {
  // Change cursor style
  sdk.getCanvas().style.cursor = "pointer";
});

// Mouse leave
sdk.on("mouseleave", "airport", (e) => {
  sdk.getCanvas().style.cursor = "";
});

Mouse Move

sdk.on("mousemove", (e) => {
  // Display mouse position in real-time
  updateMousePosition(e.lngLat);
});

Drag Interactions

Enable/Disable Drag

// Disable drag
sdk.dragPan.disable();

// Enable drag
sdk.dragPan.enable();

Drag Events

sdk.on("dragstart", () => {
  console.log("Drag started");
});

sdk.on("drag", () => {
  console.log("Dragging");
});

sdk.on("dragend", () => {
  console.log("Drag ended");
});

Zoom Interactions

Mouse Wheel Zoom

// Disable wheel zoom
sdk.scrollZoom.disable();

// Enable wheel zoom
sdk.scrollZoom.enable();

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

sdk.on("zoomstart", () => {
  console.log("Zoom started");
});

sdk.on("zoomend", () => {
  console.log("Zoom ended");
});

Double Click Zoom

// Disable double click zoom
sdk.doubleClickZoom.disable();

// Enable double click zoom
sdk.doubleClickZoom.enable();

Rotation Interactions

Enable/Disable Rotation

// Disable rotation (right-click drag)
sdk.dragRotate.disable();

// Enable rotation
sdk.dragRotate.enable();

Rotation Events

sdk.on("rotate", () => {
  console.log("Rotation angle:", sdk.getBearing());
});

sdk.on("rotatestart", () => {
  console.log("Rotation started");
});

sdk.on("rotateend", () => {
  console.log("Rotation ended");
});

Keyboard Interactions

Enable/Disable Keyboard

// Disable keyboard control
sdk.keyboard.disable();

// Enable keyboard control
sdk.keyboard.enable();

Keyboard Events

The SDK supports the following keyboard shortcuts by default:

• + / -: Zoom
• ← / → / ↑ / ↓: Pan
• Shift + ← / Shift + →: Rotate

// Listen to keyboard events
document.addEventListener("keydown", (e) => {
  if (e.key === "+" || e.key === "=") {
    sdk.zoomIn();
  } else if (e.key === "-") {
    sdk.zoomOut();
  }
});

Touch Interactions (Mobile)

Touch Events

sdk.on("touchstart", (e) => {
  console.log("Touch started");
});

sdk.on("touchmove", (e) => {
  console.log("Touch moving");
});

sdk.on("touchend", (e) => {
  console.log("Touch ended");
});

Pinch Zoom

sdk.on("touchzoom", () => {
  console.log("Pinch zoom");
});

Feature Queries

Query Rendered Features

// Query features at click position
sdk.on("click", (e) => {
  const features = sdk.queryRenderedFeatures(e.point);
  console.log("Queried features:", features);
});

// Query features from specific layers
const features = sdk.queryRenderedFeatures(e.point, {
  layers: ["airport", "airline"],
});

// Query features in a specific area
const boxFeatures = sdk.queryRenderedFeatures([
  [x1, y1],
  [x2, y2],
]);

Query Source Data

// Query all features in source
const sourceFeatures = sdk.querySourceFeatures("airport-source", {
  sourceLayer: "airport",
  filter: ["==", "type", "civil"],
});

Event Management

Add Event Listeners

// Add event listener
const handler = (e) => {
  console.log("Event triggered:", e);
};

sdk.on("click", handler);

Remove Event Listeners

// Remove specific listener
sdk.off("click", handler);

// Remove all listeners
sdk.off("click");

One-time Event Listeners

// Listen only once
sdk.once("loadComplete", () => {
  console.log("Map loaded (executed once)");
});

Custom Interactions

Using ClickManager

// Show popup on click
sdk.clickObj.clickPopup(
  "airport",
  (feature) => {
    return `<h3>${feature.properties.name}</h3>`;
  },
  {
    anchor: "bottom",
    closeButton: true,
  }
);

Using HoverManager

// Show information on hover
sdk.hover.hoverPopup(
  "airport",
  (feature) => {
    return `<div>${feature.properties.name}</div>`;
  },
  {
    anchor: "top",
  }
);

Using SelectFeature

// Enable feature selection
sdk.selector.enable({
  onSelect: (feature, properties) => {
    console.log("Selected feature:", feature);
  },
  isHighlight: true, // Highlight selected feature
  isMultiSelect: false, // Whether to support multi-select
});

// Disable feature selection
sdk.selector.disable();

// Clear selection
sdk.selector.clearSelection();

Complete Example

let sdk;

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

  sdk.on("loadComplete", () => {
    setupInteractions();
  });
}

function setupInteractions() {
  // 1. Click to query features
  sdk.on("click", (e) => {
    const features = sdk.queryRenderedFeatures(e.point, {
      layers: ["airport"],
    });
    
    if (features.length > 0) {
      const feature = features[0];
      showFeatureInfo(feature);
    }
  });

  // 2. Hover highlight
  sdk.on("mouseenter", "airport", (e) => {
    sdk.getCanvas().style.cursor = "pointer";
    highlightFeature(e.features[0]);
  });

  sdk.on("mouseleave", "airport", () => {
    sdk.getCanvas().style.cursor = "";
    clearHighlight();
  });

  // 3. Double click zoom
  sdk.on("dblclick", (e) => {
    sdk.flyTo({
      center: e.lngLat,
      zoom: sdk.getZoom() + 1,
      duration: 500,
    });
  });

  // 4. Context menu
  sdk.on("contextmenu", (e) => {
    e.preventDefault();
    showContextMenu(e.lngLat);
  });

  // 5. Adjust layers on zoom
  sdk.on("zoom", () => {
    const zoom = sdk.getZoom();
    if (zoom > 12) {
      sdk.showLayers(["detail-layer"]);
    } else {
      sdk.hideLayers(["detail-layer"]);
    }
  });

  // 6. Use selection manager
  sdk.selector.enable({
    onSelect: (feature) => {
      console.log("Selected feature:", feature);
    },
    isHighlight: true,
  });
}

function showFeatureInfo(feature) {
  const popup = new navMap.Popup()
    .setLngLat(feature.geometry.coordinates)
    .setHTML(`<h3>${feature.properties.name}</h3>`)
    .addTo(sdk.map);
}

initMap();

Notes

1. Event Order: Ensure event listeners are added after map loadComplete
2. Performance Optimization: Avoid complex operations in frequently triggered events (such as mousemove)
3. Event Cleanup: Remember to remove event listeners before page unload to avoid memory leaks
4. Mobile Adaptation: Mobile devices should prioritize touch events over mouse events