要在自己的專案裡嵌入一張可互動的地圖,百度地圖 JavaScript API 至今仍是很常見的選擇。從註冊密鑰、引入 JS 檔,到建立地圖、加上各類控件、綁定事件、放置標注與資訊視窗,這條路徑其實並不複雜。本文把整個流程依序梳理一遍,並附上可直接參考的程式碼片段。
所有調用都必須帶上開發者密鑰。百度地圖 API 首頁就有申請入口,填寫網站或應用的基本資訊後,即可拿到一組 ak 字串,後續載入腳本時作為參數傳入。
把 ak 換成自己的密鑰即可:
<script type="text/javascript" src="https://api.map.baidu.com/api?ak=yourkey&v=2.0&services=false"></script>
var map = new BMap.Map("container"); // 建立地圖實例
var point = new BMap.Point(120.391655, 36.067588); // 建立座標點
map.centerAndZoom(point, 15);
// 也可以直接用城市名稱定位:
// map.centerAndZoom("北京", 15);
// map.centerAndZoom("Hongkong", 15);
這裡有三點需要特別說明:
1. centerAndZoom 的第一個參數可以是先建立好的 BMap.Point 座標物件,也可以直接傳入城市中文名稱;若拼寫正確,英文名稱同樣可用。
2. 第二個參數是縮放等級,範圍是 0 到 19,數字越大地圖越放大。實務上縮到 3 左右就已經接近全球視野了。
3. BMap.Map 需要一個容器元素,地圖會自動適配容器的寬高,所以只要把容器 id 傳進去即可。

可以用程式主動設定層級:
map.setZoom();
也可以開放給使用者用滾輪操作:
map.enableScrollWheelZoom(true);
百度地圖把地圖上負責互動的 UI 元素稱為「控件」,API 內建的控件相當齊全:
1. Control:所有控件的抽象基類,繼承它即可打造自訂控件。
2. NavigationControl:平移縮放控件,PC 端預設在地圖左上角,行動端則是右下角的縮放鈕。
3. OverviewMapControl:可折疊的縮略地圖,預設在右下角。
4. ScaleControl:比例尺,預設在左下角。
5. MapTypeControl:地圖類型切換(地圖、衛星、三維),預設在右上角。
6. CopyrightControl:版權資訊,預設在左下角。
7. GeolocationControl:定位控件,主要面向行動端,預設在左下角。
加入控件只需要一行 addControl:
map.addControl(new BMap.NavigationControl()); // 縮放平移控件
map.addControl(new BMap.ScaleControl()); // 比例尺
map.addControl(new BMap.OverviewMapControl()); // 縮略圖
map.addControl(new BMap.MapTypeControl()); // 地圖類型
map.setCurrentCity("青島");
注意:只有設定了城市資訊,MapTypeControl 的切換功能才會生效。

API 中大多數物件都提供了 addEventListener 方法,用來監聽各種互動行為:
map.addEventListener("click", function(){
alert("您點擊了地圖。");
});
不再需要監聽時,用對應的 removeEventListener 移除即可。實務上通常會先把回呼函數命名保存下來,再傳給這兩個方法,否則會因為函數參考不同而移除失敗:
map.removeEventListener("click", functionA);
map.addEventListener("click", functionA);
覆蓋物是畫在地圖上的額外圖層,同樣以 Overlay 作為抽象基類:
· Marker:地圖上的標點,可自訂圖示。
· Label:文字標注,內容與樣式皆可自訂。
· Polyline:折線。
· Polygon:多邊形,等同封閉的折線,還能加填色。
· Circle:圓形。
· InfoWindow:資訊視窗,屬於特殊覆蓋物,可承載較豐富的文字與多媒體內容;同一時刻地圖上只能開啟一個。
var point = new BMap.Point(120.389472, 36.072362);
// 不指定 icon 時使用預設圖示,也可透過 Icon 類自訂
var marker = new BMap.Marker(point);
var label = new BMap.Label("青島市政府", {offset: new BMap.Size(20, -10)});
marker.setLabel(label); // 設定標注說明
marker.enableDragging(); // 允許拖動標注
marker.addEventListener("dragend", function(e){
alert(e.point.lng + ", " + e.point.lat); // 印出拖動後的座標
});
map.addOverlay(marker);
var point2 = new BMap.Point(120.387244, 36.064835);
var myIcon = new BMap.Icon("https://api.map.baidu.com/img/markers.png", new BMap.Size(23, 25));
var marker2 = new BMap.Marker(point2, {icon: myIcon});
map.addOverlay(marker2);
var infoWindow = new BMap.InfoWindow("<p style='font-size:14px;'>詳細資訊</p>");
marker2.addEventListener("click", function(){
this.openInfoWindow(infoWindow);
});

把上面幾個部分串起來,就足夠應付絕大多數「地圖 + 標點 + 互動」的常見需求。更進階的路線規劃、行政區邊界、客製化主題等能力,可以延續同樣的思路,對照官方 API 文件繼續擴充。