BlackBerry Widget 项目经验总结

项目总结

一、配置文件使用说明：

新建web/widget工程以后会自动生成一个工程配置文件config.xml，该文件包含了整个应用程序的关键配置信息，应用程序是否正常启动，直接取决于该文件参数的正确设置。在该文件中，我们必须提前声明：

domains（访问域）：也就是本应用程序需要访问到的网络地址（域）。

所有在该应用程序中访问到的网址的访问域都必须提前在此声明，如果没有提前声明，则该网址将无法访问到（后面将介绍一种无需声明便可访问URL的方法）。

例如：<access subdomains="true" uri="http://img.21cbh.com"/>

features（特征）：也就是本应用程序用到的web/widget系统API的访问权限。如果没有提前声明，则该类API将无法调用。（特殊不需要声明的API除外）

例如：<feature id="blackberry.app" required="true" version="1.0.0.0"/>

以上参数设置可以在“widget Permissions”选项卡页面点击选择添加，也可以在代码页面中使用代码添加。以上设置非常关键，直接决定应用是否可以运行，提醒用户特别注意。

在配置文件中，我们也可以设置应用程序名称，版本号，加载页面参数（背景图标，背景色等），程序图标，首页，作者信息等等。

该配置文件是在运行应用时统一提前加载，所以以上配置信息必须在运行应用前一次性统一完成。

二、各个功能实现：

 

黑莓web/widget主要采用html + css + JavaScript的技术组成形式。html主要负责页面布局，元素、控件的编写，结合css进行布局控制、样式渲染，采用JavaScript调用系统API编写并实现菜单，联网，数据存储等一系列后台功能以及数据处理方法。页面文件类型为html文件。

 

1.菜单实现：

在黑莓手机上点击menu弹出菜单，点击菜单项可以启动相应的应用程序或者跳转到特定界面，该菜单效果在web/widget应用上实现步骤如下：

1>调用blackberry.ui.menu.MenuItem ( isSeparator : Boolean ,  ordinal : Number ,  [caption : String ] ,  [callback : OnClick ] )

创建菜单项，参数：isSeparator设置为false时，菜单项表现为通常的可视菜单项，可以进行点击触发事件，设置为true时候菜单项将会以分割线方式存在；ordinal代表菜单项在菜单中排列顺序，值越大，菜单项排列越靠下；caption为菜单项展示给用户的文字描述；callback为点击菜单项所触发的回调函数，可启动其他应用程序或者跳转到特定页面window.location.href = "/index.html"。

2>调用blackberry.ui.menu.addMenuItem(item : blackberry.ui.

menu.MenuItem)方法将新创建的菜单项添加到菜单。所添加的菜单项依据ordinal参数值排序。

另外blackberry.ui.menu.getMenuItems ()可以获取所有菜单项集合；blackberry.ui.menu.removeMenuItem ( item : blackberry.ui.menu.

MenuItem )实现移除指定菜单项的功能，直接调用API：blackberry.ui.menu.clearMenuItems();即可清空菜单项。

2.联网实现：

           黑莓web/widget连接网络采用google.gears.httpRequest类实现，该API实现了W3C XmlHttpRequest的一个子集，提供了多种XmlHttpRequest的特性，并希望未来能有能力将response封装成XML DOM对象，并同步发送request。具体联网获取数据的步骤如下：

调用var request = google.gears.factory.create('beta.httprequest')，该API创建并返回一个beta.httprequest的Gears对象，接下来调用request.open ( method : String ,  method : String )设置访问方式和访问地址，并进行访问操作。 该API创建一个指定类的Gears对象，第一个method可以是“GET”，“POST”，“HEAD”或者是其他HTTP方法。第二个method：一个URL参数，可以是相对的也可以是绝对的，但必须是来自同一个源。接下来调用以下API获取应答数据，并对数据进行处理操作：

request.onreadystatechange = function() {

          if (request.readyState == 4) {

                    func(request.responseText); //在此处调用数据处理函数

            }

          request.send();

};

其中onreadystatechange为事件处理函数，每当状态改变或者当请求处

