SCMLife.com

 找回密码
 立即注册

QQ登录

只需一步,快速开始

扫一扫,访问微社区

查看: 3491|回复: 1

[推荐] Worklight 的客户端 API 介绍

[复制链接]
发表于 2013-2-17 15:03:05 | 显示全部楼层 |阅读模式
本帖最后由 技术狂人 于 2013-2-17 15:08 编辑 9 t, Z* b9 E4 }5 y- c2 E

' [( Q$ u3 D6 E6 E' I5 M; {# b客户端 API 的作用
2 R( \2 `* R2 j+ E, L5 |. V在混合模式下开发的手机端应用,需要处理的一个主要问题就是:通过一种合理的语言,获取本地的信息(比如手机的类型,操作系统的版本,硬件的资源)和服务器端的信息(比如各种数据,网络的连接情况)。同时,能够通过一种合理的语言,创建一些公共的控件,比如对话框,这样就可以减少在不同手机环境下,代码的开发量。
& m, d$ N) w7 L* r) ?# U! k* _从广义的角度来讲,Worklight 混合模式的客户端 API 分为三个层次:普通的 JavaScript 框架,例如 jQuery mobile,dojo mobile,prototype 等等,它们主要负责和 HTML,CSS 的互动,来实现丰富的页面效果;基于 phonegap 的 JavaScript 框架提供了和手机本地硬件的交互能力,通过它能够很好的调用本地的一些资源;Worklight 开发的客户端 API 则提供了基于 Worklight 整体框架的 JavaScript 功能,比如常规的调用 adapter。 的方法,创建各种通用控件的方法,甚至还可以通过类似反射机制,和本地的代码进行交互的方法。这些功能为创建强大的混合模式应用提供了工具。3 J$ E5 v1 T9 F9 y( ?" i  r

* ~1 z# h2 e. ]# D: b+ I% `$ {: y表 1. 客户端的不同选择7 v% O6 f: s# b( r& k
功能需求描述示例技术选择
标准的界面和图形表格、图片、列表标准的 HTML 页面技术,附加第三方 JavaScript 库
本地化控件对话框、菜单、标签栏Worklight 的客户端 API
对于不同客户端的优化在 iOS 情况下对于 iPhone 和 iPad 的适应在使用标准页面技术情况下,创建 Worklight 的环境
适应不同的设备环境同一应用提供的不同皮肤使用 Worklight 的皮肤设置
调用设备本地功能照相机、GPS、重力感应、名片夹、媒体播放使用 PhoneGap 的 JavaScript 库
第三方本地库的协作调用加密之后的本地库编写 PhoneGap 的插件
应用中集成 web 和本地 UI条形码检测使用 Worklight 的 API 调用本地的功能,实现 native 和 web 页面之间的共享
开发完全本地应用将原有项目导入到 Worklight 平台使用 Worklight 的本地 SDK

' i: X5 C- Z% y5 xWorklight 的客户端 API 提供了如下的功能:* w; O! n! K) B
  • 初始化和重启应用的功能:在启动应用时需要设置一些默认的参数,比较常用的是 showLogger,用于在开发阶段显示日志信息;timeout 用于定义连接时间的上限;heartBeatIntervalInSecs 用于定义在应用空闲时,多久连接一次服务器,测试连接状态。重启应用的功能为失败恢复提供了一种方式,虽然测试良好的应用,应该大大减少应用崩溃的几率,但是在特殊情况下,应用还是可能因为一些情况而崩溃,提供应用重启功能是一种良好的补充方式。
  • 管理认证 session 的功能:在有认证系统的条件下,应用和服务器之间的交互需要以认证信息作为条件,常用的有用户的登录、登出;用户信息的获取和更新;用户登录状态的判定。
  • 获取和更新外部信息系统的功能:应用的基本作用,就是从不同系统获取数据,然后展现在手机端,利用客户端 API,可以完成这项工作。此外,应用可能需要访问其他的手机 web 网站,在不同手机系统中,打开网页的实现并不相同,所以利用 Worklight 提供的 API 可以达到相同的效果。
  • 能够在多个 session 中获取和储存用户偏好设置的功能:用户在应用中会设定个人偏好,比如微博中就可以设定更新的排列方式,默认展现的群组,这些数据可以存在服务器端,但是在运行时,就需要通过个人偏好去管理,实现运行时个性化定制。
  • 将应用信息进行多语言支持的功能:多语言支持永远是一个好的应用需要思考的方面,如何提供不同的语言版本,如何管理,如何获取手机本地的语言信息,Worklight 提供的接口帮助实现这些功能。
  • 获取用户手机的环境信息,并且定义不同接口的功能:这里所指的手机环境更偏向于操作系统级别。比如手机的系统是 iOS 还是 Android,手机的屏幕大小,系统的版本,在这些细小的差别上提供不同的实现,更能体现应用的精致。
  • 将特定的日志存入数据库用于审计和制作报表的功能:当应用部署上线后,用户的使用情况是很好的参考材料,发布方可以根据这些数据修改原有的应用。所以,Worklight 提供了相应的 API,用于记录用户的数据,并且生成报表。
  • 将调试信息写入日志窗口的功能:在初始化阶段设定了 showLogger 参数后,需要在一个固定的控制台输出日志,比如浏览器的控制台;手机中的日志文件;模拟器的日志窗口。这些不同的输出环境,Worklight 提供了统一的 API,只需要唯一的接口就可以实现,简化了日志输出的工作。
  • 动态读入页面和片段的能力:在混合模式下,数据的读入可能来自于新的 HTML 页面,也可能来自于某一个页面片段。动态的组织这些内容可以提供良好的导航功能,又简化系统的文件结构,可以将不同页面存入不同的文件中,便于开发和测试时候的管理、定位。
    ) g) ^+ {: p0 m' K) `  x' h8 w

7 ~- l5 u$ H* {; L

* N# u( X+ P2 j客户端 API 的分类
+ M" B. l" ]" K% g+ y0 ]6 `Worklight 将 API 分为四类:普通应用接口,Worklight 可以创建手机应用外,还可以创建桌面应用和 web 应用,普通接口在不同环境下均可使用。手机的功能函数和 UI 控件,这些接口完全为了手机设定,为了更方便的提供跨平台功能,Worklight 对于不同手机操作系统实现的相同功能进行抽取,制作了这部分内容。桌面和 web 小工具的方法,这些函数主要用于非手机端开发。参数传递机制,这部分内容是在调用其他三部分时被使用的,但是因为这个机制,调用 API 的功能显得很强大,可以实现各种参数的设置和回调,提高了软件的灵活性和可读性。所以在解释其他部分函数时,需要首先了解第四部分的内容。
1 R7 o6 K7 {. m7 E* k% CWorklight 方法的调用机制
3 ^* Y# O( A# }  K) _3 R; \" e在所有的异步调用中,都需要传递一个 options 对象给函数,这个对象有三个公共属性,对于所有的函数来说都会使用,它们分别是 onSuccess,onFailure,invocationContext,相应的格式如清单 1 所示:
& s8 C& l  M, E2 V4 ]6 }& X$ E! D, v% D% ~3 ~
清单 1. options 对象
# d, ?9 Y: t$ z" c
options = {
8 j: K" i! c4 Q onSuccess: success-handler-function (response), 1 K% L" i' ?4 c  @
onFailure: failure-handler-function (response), 9 {5 `2 |4 ]. Q; c
invocationContext: invocation-context 0 a$ M# \" E# r
};
7 l" F1 o4 v, w7 q2 ]. l+ X
属性 onSuccess 是一个回调函数,当异步调用成功时,这个函数被执行。参数 response 是一个对象,在不同的异步函数中内容不同,不过基本的参数包括两项:invocationContext 是传递过去的 options 中的内容;status 是异步调用的成功后返回的结果状态。: a  `6 Z% p7 D2 b( C* X# n: o
属性 onFailure 也是一个回调函数,当异步调用失败时(无论是客户端失败还是服务器端失败),这个函数被执行。参数 response 是一个对象,包括的基本参数四项,除了 invocationContext 和 status 外,还有 errorCode 和 errorMessage。第一项是在 Worklight 中已经定义的错误类型字段;第二项则是错误的具体信息,由服务器提供。+ D2 t& Y+ @/ O. ^& I
属性 invocationContext 是一个存放异步函数上下文信息的地方。当调用结果从服务器返回的时候,需要通过它来确认客户端调用的函数,完成回调的过程。: X4 [0 |% C0 ?+ N" O% x/ z5 o
当然这三个属性中的内容会因为调用函数的不同有差异,在具体用到相应函数时,可以通过查看相应函数的说明,了解内容的扩充情况,实现各自功能。
2 \, ]! ]( G8 ]( h9 V+ R" T& {

+ b- z* X. r, _9 q) p5 F  @. A  E' F" v; _& M( i4 z
客户端 API 的实现
' e% o7 O4 R/ p4 s为了展现 Worklight 客户端 API 的丰富功能,本文将通过一个实际的应用来描述它的作用。
6 a* A9 v+ {; i3 F在应用创建后(应用名称为:ClientAPIApp),对 ClientAPIApp.html 文件中的 WL.Client.init 函数进行修改,修改后的内容如清单 2 所示:4 I0 E0 M8 |8 \
; O7 w3 b7 Y9 F, p# ?" u
清单 2. Worklight 客户端初始化6 j9 Z* ^" K* p
WL.Client.init({showLogger: true, timeout: 10000, heartBeatIntervalInSecs: 60})

1 y( p4 F! q; {" a% [从代码中可以看到,程序启动后将自动启动日志系统;每六十秒和服务器进行一次连接,判定网络是否通顺;在获取外部系统内容时,最大的等待时间为 10 秒。在启动应用后,通过 preview 界面显示应用,然后等待六十秒,在浏览器的窗口可以看到如下日志:
: j+ R+ G6 R3 D: h; n% c4 \; W6 [( e3 f
图 1. 日志窗口
! `2 `0 h4 c: z) z
% C5 F0 Q+ s  X日志窗口的最后两行信息如下:4 d1 `! E  R( V, O
6 w. ]9 l: ]! O5 v
清单 2. 不同平台下心跳日志& ]& N  a, ^( ^: J- d1 P
浏览器1 e7 w$ C( D( W4 ?' T3 F
- Request [/apps/services/api/ClientAPIApp/common/0/heartbeat]
# |! z$ X4 k+ R: S9 }! p+ ?) V! V" ^& M. \. l- d, f8 [  M3 o
- response [/apps/services/api/ClientAPIApp/common/0/heartbeat] success:
+ N. q/ |( x5 w( u6 q% ^. N: i. _1 G0 u8 b" C/ L
Android 模拟器' q9 v# Z- f$ K& j/ W+ c: o( V
Request [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat] ; h3 E$ ^$ x& S; m
7 m. U4 x2 _, z
response [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat]
. Q  f, F5 w5 n0 h& M5 g' H4 A+ _ success:

# c7 t5 w' ]3 t创建 Android 的环境代码,并且在模拟器上运行,相应的内容将被打印在 Android 模拟器的日志系统中,这就说明在 Worklight 的日志系统中,相同的日志会根据不同的平台情况,被记录在不同地方。为了更好的说明这个问题,在本文的例子中,将在不同地方加入日志,并且查看在不同环境下的显示方式。
5 F/ b6 O2 `  _' o与初始化相对应的一个函数是重启函数,它的格式很简单 WL.Client.reloadApp(),作用就是重新读入主页面,执行初始化的工作。# L! T  H' b# M
接下来是将公有控件添加到应用中,在 Worklight 中比较常用的公有控件有三个(适应于 iPhone 和 Android),分别是等待提示、标签栏、和对话框。等待提示的主要作用就是在发送异步调用时锁住界面,防止用户进行其他的操作。0 N" `% I5 `$ \$ c8 M* {5 L' e
在 Worklight 中创建等待提示比较简单,需要设定两个参数:分别是锁定的界面节点和显示内容的参数设定。在本例中,界面为全部界面,所以节点为 null,设置的参数包括显示的文字 text,窗口的透明度 opacity,以及用于显示等待提示的跳跃效果参数 bounceAnimation。2 E. {- t5 n6 d1 R2 T# y+ R1 ^* W
标签栏的设置稍微复杂一点,在 iPhone 和 Android 环境中,标签栏的实现是不同的,前者依靠系统自带的本地控件,后者依靠 web 的实现方式,所以在 Android 中实现标签栏,需要设置一个父亲节点,并且是在初始化控件之前。标签栏还有一点需要注意的是代码的位置,在文件系统中,代码将被放入环境所在的那个 JavaScript 文件中(图 2 中绿色框处),这样才可以在运行特定环境的代码时有效果。- M  \$ m' Z9 e( A% D) k3 {

* {: Z! \6 q( r) h; N' \图 2. 标签栏代码位置! p6 U0 ^! _  @( d* o+ ?7 e

8 c$ Q- U3 N  s& I8 r& |0 d在标签栏的初始化完毕后,需要将不同的标签添加到页面中,添加标签的函数需要定制四个参数:标签的 ID,回调函数,标签的名称和图片的位置。标签的 ID 用一个字符串来唯一标示标签;回调函数用于定义在用户点击该标签时所相应的事件;标签名称为标签页显示的文字内容;图片位置在 iPhone 和 Android 中又不同,前者是指定图标的位置或者系统默认支持的一些图标的名称;后者就是指定图标的位置,包括选中和不选中时显示的图片。
9 N8 \% O2 C5 S8 }' l2 T, M) ~标签栏在 Android 版本中还有一个需要特别注意的问题:因为标签栏生成的页面会掩盖其余的 web 内容,所以需要将其他内容的 margin-top 设置为标签栏的高度,这样就可以不被标签栏遮盖。
% i7 Z9 I: ]- c6 K6 V2 i0 C最后一个是对话框,对话框统一的定制三个参数:title 定义对话框的标题;text 定义对话框的说明文字;buttons 是一个数组,里面均为 JSON 对象,在对象中包含了两个参数:btext 为按钮的显示名称,handler 为按钮点击时击发的事件函数。这个数组的最大有效容量是三个,当长度超过三时,余下的数据均无效。
6 J' T( q$ I4 `* {4 q, C. {完成了公共控件的构造后,就需要通过简单的按钮触发,来测试一些常用的功能。首先,在手机应用中,会打开一些外部的网页,比如一个企业的手机应用,可以内置企业的官方手机网站,便于用户的查看。但是利用 JavaScript 技术打开网页的效果会因为手机系统的不同而不同,所以利用 Worklight 封装的 WL.App.openURL 函数,可以在程序之外,利用系统自带的 safari 浏览器打开一个新的网页。5 ^7 A7 H( H' R: W% C! w' c  c
然后是测试网络情况的函数,在判断手机是否和网络连接,并且根据不同的网络情况使用不同的策略实现代码,都可以通过 WL.Device.getNetworkInfo (callback) 函数来获取信息。这个函数通过调用后返回的数据,检测各种网络情况。需要注意的是 WL.Client.isConnected() 这个函数已经被 deprecated 了,所以建议在开发时不用这个函数来检测是否和服务器连接。
0 [& b& b  _2 a. {最后一个需要介绍的功能函数是 WL.App.close(),在不同的手机应用平台上,应用关闭会有不同的方式,这不符合跨平台应用的需求。通过这个简单的函数,应用就能被关闭,然后回到主界面,或者应用被调用的地方。
: c& X9 i" S' g在介绍了这些功能后,Worklight 的客户端还提供了如下的的一些函数,WL.Client.getEnvironment() 用于获取程序运行的环境,但是在原则上利用 Worklight 的环境设置,而不是用这个函数去定制不同环境的代码;WL.Client.getAppProperty() 可以获取例如应用名称的数据,提供一些辅助的信息;WL.App.getDeviceLocale() 和 WL.App.getDeviceLanguage() 函数提供了系统的地区信息和语言信息,根据这两项可以对应相应的 message 文件,来完成应用多国化的支持。这些函数在本文的例子中都有涉及,可以查看如何使用。6 n9 h/ A* h+ O& A: o8 ?% u


& [; [7 }" A* {0 e4 B- \
3 f8 u9 C# e7 g6 U) g6 L, L结束语0 b5 T1 [: F  y! c& v2 @
在混合模式下开发良好的应用,就需要对 Worklight 的客户端 API 有足够的了解。本文介绍了很多常用的 API,实现了在客户端提供对公共控件的支持、多语言环境的支持和根据网络情况进行不同代码实现的支持。对于常用的调用外部系统的函数,可以查阅 《开始 Worklight 的开发之旅》《 Worklight 中适配器的开发》 获得详细的信息。
( B4 Y9 [8 s, g& A0 J在熟悉了这些 API 后,开发者可以利用 Worklight 提供的 LOG 和日志机制,记录运行时触发的各种日志信息,用于系统后期的调优、错误修复和数据统计。
0 X0 N# J  a- t( Q7 f7 Z
4 t! |* t% b; A- k: \2 b+ @

本帖子中包含更多资源

您需要 登录 才可以下载或查看,没有帐号?立即注册

x
 楼主| 发表于 2013-2-17 15:12:37 | 显示全部楼层
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

QQ|小黑屋|手机版|无图版|SCMLife.com ( 京ICP备06056490号-1 )

GMT+8, 2018-1-18 00:12 , Processed in 0.072964 second(s), 7 queries , Gzip On, MemCache On.

Powered by SCMLife X3.4 Licensed

© 2001-2017 JoyShare.

快速回复 返回顶部 返回列表