手把手教你玩转cordova（PhoneGap）

通讯录

前言

这一章我们将学习如何使用cordova访问手机的通讯录（联系人），包括读取通讯录中的所有联系人信息、添加新的联系人、删除指定的联系人、按条件查找联系人.....等等。

一、获取通讯录数据

打开PhoneGap PC端，创建一个名为“Contacts”的项目。

修改文件 www -> index.html，使其最终成为以下这样：

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="format-detection" content="telephone=no" />
<meta name="msapplication-tap-highlight" content="no" />
<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width" />
<meta http-equiv="Content-Security-Policy" content="default-src * 'unsafe-inline'; style-src 'self' 'unsafe-inline'; media-src *" />
<title>Contacts</title>
<style type="text/css">
html,body{padding:0px;margin:0px;height:100%;overflow:hidden;}
.container{height:100%;overflow-y:auto;}
#divLst > div{padding:18px 5px;border-bottom:1px solid #444;position:relative;}
#divLst > div > .right{position:absolute;right:3px;top:10px;bottom:0px;line-height:100%;}
</style>
</head>
<body>
<div class="container">
<div id="divLst"></div>
</div>
<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript" src="js/index.js"></script>
<script type="text/javascript">
app.initialize();
</script>
</body>
</html>

在网页中有一个ID为“divLst”的DIV，我们希望网页加载后，将用户手机中的通讯录的所有数据读出来显示在此DIV中。

打开文件 www -> js -> index.js，删掉我们并不需要的变量“app”的“receivedEvent”属性，编辑 onDeviceReady 方法：

onDeviceReady: function () {
var divLst = document.getElementById('divLst');
var createItem = function (contact) {
var div = document.createElement('div');
divLst.insertBefore(div, divLst.children[0]);
// phoneNumbers 是一个数组，因为有些设备允许为一个联系人设置多个电话号码。
// 我们这里只将联系人的第一个电话展示了出来。
var phone = contact.phoneNumbers[0];
if (phone) {
phone = phone.value; // phone 是一个 object，phone.value 才是我们需要的电话号码
}
div.innerHTML = contact.displayName + '（' + phone + '）';
};
// 读取通讯录中的所有联系人信息。
// 第一个参数是一个数组，它决定了返回的数据中包含联系人的哪些信息，
// 可包含的值有：
//id：唯一标识符；
//displayName：显示的名称；
//nickname：昵称；
//phoneNumbers：电话；
//emails：电子邮箱；
//addrsses：地址；
//ims：即时通讯地址；
//birthday：生日；
//note：备注；
//photos：照片
// 如果传的是一个空数组，则返回的数据中只会包含联系人的ID。
navigator.contacts.find(['displayName', 'phoneNumbers'], function (lst) {
// 调用成功后执行此方法。
// 返回的数据 lst 是一个数组，遍历数组，将每一个联系人的信息展示在 divLst 中。
for (var i = 0; i < lst.length; i++) {
createItem(lst[i]);
}
}, function (err) {
// 调用失败后执行此方法
alert('发生错误了。' + err);
});
}

然后，在手机端运行PhoneGap测试。

如果只需要获取名字（displayName）中带有“陈”字的联系人，则需传入第四个参数，将以上方法修改为：

onDeviceReady: function () {
var divLst = document.getElementById('divLst'),
options = new ContactFindOptions(); // 这里创建了一个 ContactFindOptions 的实例，将传递给 navigator.contacts.find() 方法的第四个参数，它将作为一个筛选条件
// 设置筛选条件，这里指定的是只查找名字中带“陈”字的联系人。
// 这个筛选条件会与 find 方法中的第一个参数中所传递的所有字段相比较（不区分大小写），
// 在我们这个案例中，实际上是查找 displayName 与 phoneNumbers 这两个字段中任意一个带有“陈”字的联系人，但 phoneNumber 中显然不可能有“陈”字
options.filter = '陈';
// 是否返回多条数据。默认为 false，即只会返回一个符合条件的数据。
options.multiple = true;
var createItem = function (contact) {
var div = document.createElement('div');
divLst.insertBefore(div, divLst.children[0]);
var phone = contact.phoneNumbers[0];
if (phone) {
phone = phone.value;
}
div.innerHTML = contact.displayName + '（' + phone + '）';
};
navigator.contacts.find(['displayName', 'phoneNumbers'], function (lst) {
for (var i = 0; i < lst.length; i++) {
createItem(lst[i]);
}
}, function (err) {
alert('发生错误了。' + err);
}, options);
}

二、创建联系人

接下来，我们可以在我们的App中创建新的联系人，并将新创建的联系人的信息保存到手机的通讯录中。