于交互状态，重复获取新的可用应答数据时触发；readyState为状态变量，其获取值不同代表不同的联网状态：0 –为初始化状态, 1 – 链接打开, 2 – 发送请求, 3 - 联网交互状态, 4 – 交互完成状态。该变量区别于status变量，后者是用来返回连接状态（数字），(404 for "Not Found" or 200 for "OK").该属性在请求处于交互或者完成状态时可读，用于判断是否找到网络地址或者是否联网成功；request.responseText为返回的应答数据字符串，只有当请求处于交互或者完成状态时可读func(request.responseText)是自定义的数据处理方法；request .send ( [postData : Object ] ) 发送请求，postData是string或者Blob类型数据，作为post或者put请求数据体，该参数为可选参数。

注意事项：URL地址必须在配置文件中事先声明，否则将无法访问。

3.本地数据存储实现：

通过JavaScript调用web/widget API可以创建本地数据库，创建表，并

进行一系列增上改查等数据库操作，该API提供了持续保存用户和应用程序数据的客户端数据库，该数据库创建在SQLite之上。数据库创建路径：

/home/user/appdata/rim/gears/folder或者/BlackBerry/system/appdata/rim/gears/ folder。数据库具体操作如下：

google.gears.factory.create('beta.database');该API创建并返回数据库对象，然后调用open ( name : String ) 打开已存在的数据库，如果该数据库不存在，自动创建一个名为name的数据库。

数据库创建好了以后，我们可以调用ResultSet   execute ( sqlStatement : String ,  argArray : String )，该API可执行sqlStatement 数据库操作语句，参数值来自argArray，结果返回ResultSet类型。因此，我们可以通过该API执行建表，增删改查等一系列数据库操作。

具体的SQL操作：

创建表：create table if not exists tableName (Id int,JsonData text)

添加：insert into tableName values (?,?)，其中问号所代表参数从argArray 获得。

删除：delete from tableName where Id =ID

修改：update tableName set JsonData = "'s'" where Id = 1

查询：select * from tableName

删除表：drop table tableName

注意事项：当程序不需要database、ResultSet打开时候，必须明确关闭对象（.close()方法），否则有可能导致内存泄露。

其中数据返回集合ResultSet隶属于google.gears.database.ResultSet类，该类对象是数据库执行语句Database.execute()的返回，包含了SQL语句执行的结果，ResultSet只承装一次SQL的返回结果，而后对数据库的改变不会对其产生影响。

通过代码操作，可以对返回集合ResultSet进行迭代操作，从而获取并处理每一个数据项，其中用到的API包括：

void next()：指向下一行数据。

boolean   isValidRow():判断该行数据是否有效。

Object   field ( fieldIndex : int ) ：获取指定行数据对象。

int   fieldCount ( ) ：返回ResultSet的行数。

4.代码启动系统浏览器实现：

在开发黑莓web/widget应用程序时会出现这样的情况，因为这类应用是与网络息息相关的，在运行过程中往往会随机地动态访问一些网址，而这些网址往往事先无法预测，也就无法注册在配置文件中，那么，怎样访问配置文件中没有的网络地址呢？答案就是启动系统浏览器。

这就应用到了blackberry.invoke.BrowserArguments类API，该类API属于blackberry.invoke。

blackberry.invoke类对象提供了与黑莓智能手机上其他程序交互的方法。其中invoke()方法允许用户传参数到指定的目标应用，参数的类型可以是：AddressBookArguments, CalendarArguments, MapsArguments, MemoArguments, MessageArguments, PhoneArguments, SearchArguments, TaskArguments, CameraArguments, BrowserArguments, and JavaArguments.

首先，创建BrowserArguments对象，该对象作为参数传递给invoke()方法，从而启动系统浏览器，var args = new blackberry.invoke.

BrowserArguments('http://www.blackberry.com')。

           其次，调用系统API：blackberry.invoke.invoke ( appType : Number , 

[args : object ] )启动浏览器。参数介绍：appTpye代表了需要启动的应用程序类型，这里我们使用blackberry.invoke.APP_BROWSER，也就是浏览器类型；args 该参数对象包含了需要启动应用程序所必须的参数。

注意事项：应用该API必须声明API访问权限，如下：

<feature id="blackberry.invoke" version="1.0.0"/>
<feature id="blackberry.invoke.BrowserArguments" version="1.0.0"/>
<feature id="blackberry.identity" version="1.0.0"/>