bmap-jsapi-v4

Baidu Map JavaScript API 4.0

Core Principles

Focus on developing browser map applications through the v=4.0 loader and the global BMap namespace, without systematically introducing other versions.

Fixed Constraints

• Use https://api.map.baidu.com/api?v=4.0&ak=YOUR_BAIDU_MAP_AK。
• for the loading URL. New code uses the global BMap, and do not mix namespaces and loading parameters from other versions.
• In the examples, YOUR_BAIDU_MAP_AK needs to be replaced with the developer's own AK; do not expose real keys in shared code and logs.
• Results that depend on AK, online services, CORS, WebGL, or real data need to be verified in the browser.
• When creating listeners, overlays, controls, layers, service rendering results, animations, panoramas, or Maps, also provide the corresponding unbinding, removal, cancellation, or destruction paths.

Workflow

1. Confirm that the task indeed uses v=4.0 and BMap。
2. Only read the reference directly related to the requirement; for cross-module tasks, load in the order of "integration → Map/geometry → business modules → lifecycle → troubleshooting".
3. Select the minimal API combination from the reference that satisfies the requirement.
4. For TypeScript installation, configuration, type errors, or .d.ts supplementary tasks, also read the TypeScript dedicated page.
5. Check version parameters, container size, asynchronous state, event references, and resource cleanup.
6. Perform real browser verification for network- and rendering-related results.

Reference Routing

Integration and Basics

Task	Read
Page loading, AK, synchronous/asynchronous entry points, blank map	project-setup.md
Map initialization, viewport, interaction, styles, rotation and tilt	map-core.md
Control themes, dark mode, theme variables	ui-version-and-theme.md
Point, Pixel, Size, Bounds, coordinate conversion	coordinates-and-geometry.md
Event listening, unbinding, component destruction	events-and-lifecycle.md
Built-in/custom controls and context menus	controls-and-context-menu.md

Overlays

Task	Read
Marker, Icon, Symbol, dragging and events	marker.md
Label, InfoWindow, content updates and closing	label-and-info-window.md
Polyline, Polygon, Rectangle, Circle and editing	vector-overlays.md
CustomOverlay、GroundOverlay、Prism、BezierCurve、PlaceDetail	advanced-overlays.md

Layers and Visualization

Task	Read
GeoJSON, GeoJSONParse, DOMLayer, map text	data-layers.md
MVT vector tiles, styles and feature states	mvt-layer.md
PointIcon, PointShape, Line, Fill batch layers	visualization-layers.md
Extended APIs such as Heatmap, PointLayer, ClusterLayer, TrackLine, Icons	runtime-extended-apis.md
Tile, XYZ, Raster, WMS, WMTS, Traffic, panorama overlays	tile-and-service-layers.md
Administrative district boundaries and DistrictLayer	administrative-district.md

Services and Views

Task	Read
LocalSearch、Autocomplete、Geocoder	search-and-geocoding.md
Driving, walking, riding, transit and bus line search	route-search.md
Geolocation、LocalCity、Convertor	geolocation-and-convertor.md
Panorama、PanoramaService、PanoramaLabel	panorama.md
ViewAnimation, keyframes and cancellation	view-animation.md

Engineering Integration

Task	Read
@baidumap/jsapi-v4-types, global types, tsconfig, declaration augmentation	typescript-integration.md
Troubleshooting performance, containers, coordinates, tiles, CORS, events, and memory	performance-and-troubleshooting.md

Output Contract

• Give the conclusion first, then the minimal complete code and necessary explanation.
• For online services, check the status code and empty results first; for asynchronous callbacks, consider that the component may have already been unmounted or the request may have already expired.
• The cleanup order follows: "stop business asynchrony → unbind events → remove child resources → destroy the Map".
• Only when it is truly necessary to avoid misuse of core APIs, use one sentence to explain the difference from the old approach; version migration must not become the main thread of the answer.
• Passing syntax or type checking does not mean that AK, networking, CORS, WebGL, and online data have already run successfully.

Common mistakes

• Mixing loading parameters, namespaces, or examples from other versions.
• Guessing constructor parameters, events, or cleanup methods based on the class name.
• Treating passing type checking as successful browser execution.
• Using anonymous functions to separately register and remove the same event.
• Only adding overlays or layers without saving references and removing them.
• Ignoring the failure status, empty results, or late callbacks of asynchronous services.