Google AJAX APIs (2) - Using Google's AJAX APIs

Getting Started:
Google 有一系列的 AJAX APIs, 可以不需要寫 server side code, 直接使用在網頁上, 像是 Maps API, AJAX Search API, 還有 AJAX Feed API. 只需要在網頁的最上方 include 一個 <script> tag, 以及提供 Google API key 就可以使用了.

<script type="text/javascript" src="//www.google.com/jsapi?key=ABCDEFG"></script> Google AJAX APIs script 載入之後, 在頁面上使用 google.load 來指定要使用的模組. <script type="text/javascript"> google.load("maps", "2"); google.load("search", "1"); </script> 上面的範例載入了, 第2版 Maps API, 和第1版 AJAX Search API. 執行了 google.load 之後, 就可以在頁面上使用已經讀取過的模組了. 另外可以使用 google.setOnLoadCallback 去指定 document load 的處理函數. 請看底下範例: &lt;html> &lt;head> <script type="text/javascript" src="//www.google.com/jsapi?key=ABCDEFG"></script> <script type="text/javascript"> google.load("maps", "2"); google.load("search", "1"); // 當網頁讀取之後, 呼叫這個函式. function initialize() { var map = new google.maps.Map2(document.getElementById("map")); map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13); var searchControl = new google.search.SearchControl(); searchControl.addSearcher(new google.search.WebSearch()); searchControl.addSearcher(new google.search.NewsSearch()); searchControl.draw(document.getElementById("searchcontrol")); } google.setOnLoadCallback(initialize); </script> &lt;/head> &lt;body> <div id="map" style="width: 200px; height: 200px"></div> <div id="searchcontrol"></div> &lt;/body> &lt;/html>
Detailed Documentation:
google.load
Google AJAX APIs <script> 載入一個google.load 方法, 透過它來載入個別的 AJAX APIs, 它的寫法:

google.load(moduleName, moduleVersion, optionalSettings)

moduleName: 是 API 的名稱(例如: "maps", "search"). 模組名稱同時也是 API 的 namespace.
modileVersion: 指定 API 的版本. 這是一個必要的參數.
optionalSettings: 用來設定 API 其它選項, 例如, 你可以直接指定 Maps API 使用日文 UI. google.load("maps", "2", {"language" : "ja_JP"}); 或是指定不要使用 API 預設的 CSS: google.load("feeds", "1", {"nocss" : true}); 使用這些選項請參考各 API 的文件.

API Namespaces:
API 的模組名稱同時也是它的 namespace. 所以 "maps" 模組的方法, 全部在 google.maps 底下, 以前的 Google AJAX APIs 像是 Maps API 的 classes 和 常數, 使用 G 當作字首, 依照新的命名原則, class 不會再是 G 開頭了. 例如: GMap2 變成 google.maps.Map2 現有使用 G 當字首的 APIs 會繼續同時支援新舊兩種命名方式. 但是新的 APIs 只會支援 google.moduleName

API Versioning:
google.load 的第二個參數是 API 的版本. 每個 AJAX API 都有一個主要版本和修定版本. AJAX APIs 更新的非常頻繁, 為了保持穩定性, 所有的 AJAX Apis 都有一個有效的 stable version與 test version. 例如: 最新的2.24版, 前一個修定版本 2.23 會變成這個 API 的 stable version. 而 2.24 則會是 test version. 如果你要求 version 2的 API, 而且沒有指定修定版次, 你會自動的取得 stable version 2.23. 如果你需要 test version, 你可以明確的指定 version 2.24, 或是你可以使用特別的通配字元 2.x, 這個會指定到 API 的 test version 2.24. 直到有一個更新的版次出現.

Dynamic Loading:
AJAX API loader 可以動態的引用到網頁上. 如果你不想要網頁讀取的時候就使 API 生效, 這是非常有用的. 例如: 使用者在執行搜尋或是其他動作, 才執行 API.
這可以使用第三個參數 callback 來完成, 範例如下: function mapsLoaded() { var map = new google.maps.Map2(document.getElementById("map")); map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13); } function loadMaps() { google.load("maps", "2", {"callback" : mapsLoaded}); } 當你呼叫 loadMaps(), 他會載入 Maps API 並且在 API 準備好之後執行 mapsLoaded. 確定 DOM 準備好了之後, 當你呼叫 google.load 與 callback 參數, 它會試著在 DOM 加上一個 element. 隨著載入 Maps API 之後, 會立即執行所提供的 callback, 而且你不需要擔心同樣的 API 會載入多次的問題.

你也可已經由建立一個 script element 動態的載入 Google AJAX API loader, 同樣設定他的來源 URL "http://www.google.com/jsapi?...", 加上一個查詢參數 callback. 這個 callback 會在 loader 準備好之後呼叫. 範例如下: function mapsLoaded() { var map = new google.maps.Map2(document.getElementById("map")); map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13); } function loadMaps() { google.load("maps", "2", {"callback" : mapsLoaded}); } function initLoader() { var script = document.createElement("script"); script.src = "http://www.google.com/jsapi?key=ABCDEFG&callback=loadMaps"; script.type = "text/javascript"; document.getElementsByTagName("head")[0].appendChild(script); }