"这篇文档是关于PhoneGap API的第六部分,专注于Contacts(通讯录)功能。主要内容包括如何创建、查找和操作设备上的联系人数据。"
PhoneGap 是一个开源框架,它允许开发者使用HTML、CSS和JavaScript来构建跨平台的移动应用。在PhoneGap中,Contacts API 提供了与设备本地联系人数据库交互的能力,使得开发者可以在应用程序中管理用户的联系人信息。此API适用于iOS、Android和BlackBerryWebWorks(操作系统5.0及以上版本)等平台。
Contacts API 的主要方法:
1. contacts.create - 这个方法用于创建一个新的联系人对象。它是一个同步函数,接收一个属性对象作为参数,返回一个新的Contact对象。这个新对象不会立即保存到设备的联系人数据库中,除非调用 `contact.save()` 方法。例如:
```javascript
var myContact = navigator.service.contacts.create({"displayName": "Test User"});
```
主要对象和属性:
2. Contact - 表示一个联系人的对象,包含了诸如名字、电话号码、电子邮件地址等信息。Contact对象包含多个子属性,如ContactName、ContactField等。
3. ContactName - 包含联系人的名、姓、全名等信息。
4. ContactField - 用于表示联系人的单个字段,如电话号码、电子邮件地址等。每个ContactField都有一个类型(如'phone'或'email')和一个值。
5. ContactAddress - 描述联系人的地址,包含街道、城市、国家等信息。
6. ContactOrganization - 代表联系人在某个组织的职位和相关信息。
7. ContactFindOptions - 在查找联系人时使用的选项,可以设置过滤条件和排序方式。
8. contactSuccess 和 contactError - 这两个分别是成功执行操作和出现错误时的回调函数。在查找联系人时,`contactSuccess` 接收一个Contact数组作为参数,而`contactError`则在操作失败时被调用。
示例代码:
```html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待PhoneGap加载
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap准备就绪
//
function onDeviceReady() {
// 创建一个新联系人
var myContact = navigator.service.contacts.create({"displayName": "Test User"});
// 保存联系人到设备
myContact.save(onSaveSuccess, onSaveError);
}
function onSaveSuccess(contact) {
console.log("Contact saved successfully.");
}
function onSaveError(error) {
console.log("Error saving contact: " + error.code);
}
</script>
</head>
<body>
<!-- 页面内容 -->
</body>
</html>
```
以上代码展示了如何在PhoneGap应用中创建一个新的联系人,并尝试将其保存到设备上。如果保存成功,将在控制台显示一条消息;如果出错,则会打印错误代码。
通过Contacts API,开发者可以实现各种功能,如添加、更新、删除联系人,以及搜索和过滤联系人列表,以适应不同应用场景的需求。这使得PhoneGap成为构建涉及用户联系人数据的移动应用时的一个强大工具。