地址簿管理

示例应用程序功能

ExtendedAddressBook 示例应用程序演示如何使用 Tizen 平台联系人、 消息和应用程序的 Api。 它还使用的筛选器 (属性和 CompositeFilter) 提供的 Tizen 设备 API。

启动后,该应用程序显示存储在手机中的通讯簿中,按第一名属性中的所有联系人的列表。 提供选项来选择筛选器类型 ("名字"、"姓氏"或"手机"),在搜索栏中输入一个字符串。 如果在搜索栏中输入一个字符串,则应用程序将筛选列表中的联系人显示,基于搜索字符串和选定的筛选器类型。 在列表中的每个元素被注册来处理的 'swiperight' 和 'swipeleft' 的事件。 'Swiperight' 事件启动应用程序服务电话应用程序,与所选号码作为参数。 'Swipeleft' 事件打开消息页面,,用户可以创建并将消息发送给一个或多个收件人。 在 index.html 文件,在 main.js 中的行为和融洽的样式中定义应用程序布局。

示例应用程序使用 jQuery 移动 1.2.0 框架,包括 jQuery 1.8.0 库。 示例应用程序已在 Tizen SDK 2.0.0a2 通过测试。

示例应用程序的屏幕截图

联系人

Tizen.contact 对象包含的信息,如电话号码、 电子邮件地址等。 并提供 API 功能读取、 创建、 删除和更新特定的地址簿中的联系人。 使用 getAddressBooks() 方法,它返回的通讯簿对象的数组,可获取通讯簿。 若要使用任何联系人功能,您必须声明中的 config.xml 文件的必要功能。

  1. 打开 config.xml 文件。
  2. 选择功能选项卡。
  3. 检查或添加功能: http://tizen.org/api/tizenhttp://tizen.org/api/contact

您也可以手动执行操作:

  1. 打开 config.xml 文件。
  2. 选择源选项卡。
  3. 将以下 <功能> 标记添加到文件::
"http://tizen.org/api/tizen"required="true"/>
"http://tizen.org/api/contact"required="true"/>

 

通讯簿对象

您可以添加、 更新或删除的联系人之前,您需要获取的通讯簿对象的实例。 示例应用程序使用下面的方法获取默认地址簿:

gAddressbook = tizen.contact.getDefaultAddressBook();

一旦您检索默认的通讯簿,就可以获取联系人。

 

获取联系人

FetchAllContacts() 函数检索使用通讯簿对象的 find() 方法的所有联系人。 您需要提供成功回调的 find() 方法,和(可选)错误回调,筛选和排序方式:

gAddressbook.find(onContactFindSuccess, onError, phoneFilter, sortingMode);

在此示例应用程序 tizen。SortMode 和 tizen。使用属性的对象。 tizen。SortMode 是一个通用的界面,用于排序查询的数据。 tizen。属性是 tizen 之一。AbstractFilter 的子类型和代表一个筛选器基于对象的属性。

  • 如果筛选器通过包含有效的值,只有这些联系人通讯簿中匹配的筛选条件将返回 successCallback。
  • 如果筛选器包含任何无效的值,或传递给任何筛选器,或者如果筛选器为空或未定义,则联系人项目的完整列表返回在 successCallback 中。
  • 如果没有联系人通讯簿中有或没有接触与筛选条件相匹配,将用一个空数组调用 successCallback。

在此示例应用程序中,只包含电话号码的联系人是必需的和他们应显示按字母顺序,所以我们 (phoneFilter 和 sortingMode) 的变量定义如下:  

var sortingMode = new tizen.SortMode('name.firstName', 'ASC');
var phoneFilter = new 	tizen.AttributeFilter('phoneNumbers.number','CONTAINS', '');

当找到满足这些条件的联系人项目时,将调用 onContactFindSuccess 回调。 此方法包含检索到的联系人列表中,可以添加到 中 index.html 元素:  

"listview"id="list"data-theme="d"data-divider-theme="d"class="ui-listview">

每个列表中的项是以这种方式 (main.js) 创建的:    

