JavaScript API 文檔中參數標記的含義解析

理解 API 文檔中的可選參數語法

在閱讀百度地圖 JavaScript API 文檔時，經常會遇到類似 getViewport(view: Array<Point>[, viewportOptions: ViewportOptions]) 這樣的函數簽名。這裡的方括號 [] 和逗號 , 究竟代表什麼意思？

方括號表示可選參數

在 API 文檔的慣例中，方括號 [] 內的內容代表可選參數。這意味著調用該函數時，可以只傳遞必需參數 view，而省略 viewportOptions 參數。

逗號的作用

逗號 , 位於方括號內部的開頭位置（即 [, viewportOptions: ViewportOptions]），這是因為當省略可選參數時，前面的必需參數後面不需要額外的逗號分隔符。文檔寫法將逗號包含在可選部分中，避免了語法上的歧義。

參數類型說明

• view: Array<Point>：必需參數，類型為 Point 對象的數組
• viewportOptions: ViewportOptions：可選參數，類型為 ViewportOptions 對象，用於配置視口選項（如邊距、縮放級別等）

實際調用示例

// 僅傳遞必需參數
map.getViewport(pointsArray);

// 傳遞可選配置參數
map.getViewport(pointsArray, {
    margins: [10, 10, 10, 10],
    zoomFactor: 0.8
});

掌握這種文檔閱讀慣例，能幫助開發者快速理解 API 的使用方式，避免因參數傳遞錯誤導致的運行時異常。