首先我们需要修改 index.html，让用户可以在网页中填写新的联系人的信息：

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="format-detection" content="telephone=no" />
<meta name="msapplication-tap-highlight" content="no" />
<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width" />
<meta http-equiv="Content-Security-Policy" content="default-src * 'unsafe-inline'; style-src 'self' 'unsafe-inline'; media-src *" />
<title>Contacts</title>
<style type="text/css">
html,body{padding:0px;margin:0px;height:100%;overflow:hidden;}
.container{height:100%;overflow-y:auto;}
#divLst > div{padding:18px 5px;border-bottom:1px solid #444;position:relative;}
#divLst > div > .right{position:absolute;right:3px;top:10px;bottom:0px;line-height:100%;}
#divNew{border:1px solid #be9898;box-sizing:border-box;overflow:hidden;background-color:#ddd;height:0px;}
</style>
</head>
<body>
<div class="container">
<div>
<button id="btnNew">新建联系人</button>
<div id="divNew">
姓名：<input id="txtName" />
<br />
电话：<input id="txtPhone" type="number" />
<br />
<button id="btnSubmit">提交</button>
<button id="btnCancel">取消</button>
</div>
</div>
<div id="divLst"></div>
</div>
<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript" src="js/index.js"></script>
<script type="text/javascript">
app.initialize();
</script>
</body>
</html>

然后，修改 index.js，在 onDeviceReady 方法中加入以下代码：

var btnNew = document.getElementById('btnNew'),
divNew = document.getElementById('divNew'),
txtName = document.getElementById('txtName'),
txtPhone = document.getElementById('txtPhone'),
btnSubmit = document.getElementById('btnSubmit'),
btnCancel = document.getElementById('btnCancel');
// 点击“新建联系人”按钮后，将让用户填写联系人信息的面板展示出来
btnNew.addEventListener('click', function () {
this.disabled = 'disabled';
divNew.style.height = 'auto';
}, false);
// 点击“取消”按钮后，将填写联系人信息的面板收隐藏
btnCancel.addEventListener('click', function () {
btnNew.disabled = '';
txtName.value = txtPhone.value = '';
divNew.style.height = '0px';
}, false);
// 点击“提交”按钮后，创建联系人信息，并将其写入手机的通讯录中
btnSubmit.addEventListener('click', function () {
var name = txtName.value, phone = txtPhone.value;
if (name && phone) {
// 这里仅仅是创建了一个联系人的数据（Contact类的实例），并没有保存到通讯录中
var contact = navigator.contacts.create({
displayName: name,
phoneNumbers: [{
type: 'mobile',
value: phone
}]
});
// 将新建的联系人信息保存到通讯录中
contact.save(function () { // 保存成功后执行
createItem(contact); // 将新建的联系人信息显示到我们页面中的联系人列表中
btnCancel.click(); // 触发“取消”按钮的点击事件，将填写联系人信息的面板隐藏
}, function (err) { // 保存失败后执行
alert('发生错误了！' + err);
});
}
}, false);

三、删除联系人

现在，为我们的联系人列表添加一个“删除”按钮。

我们当然是根据联系人的ID来删除，因为ID是联系人的唯一标识符。因此，在获取联系人列表时，需给 find 方法的第一个参数中加上“id”字段：

navigator.contacts.find(['id', 'displayName', 'phoneNumbers'], .....)

然后，修改 createItem 方法：

var createItem = function (contact) {
var div = document.createElement('div');
divLst.insertBefore(div, divLst.children[0]);
var phone = contact.phoneNumbers[0];
if (phone) {
phone = phone.value;
}
div.innerHTML = contact.displayName + '（' + phone + '）';
var spanRight = document.createElement('span');
div.appendChild(spanRight);
spanRight.className = 'right';
var btnDel = document.createElement('button'); // 在网页上联系人列表中每一个联系人的后面添加一个“删除”按钮
spanRight.appendChild(btnDel);
btnDel.innerHTML = 'Delete';
// 给“删除”按钮绑定 click 事件
btnDel.addEventListener('click', function () {
// 依据 id 字段查找出要删除的联系人。
// 因为“删除联系人”的方法是在 Contact 对象上，因此我们必须先获得要被删除的联系人的 Contact 对象。
var options_id = new ContactFindOptions();
options_id.filter = contact.id;
navigator.contacts.find(['id'], function (items) {
if (items.length > 0) {
// items 是一个数组，最匹配筛选条件的（即和我们传入的 id 完全相等的）肯定是“第0个”。
// items[0] 是一个 Contact 对象的实例，它有一个 remove 方法，将自己从手机的通讯录中移除。
items[0].remove(function () { // 移除成功后执行此方法
divLst.removeChild(div); // 当选定的联系人从通讯录中成功移除后，也将网页中联系人列表中相对象的元素移除
}, function (err) { // 移除失败后执行此方法
alert('删除失败。' + err);
});
}
}, function (err) {
alert('发生错误了。' + err);
}, options_id);
contact.remove(function () { // 移除成功后执行此方法
divLst.removeChild(div); // 当选定的联系人从通讯录中成功移除后，也将网页中联系人列表中相对象的元素移除
}, function (err) { // 移除失败后执行此方法
alert('删除失败。' + err);
});
}, false);
};

更多....

参考文档：http://cordova.apache.org/docs/en/latest/reference/cordova-plugin-contacts/index.html

最后，来个广告

若你觉得此文不错，请分享，若认为尚需改进，请点讚。

结束语

在不同的设备中 Contact 对象包含的值可能会有所不同，例如在有些版本的 iPhone 中，联系人的名字就不是 displayName。
另外，某些版本的 iPhone 也不支持使用 ID 查询联系人。
期望cordova在以后的版本中能够减少这种差异。
手把手教你玩转cordova（PhoneGap）- 目录

关于我：google.com/+YFCAO
由nooong.com提供空间支援。