var str = '';
str += '
  • '
    + ((contacts[i].name == null) ? "" : (value = contacts[i].name.firstName) ? value : "")
    + ' '
    + ((contacts[i].name == null) ? "" : (value = contacts[i].name.lastName) ? value : "")
    + ' ' + ''
    + ((value = contacts[i].phoneNumbers[0]) ? value.number : "")
    + '
  • ';

    使用筛选器

    FetchAllContacts() 方法返回所有包含电话号码的联系人。 在此示例应用程序中,核心功能之一是到筛选器基于用户选择的其他选项的联系人的可能性。 为此目的的示例应用程序使用 fetchContacts() 方法。 用户可以选择从以下筛选器选项:  

    可用的筛选器

    这些按钮切换有点二进制数中 (初始价值: 000)。 选择名字按钮更改第一位为 1 (001),取消选择 — — 为 0。 姓氏 — — 更改第二位,电话 — — 第三位。 结果数字的十进制值保存为变量的筛选器。 根据筛选器的值,设置合适的 filterMode (稍后介绍)。 TranslateApiExceptionMethod: Translate()Message: The Azure Market Place Translator Subscription associated with the request credentials has zero balance.message id=3631.V2_Rest.Translate.166A7DA7 第三个被用来检查一个联系人的属性值是否与用户在搜索栏中输入的字符串相匹配。 最后一个用来检查是否联系人项目包含一个电话号码。    

    var firstNameFilter =
    new tizen.AttributeFilter('name.firstName','CONTAINS', attrName);
    var lastNameFilter =
    new tizen.AttributeFilter('name.lastName','CONTAINS', attrName);
    var phoneFilter =
         new tizen.AttributeFilter('phoneNumbers.number','CONTAINS', attrName);
    var includePhone =
    new tizen.AttributeFilter('phoneNumbers.number','CONTAINS', '');

    属性是一个筛选器,可以被用来搜索项目基于对象的属性。 如果没有第三个参数定义,该筛选器用于匹配已定义的属性 (作为"存在"标志相同) 的所有对象,否则,它将用来查找其属性与给定的值相匹配的对象。 第二个参数是 FilterMatchFlag。 此属性的所有可用值:  

    enum FilterMatchFlag { "EXACTLY", "FULLSTRING", "CONTAINS", "STARTSWITH", "ENDSWITH", "EXISTS" };

    默认情况下,它设置为"完全"。 根据用户所选的选项,该示例应用程序使用不同的筛选器组合。  

    mode = filter;
    
    switch (mode) {
    case 0:
        var filterMode = includePhone;
        break;
    
    case 1:
        var filterMode = new tizen.CompositeFilter("INTERSECTION", [firstNameFilter, includePhone ]);
        break;
    
    case 2:
        var filterMode = new tizen.CompositeFilter("INTERSECTION", [lastNameFilter, includePhone ]);
        break;
    
    case 3: {
        var tmp = new tizen.CompositeFilter("UNION", [firstNameFilter, lastNameFilter ]);
        var filterMode = new tizen.CompositeFilter("INTERSECTION", [tmp, includePhone ]);
    }
        break;
    
    case 4:
        var filterMode = phoneFilter;
        break;
    
    case 5: {
        var tmp = new tizen.CompositeFilter("UNION", [firstNameFilter, phoneFilter ]);
        var filterMode = new tizen.CompositeFilter("INTERSECTION", [tmp, includePhone ]);
    }
        break;
    
    case 6: {
        var tmp = new tizen.CompositeFilter("UNION", [lastNameFilter, phoneFilter ]);
        var filterMode = new tizen.CompositeFilter("INTERSECTION", [tmp, includePhone ]);
    }
        break;
    
    case 7: {
        var tmp = new tizen.CompositeFilter("UNION", [firstNameFilter, lastNameFilter, phoneFilter ]);
        var filterMode = new tizen.CompositeFilter("INTERSECTION", [tmp, includePhone ]);
    }
        break;
    
    default:
        break;
    }

    CompositeFilter 表示筛选器的组合。 有 2 种类型的此筛选器:

    • 联盟-用来与任何它所包括的筛选条件匹配的筛选器对象,它等效于逻辑或。
    var tmp = new tizen.CompositeFilter("UNION", [firstNameFilter, phoneFilter ]);
    • 路口-用于筛选它还包括所有的筛选条件相匹配的对象,这是相当于逻辑 and。
    var filterMode = new tizen.CompositeFilter("INTERSECTION", [tmp, includePhone ]);

    第二个参数包含在复合筛选器中使用的筛选器的列表。 示例应用程序使用一个联盟的筛选器,以结合用户,所选的选项和交叉筛选器,以确保显示每个联系人包含电话号码。 CompositeFilter 和属性,都是亚型的 AbstractFilter,这是一个通用的界面,使用的不同类型的对象的筛选器。 您永远不应直接使用此基接口。

    消息

    该消息 API 提供了可用的邮件服务中检索和发送 SMS 消息,这此示例应用程序的重要组成部分等功能的访问。 若要使用任何一种消息传递功能,您必须声明在 config.xml 文件中必要的功能:

    1. 打开 config.xml 文件。
    2. 选择功能选项卡。
    3. 检查或添加功能: http://tizen.org/api/tizenhttp://tizen.org/api/messaging.send

    邮件页面的结构是 index.html 文件中描述的。 主要内容是: 电话号码输入、 消息文本框和"发送"按钮。  

    "text" id="formPhone"/>
    "10"cols="20" id="formBody">
    "#" id="send" data-role="button" data-inline="true" data-theme="d" class="rightPos">Send 

    此外, 消息发送状态和其他操作的结果有关的日志记录信息,并添加标记:

    "logDiv">

     

    检索消息服务

    点击"发送"按钮触发器 sendSms() 方法。  

        $("#send").unbind().click(function(event) {
            sendSms();
        });

    SendSms() 方法的主要目的是要获得短信服务。 这是使用 tizen.messaging.getMessageServices() 方法:  

    tizen.messaging.getMessageServices("messaging.sms", serviceList, onError);

    第一个参数指定要检索的服务的类型,第二个是检索 SMS 服务时调用的回调函数和第三个是可选的回调函数,如果发生错误,则调用。

     

    创建消息

    Tizen.messaging.getMessageServices() 成功,如果调用成功回调函数 (serviceList) 和返回的 MessageService 对象 (服务) 的数组,可以使用来创建和发送邮件。 在此方法读取 formBody 元素的值:  

    function serviceList(services) { 
    
        var body = $("#formBody").val();

    因为您不希望用户能够发送空的消息,如果是空的消息区域显示相关的弹出消息:  

    view.showPopup("Message cannot be empty.");

    视图是一个模块负责上显示自定义 jQueryMobile 的 UI 元素。 它包括的 showPopup() 方法,其中显示一个弹出式消息。 下一步是创建要发送的消息。 SMS 服务 (MessageServiceTag) 的第一个参数是"messaging.sms"和第二个是一个新的 MessageInit 对象。 MessageInit 允许您指定多个可选的消息属性时创建消息,但此示例应用程序使用这些属性中只有两个:

    • DOMString plainBody ;

    消息正文的纯文本表示形式。

    • DOMString [] ;

    一条消息的目标地址 (或电话号码)。  

        msg = new tizen.Message("messaging.sms", {
            plainBody : body,
            to : [ phone ]
        });

    GetPhoneNumber() 方法返回的示例应用程序中的电话号码。  

    function getPhoneNumber(p) {
        var phoneNr = "";
        var contact = gAddressbook.get(receivers[p]);
    
        if (typeof(contact.phoneNumbers[0]) !== 'undefined') {
            if (contact.phoneNumbers[0]['number'][0] != '+')
                phoneNr += "+48";
    
            phoneNr += (contact.phoneNumbers[0]['number']);
        }
    
        return phoneNr;
    }

    GAddressbook.get(receivers[p]) 返回具有给定标识符的联系人 (在此用例的标识符 = receivers[p])。 接收机 [] 是联系人的 id 的数组。  

    var receivers = [];

    成功地创建一封邮件后,该示例应用程序可以发送它。 为此,sendMessage() 调用方法时,以前创建消息对象 (msg) 作为参数。 此外,您可以注册两个回调函数,被触发后消息发送已成功或失败。  

    services[0].sendMessage(msg, messageSent, messageFailed);
    /**
     * Success Callback for function sendMessage()
     */
    function messageSent() {
        logMsg("The SMS has been sent");
    }
    
    /**
     * Error Callback for function sendMessage()
     */
    function messageFailed(error) {
        logMsg("The SMS could not be sent: " + error.message);
    }

    您可以使用简单的测井方法在先前定义的 logDiv 标签中显示消息:  

    function logMsg(message) {
        var line = $('
    
    ');
        line.html(message);
        $("#logDiv").append(line);
    }

     

    刷卡事件

    在列表中的每个元素是已注册的两个事件: 'swiperight' 和 'swipeleft'。 'Swiperight',对每次触发事件附加处理程序之后调用以下回调函数:  

    elem.unbind('swiperight').bind('swiperight', function(e) {
        /**
         * On "swiperight" event call to selected person
         */
        receivers.length = [];
        receivers[0] = $(this).data("id");
    
        callTo();
    });

    这将清除联系人 id 的数组并调用 callTo() 方法,它将在稍后介绍。 以类似的方式,附加处理程序的联系人列表中的所有元素的 'swipeleft' 事件。 每次事件时触发回调函数被调用:  

    $(str).unbind('swipeleft').bind('swipeleft', function(e) {
        /**
         * On "swipeleft" event send message to selected person
         */
        receivers.length = [];
        receivers[0] = $(this).data("id");
    
        setMsgPage();
        $.mobile.changePage("#msgpage");
    
    });

    此清除联系人 id 的数组、 设置的第一个元素作为选的人 id、 调用 setMsgPage() 方法并更改为邮件页面。 SetMsgPage() 方法设置的属性的邮件页面。  

    function setMsgPage() {
        var number = "";
    
        if (!page)
            page = 1;
        else {
            receivers.length = 0;
            for ( var i = 0; i < tmpReceivers.length; i++)
                receivers[i] = tmpReceivers[i];
        }
    
        for ( var i = 0; i < receivers.length; i++) {
            if (getPhoneNumber(i)) {
                number += getPhoneNumber(i);
                number += ", ";
            }
            else { // If the contact doesn't have proper phone number contact.phoneNumbers[0] is undefined
                view.showPopup("phoneNumbers[0] for receiver (id " + receivers[i] +") is undefined!");
            }
        }
    
        $("#formPhone").attr("value", number);
        $("#formBody").attr("value", "");
        $("#logDiv").empty();
    
    }

    可以看出在 setMsgPage() 方法中,可以向多个收件人发送邮件。

     

    多个收件人

    消息的属性之一是电话号码。 此示例应用程序允许用户添加多个收件人。 要做到这一点,与联系人列表中的第二页显示用户的选择。 此页面的结构是 index.html 文件中描述的。 主要内容是: 添加/更改按钮、 搜索输入和所有联系人的列表。  

    "" id="add-change" data-role="button" data-icon="plus" data-iconpos="left" data-theme="d" class="rightPos">Add/Change
    
      "search" name="search-receiver" id="search-receiver" value="" data-theme="d">
      
      "listview-add-more" data-role="listview" id="listAddRec" data-theme="d" data-divider-theme="d">

    每个列表中的项目创建方式如下:

    str += '
  • ' + ''
    + ((contacts[i].name == null) ? "" : (value = contacts[i].name.firstName) ? value : "")
    + ' '
    + ((contacts[i].name == null) ? "" : (value = contacts[i].name.lastName) ? value : "")
    + ' ' + ((value = contacts[i].phoneNumbers[0]) ? value.number : "")
    + '
  • ';

    +'';

    IsChecked(index) 方法将检查是否联系人的 id 已在邮件收件人列表中所以列表 '检查' 可以适当地设置属性。  

    function isChecked(index) {
        for ( var i = 0; i < tmpReceivers.length; i++) {
            if (index == receivers[i]) {
                return true;
            }
        }
        return false;
    }

    从联系人列表中选择任何元素调用以下:

    $("#listAddRec").delegate("input", "change", function() {
        /**
         * Adding receivers of message
         */
        if (tmpReceivers.length > 10)
            view.showPopup("10 contacts available only. Uncheck some contacts.");
    
        var checkedNr = $(this).data("id");
        if ($(this).prop("checked")) {
            var wsk = 0;
            for ( var i = 0; i < tmpReceivers.length; i++) {
                if (tmpReceivers[i] === checkedNr)
                    wsk = 1;
            }
            (!wsk) ? tmpReceivers.push(checkedNr) : wsk = 0;
        } else {
            var idx = -1;
            for ( var i = 0; i < tmpReceivers.length; i++) {
                if (tmpReceivers[i] === checkedNr)
                    idx = i;
            }
            tmpReceivers.splice(idx, 1);
        }
    });

     

    应用程序

    该应用程序 API 提供了用于启动其他应用程序的功能。 通过指定它们的标识符,或通过指定应由启动的应用程序执行什么操作,您可以启动其他应用程序。 一个字符串,标识操作。 包含标准操作说明的表可以在文档中找到。 要使用的任何应用程序的功能,您必须声明中的 config.xml 文件的必要功能。 在此示例中需要 tizen 和应用程序功能。

    1. 打开 config.xml 文件。
    2. 选择功能选项卡。
    3. 检查或添加功能: http://tizen.org/api/tizenhttp://tizen.org/api/application.launch

     

    启动服务

    如果您希望您的应用程序使用提供的另一个应用程序的常见功能,您可以请求则系统将启动的应用程序提供了您所需的功能。 推出一项服务的功能被提供的 tizen.application.launchService() 方法。

    tizen.application.launchService(service, 'org.tizen.phone', onSuccess, onError, null);

    它具有以下参数:

    • ApplicationService 服务,

    描述服务详细信息的数据结构通过下列构建:

    var service = new tizen.ApplicationService('http://tizen.org/appcontrol/operation/dial', number, null);

    界面的操作,包括 URI、 MIME 类型、 ApplicationService 和数据 (URI 和 MIME 是可选参数)。 它描述要由另一个应用程序执行的操作。 当系统获取的服务启动请求时,它找到的应用程序提供所需的服务,并启动它。 此示例应用程序中的此功能用于启动拨号程序应用程序来拨打电话。 所需的操作参数是 'http://tizen.org/appcontrol/operation/dial' 和没有 MIME 类型参数。

    • ApplicationId 吗?gdb

    这是要启动的应用程序的标识符。 如果 id 为空或未指定,系统将尝试查找所请求的服务为要启动的应用程序。 此示例应用程序中的 id 是 org.tizen.phone。

    • 的 SuccessCallback 吗?successCallback,

    调用成功结束时调用。

    • 的 ErrorCallback 吗?errorCallback,

    当发生错误时调用。

    • 可选的 ApplicationServiceDataArrayReplyCallback 吗?replyCallback

    当应用程序获取结果回从启动的应用程序时调用。

     

    退出应用程序

    如示例应用程序包含一个退出按钮,它包含要退出该应用程序的功能。 若要提供它,必须在 config.xml 文件中添加 application.read 功能。  

    "http://tizen.org/api/application.read" required="true"/>

    将退出按钮添加到 index.html:  

    "" id="close" data-role="button" data-icon="delete" data-theme="d" data-iconpos="notext">Close

    在 main.js 中:  

    $("#close").unbind().click(function(event) {
        tizen.application.exit();
    });

     

    摘要。

    使用本文中介绍的 Api,您可以开发具有以下功能的应用程序: 发送和接收 SMS 消息,启动其他应用程序和服务,打电话到所选的人、 添加/删除/修改联系人和其他许多人。

    文件附件: