Site icon Soul & Shell Blog

Android WebApp 開發教學 (4) - PhoneGap Contacts API 使用教學

Introduction - 前言

在之前的文章「Android WebApp 開發教學 - HTML5 + PhoneGap = 如虎添翼」中,已經與各位介紹過 JavaScript Bridge 技術與 PhoneGap。接下來我們就來試試看 PhoneGap 用起來的感覺是如何囉。

PhoneGap Contacts API 使用教學

首先我們先參考前面幾篇文章建立 Android Project,並且掛上 PhoneGap Library。還記得之前的「Android WebApp 開發教學 - HTML5 Web Storage」這一篇文章中,我們使用 HTML5 Web Storage 設計了一個聯絡簿 WebApp。接下來我們要透過 PhoneGap Contacts API 將聯絡簿的資料與手機進行整合。先說明一下,PhoneGap 都是採用 JavaScript 的方式呼叫,並且統一用 Callback 進行非同步處理,所有 PhoneGap 的 API 都是建立在 navigator 這個物件中,如果您有對 PhoneGap 實作自己的 Plugins 也是一樣透過 navigator 來呼叫喔。接下來的聯絡簿範例我們會用到以下兩個函式:

// 讀取手機聯絡簿
navigator.contacts.find(fields, onSuccess, onError);

// 建立手機聯絡簿
navigator.contacts.create();

先看一下 index.html 的內容,這裡僅設計顯示畫面,有關業務邏輯的程式我們放在 contacts_pg.js 這一支檔案中。

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh-TW">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>HTML5 WebApp Contacts Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova-1.7.0.js"></script>
    <script type="text/javascript" charset="utf-8" src="jquery.min.js"></script>
    <script type="text/javascript" charset="utf-8" src="contacts_pg.js"></script>
</head>
<body>
    <h2>WebApp PhoneGap 聯絡簿</h2>
    <p><input type="button" value="刷新聯絡簿" id="refresh_btn" /></p>
    <table border="1">
    	<thead>
            <tr>
                <th>姓名</th>
                <th>電話</th>
    	    </tr>
    	</thead>
    	<tbody id="contact_body">
    	</tbody>
    </table>
    <p>姓名:<input type="text" name="name_txt" id="name_txt" /></p>
    <p>電話:<input type="text" name="tel_txt" id="tel_txt" /></p>
    <p><input type="button" value="新增" id="create_btn" /></p>
</body>
</html>

接著來看一下 contacts_pg.js 的內容(如下程式碼),處理的過程中我們也會用到 jQuery 函式,這裡就先不介紹囉。

// 網頁都載入完畢後才會執行
$(document).ready(function(){

    // 重新刷新手機聯絡簿
    $('#refresh_btn').click(function(){
        // 只抓 displayName, phoneNumbers 兩個欄位
        var fields = ['displayName', 'phoneNumbers'];
        navigator.contacts.find(fields, onSuccess, onError);
    });

    // 建立一筆新的聯絡簿成員
    $('#create_btn').click(function(){
        // 電話必須使用陣列存放
         var phoneNumbers = [];
        phoneNumbers[0] = new ContactField('work', $('#tel_txt').val(), false);

        // 建立 Contact 物件並且儲存
        var myContact = navigator.contacts.create();
        myContact.displayName = $('#name_txt').val();
        myContact.phoneNumbers = phoneNumbers;
        myContact.save(
            function(){
                alert('新增完成');
                $('#name_txt').val('');
                $('#tel_txt').val('');
            }, 
            onError
        );
    });

});

// 讀取手機聯絡簿成功後要執行的程式
function onSuccess(contacts) {
    // 先清空 Table
    $('#contact_body').children().remove();
    for (var i=0; i<contacts.length; i++) {
        var tels = '';
        for (x in contacts[i].phoneNumbers) {
            tels += contacts[i].phoneNumbers[x].value + '<br/>';
        }
        // 新增資料到畫面 Table 中
        $('#contact_body').append('<tr><td>'+contacts[i].displayName+'</td><td>'+tels+'</td></tr>');
    }
}

// 發生錯誤要執行的程式
function onError(contactError) {
    alert('Error!');
}

Android WebApp 執行後的畫面如下,輸入姓名與電話後按下「新增」按鈕,新增完成後按下「刷新聯絡簿」重新讀取手機聯絡簿:

剛剛新增的聯絡簿也可在手機裡面看的到,畫面如下:

整體用起來的感覺還算順暢,理論上把這樣的程式拿到 iOS 等等其他作業系統中,應該是能夠正常運作的(筆者手邊暫無環境可以測試)。PhoneGap 還有其他很多 API 可以玩,有機會再跟各位介紹囉。

Reference - 參考資料

系列文章

Exit mobile version