那麼,API 到底是什麼?
應用程式介面(Application Programming Interface,API)是一組存取某個軟體應用程式的編程指令與標準。透過 API,你可以設計出由該 API 所提供服務來驅動的產品——換句話說,別人已經處理好的能力,你可以直接取用。
HTML5 帶來了一批新的 API:
<canvas> 的 2D 繪圖 API,用來渲染圖形與其他視覺影像本文聚焦其中兩個:Geolocation 與 Web Worker。我們先個別拆解它們的原理,再動手做一個同時用上兩者的頁面。
Geolocation API 用來確定並分享地理位置,它回傳經度與緯度座標。企業可以拿這組座標,在周邊區域提供服務——這類服務一般稱為位置服務(Location-Based Service,LBS)。
LBS 以地理資料來源為參照,用來標識被監測裝置的實體位置,進而辨識與該位置相關的人。這讓有興趣的各方得以與之互動,而互動的切入點,是那些以地理位置為中心的服務市場。
商業的本質,是為客戶創造品質、實用性與價值,同時為利害關係人、股東、員工與供應商創造經濟利益。以地理位置為驅動的 LBS,讓「追蹤一個包裹」或「掌握一個人(不論對方用的是瀏覽器還是其他裝置)」變得容易。從商業角度說,地理定位就是運用地理資產確定某人或某物的位置,再把這組資訊提供給有需求的單位或個人——前提是這麼做在法律上站得住腳。
這句前提並非客套話。位置資訊屬於高敏感度的個人資料,實作時應以「取得使用者明確同意、只做必要蒐集、用完即丟」為原則,這既是法規要求,也是使用者信任的基礎。
Geolocation API 建立在 navigator 這個全域物件的新屬性上:navigator.geolocation。JavaScript 的 navigator 物件本來就提供了不少關於使用者瀏覽器與系統的資訊,定位能力是它的延伸。
經緯度可能來自 IP 位址、網路資料庫、無線網路基地台,或三角測量/GPS 等技術。要特別注意的是,回傳結果的精確度會隨取得方式而異;在某些環境下,你可能只得到很粗的估算值,甚至完全取不到讀數。
腳本可以透過 navigator.geolocation 取得與使用者宿主裝置相關的位置資訊。取回資料後,系統會建立一個 position 物件並填入這些數值。
navigator.geolocation 提供三個方法:
getCurrentPosition()watchPosition()clearWatch()這個方法只取一次目前位置。呼叫時,它以非同步(asynchronous)方式嘗試取得宿主裝置的位置。
非同步的意思是:送出請求方與回應方並不在同一時間點上完成整段流程。這樣做的好處是瀏覽器可以繼續處理其他工作,不必停下來乾等定位結果——對使用者而言,就是介面不會卡住。
它最多接受三個參數:
geolocationSuccess:成功取得位置時呼叫的回呼函式(必要)geolocationError:發生錯誤時呼叫的回呼函式(選填)geolocationOptions:定位選項(選填)呼叫時,getCurrentPosition() 會以一個 position 物件作為參數呼叫 geolocationSuccess;若失敗,則以一個 PositionError 物件呼叫 geolocationError。
geolocationOptions 有三個屬性:enableHighAccuracy(在裝置支援的前提下啟用高精度定位)、timeout(等待位置回傳的最長時間)、maximumAge(快取位置可被採用的最長存活時間)。
void navigator.geolocation.getCurrentPosition(
geolocationSuccess, geolocationError, geolocationOptions);
這個方法會週期性輪詢使用者位置,用來偵測位置是否改變,同樣最多接受三個參數。
呼叫後,它會非同步啟動一個監看流程:取得新的 position 物件,並建立一個 watchID。成功時,以 position 物件呼叫 geolocationSuccess;失敗時,以 PositionError 物件呼叫 geolocationError。之後每當裝置位置改變,對應的回呼就會被再次觸發。
long navigator.geolocation.watchPosition(
geolocationSuccess, geolocationError, geolocationOptions);
這個方法用來終止進行中的 watchPosition(),只接受一個參數。呼叫時它會找到對應的 watchID 並立即停止。
void navigator.geolocation.clearWatch(watchID);
Geolocation API 回傳一個 Position 物件,它有兩個屬性:timestamp(該筆定位資料的建立時間)與 coords。coords 底下又有七個屬性:
coords.latitude:估計緯度coords.longitude:估計經度coords.altitude:估計高度coords.accuracy:經緯度估計的精確度,單位為公尺coords.altitudeAccuracy:高度估計的精確度,單位為公尺coords.heading:裝置目前的移動方向角,自正北順時針計算coords.speed:裝置目前對地速度,單位為公尺/秒其中只有 latitude、longitude 與 accuracy 保證有值,其餘會視裝置能力與後端定位服務而定,取不到時回傳 null。heading 與 speed 在可能的情況下,可以依使用者先前位置推算得出。
這個「其餘欄位可能是 null」的特性,在寫程式時務必納入考量——直接拿 altitude 或 speed 做運算之前,先檢查它到底有沒有值。
Web Worker 是 HTML5 對 JavaScript 單執行緒限制的回應。它把耗工的程序放到與主頁面分離的執行緒中執行,把主執行緒留給真正重要的工作,例如維持一個順順不卡頓的使用者介面。
一個 web worker 是在背景載入並執行的 JavaScript 檔案。它讓你能動態載入一支腳本,並在背景下執行而不影響 UI。由於不使用瀏覽器的 UI 執行緒,worker 無法存取 DOM;worker 與主頁面之間透過事件模型與 postMessage() 溝通,傳遞的內容基本上只有字串。worker 內可使用全域的 self 與 this 參照。
因為具備多執行緒行為,worker 只能使用 JavaScript 功能的一個子集。它可以:
專用型 worker 與建立它的那支腳本綁在一起,可以與其他 worker 或瀏覽器元件溝通,但同樣不能碰 DOM。
建立方式是把一支 JavaScript 檔名傳給新的 Worker 實例,也就是透過 Worker() 建構子指定執行腳本的 URI:
var worker = new Worker('worker.js');
共享型 worker 一樣無法存取 DOM,對視窗屬性的存取也受限。不同的是,它只能與來自同一個來源(same origin)的其他共享型 worker 通訊。
通訊方式也不同:頁面腳本要透過一個 port 物件並挂上 message 事件處理器來溝通,而且在呼叫第一次 postMessage() 之前,必須先呼叫該 port 的 start()。
共享型 worker 在收到來自己方腳本的第一則訊息後,會把事件處理器掛到已啟用的 port 上。處理器通常會呼叫自己的 postMessage() 把結果回傳給呼叫端,而 port 的 start() 則讓訊息流程真正開始流動。
建立時要改用 SharedWorker 物件:
var worker = new SharedWorker('worker.js');
接下來設計一個同時使用 Geolocation 與 Web Worker 的頁面,並順手用 Google Maps API 把取到的座標畫成地圖。
頁面結構如圖1:一個用 <header> 建立的頁首、一個用 <section> 建立的內容區,以及一個用 <aside> 建立的側欄。section 放 Geolocation,aside 放負責計算質數的 worker。
圖1. API 頁面的版面配置

執行後如圖2。要看到定位資料,你必須先同意分享位置資訊;worker 則在頁面載入時就開始跑,想看它算出什麼,點一下「Display Web Worker」。
圖2. API 網頁

HTML 的開頭是標準的 HTML5 結構。<head> 中呼叫了 Google Maps API,並把 sensor 參數設為 false——這個參數是在告知 API:你的應用是否使用 GPS 之類的感測器來確定位置,因此必須明確宣告 true 或 false。同一段 head 裡也連結了負責功能與格式的 JavaScript 與 CSS3 檔案。
<!doctype html>
<html>
<head>
<title>基礎地理定位地圖與 Web Worker 質數計算機</title>
<script src="https://maps.google.com/maps/api/js?sensor=false"
type="text/javascript"></script>
<link href="GeolocationWebWorker.css" rel="stylesheet" type="text/css">
<script src="HTML-Part3-GeolocationWebWorker.js"
type="text/javascript"></script>
</head>
(時事提醒:Google Maps API 早已不是這樣用了。現行做法需要申請 API 金鑰並以 key= 參數帶入,sensor 參數也已停用; billing 與用量限制同樣需要留意。上面的寫法保留是為了說明當時的技術脈絡。)
<body> 掛了 onLoad 事件去呼叫定位的初始化函式,如清單2。這個函式會先檢查瀏覽器是否支援定位;若可以與 Geolocation API 溝通,地圖便會被繪製出來。
<body onLoad="initGeoApp();">
<header>
<hgroup>
<h1>Geolocation & Web Worker</h1>
<h2>Making it work</h2>
</hgroup>
</header>
接著的 <section> 放 navigator.geolocation 的輸出。API 回傳的經緯度用來建立地圖畫布,Position 的 coords 各項資料則以 <span> 逐一呈現。
<section>
<p>這是地理定位的示範地圖。</p>
<div id="map_canvas"></div>
<p>以下是 navigator.geolocation 物件的輸出。</p>
<table>
<tr><td>accuracy:</td><td><span id="accuracyOutput"></span></td></tr>
<tr><td>altitude:</td><td><span id="altitudeOutput"></span></td></tr>
<tr><td>altitudeAccuracy:</td><td><span id="altitudeAccuracyOutput"></span></td></tr>
<tr><td>heading:</td><td><span id="headingOutput"></span></td></tr>
<tr><td>latitude:</td><td><span id="latitudeOutput"></span></td></tr>
<tr><td>longitude:</td><td><span id="longitudeOutput"></span></td></tr>
<tr><td>speed:</td><td><span id="speedOutput"></span></td></tr>
</table>
</section>
worker 的部分用上了 <output> 這個新標籤來顯示計算結果。它的 id 與 JavaScript 中用來標識計算結果的 id 相同——這些 id 讓元素在 DOM 中可被存取;沒有 id,JavaScript 根本不知道該把值寫進哪一個 span 或 output。
<aside>
<p>This is the Web Worker.</p>
<p>質數計算結果:
<output id="result"></output>
</p>
<input type="button" value="Display Web Worker" onClick="displayWorker();">
<input type="button" value="Stop Web Worker" onClick="stopWorker();">
</aside>
</body>
</html>
兩個按鈕分別負責顯示與停止 worker。按下的瞬間,displayWorker() 被觸發,把 worker 算出來的結果呈現出來。而 worker 本身,在頁面載入後就已經開始計算質數了。
JavaScript 是這個頁面的引擎。定位由 initGeoApp() 初始化,也就是 <body> 上 onLoad 事件所呼叫的函式:它先判斷瀏覽器能否使用定位資料,若可以就呼叫 Geolocation API;呼叫成功後,會以 Position 的屬性值繪製地圖,並把這些值印在地圖下方。
function initGeoApp() {
if (navigator.geolocation) {
navigator.geolocation.getCurrentPosition(success, failure);
} else {
alert('您的瀏覽器不支援地理定位服務。');
}
}
取值靠的是 document.getElementById——這是文件物件的方法,必須透過 document 呼叫。Position 的屬性值在這裡被取出並寫入對應元素,地圖下方那串數字就是這樣來的。
var map;
function success(position) {
document.getElementById("accuracyOutput").innerHTML =
position.coords.accuracy;
document.getElementById("altitudeOutput").innerHTML =
position.coords.altitude;
document.getElementById("altitudeAccuracyOutput").innerHTML =
position.coords.altitudeAccuracy;
document.getElementById("headingOutput").innerHTML =
position.coords.heading;
document.getElementById("latitudeOutput").innerHTML =
position.coords.latitude;
document.getElementById("longitudeOutput").innerHTML =
position.coords.longitude;
document.getElementById("speedOutput").innerHTML =
position.coords.speed;
接下來定義 Google Maps API 的 LatLng 物件座標。它提供建立地圖所需的座標資訊,你還可以設定縮放層級與其他選項,這些選項共同決定了使用者看到的地圖長什麼樣子。
var coordinates = new google.maps.LatLng(
position.coords.latitude, position.coords.longitude);
var myOptions = {
zoom: 14,
center: coordinates,
mapTypeControl: false,
navigationControlOptions: {
style: google.maps.NavigationControlStyle.small
},
mapTypeId: google.maps.MapTypeId.ROADMAP
};
注意 mapTypeId 這個選項,範例選的是 ROADMAP,呈現出圖2 的樣子。它共有四個可選值:
圖3 是改用 HYBRID 之後的樣子。
圖3. 使用混合式地圖的 API 網頁

map_canvas 這個 id 就是 HTML 檔中那個 <div> 的 id,地圖會被畫在它裡面。
map = new google.maps.Map(
document.getElementById("map_canvas"), myOptions);
最後在初始位置上放一支標記:
var marker = new google.maps.Marker({
position: coordinates,
map: map,
title: "您在這裡。"
});
}
function failure() {
alert('抱歉,無法取得位置資訊。');
}
worker 在頁面初始化之後就開始執行。使用者若想看它算出什麼,點「Display Web Worker」即會呼叫 displayWorker():
var worker = new Worker('PrimeNumberWebWorker.js');
function displayWorker() {
worker.onmessage = function (event) {
document.getElementById('result').innerHTML = event.data;
};
}
想讓它停下來,點「Stop Web Worker」會呼叫 stopWorker():
function stopWorker() {
worker.terminate();
}
這支檔案就是質數計算機本體,它會持續算出下一個質數,直到被終止為止。
var n = 1;
search: while (true) {
n += 1;
for (var i = 2; i <= Math.sqrt(n); i += 1)
if (n % i == 0)
continue search;
postMessage(n);
}
這段程式之所以適合放進 worker,正是因為它是個「不會自己結束」的無窮迴圈。若寫在主執行緒裡,瀏覽器分頁會直接卡死;放進 worker 後,它愛跑多久就跑多久,頁面其他地方照樣能操作。
最後是負責呈現格式的樣式表:
* {
font-family: Arial, Helvetica, sans-serif;
}
body {
margin: 0 300px;
color: #990000;
background-color: #FFFFCC;
}
header > hgroup h1 {
margin: 0 0 3px 0;
padding: 0;
text-align: center;
font-size: 30px;
}
header > hgroup h2 {
margin: 0 0 15px 0;
padding: 0;
text-align: center;
font-style: italic;
font-size: 12px;
}
header p {
margin: 0 0 20px 0;
padding: 0;
text-align: center;
font-size: 12px;
}
aside {
width: 200px;
height: 175px;
margin: -450px 0 0 450px;
background-color: #990000;
padding: .5px 0 0 10px;
color: #FFFFFF;
font-weight: bold;
}
div {
width: 400px;
height: 250px;
}
本文拆解了 Geolocation 與 Web Worker 這兩個 API 的實用性。之所以挑這兩個放在一起,是因為它們一個展現了 API 在商業模式上的創新空間,一個則回應了 JavaScript 併發性所固有的問題——兩者合起來,正好勾勒出一種兼顧商業與社交應用的 HTML5 使用樣式。
不過也別忘了它們各自的限制:定位結果依裝置與環境而變,高精度並非理所當然;worker 拿不到 DOM,只能透過訊息與主頁面溝通,傳遞的資料型別也有限。理解這些邊界,比記住方法名稱更能決定你最後做出來的東西好不好用。