SCMLife.com

 找回密码
 立即注册

QQ登录

只需一步,快速开始

扫一扫,访问微社区

查看: 4453|回复: 1

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

[复制链接]
发表于 2013-2-17 15:03:05 | 显示全部楼层 |阅读模式
本帖最后由 技术狂人 于 2013-2-17 15:08 编辑 : n) {$ F1 o0 o. A7 t

9 Q- x- b4 y+ A/ E$ G客户端 API 的作用- S* z8 i1 z" W
在混合模式下开发的手机端应用,需要处理的一个主要问题就是:通过一种合理的语言,获取本地的信息(比如手机的类型,操作系统的版本,硬件的资源)和服务器端的信息(比如各种数据,网络的连接情况)。同时,能够通过一种合理的语言,创建一些公共的控件,比如对话框,这样就可以减少在不同手机环境下,代码的开发量。* ~+ i2 k. i" _) w
从广义的角度来讲,Worklight 混合模式的客户端 API 分为三个层次:普通的 JavaScript 框架,例如 jQuery mobile,dojo mobile,prototype 等等,它们主要负责和 HTML,CSS 的互动,来实现丰富的页面效果;基于 phonegap 的 JavaScript 框架提供了和手机本地硬件的交互能力,通过它能够很好的调用本地的一些资源;Worklight 开发的客户端 API 则提供了基于 Worklight 整体框架的 JavaScript 功能,比如常规的调用 adapter。 的方法,创建各种通用控件的方法,甚至还可以通过类似反射机制,和本地的代码进行交互的方法。这些功能为创建强大的混合模式应用提供了工具。- C3 w5 H& i6 ?; Y

% Q- b7 V$ X& A) M- Q3 A表 1. 客户端的不同选择6 \: p) Z0 D6 N: Q8 m* G
功能需求描述示例技术选择
标准的界面和图形表格、图片、列表标准的 HTML 页面技术,附加第三方 JavaScript 库
本地化控件对话框、菜单、标签栏Worklight 的客户端 API
对于不同客户端的优化在 iOS 情况下对于 iPhone 和 iPad 的适应在使用标准页面技术情况下,创建 Worklight 的环境
适应不同的设备环境同一应用提供的不同皮肤使用 Worklight 的皮肤设置
调用设备本地功能照相机、GPS、重力感应、名片夹、媒体播放使用 PhoneGap 的 JavaScript 库
第三方本地库的协作调用加密之后的本地库编写 PhoneGap 的插件
应用中集成 web 和本地 UI条形码检测使用 Worklight 的 API 调用本地的功能,实现 native 和 web 页面之间的共享
开发完全本地应用将原有项目导入到 Worklight 平台使用 Worklight 的本地 SDK

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

* Y2 |, R" ?: {/ |

  Z' }& L( g, `. P7 x" R6 ~0 V8 q9 I客户端 API 的分类6 B6 H, S: b5 n. E* C
Worklight 将 API 分为四类:普通应用接口,Worklight 可以创建手机应用外,还可以创建桌面应用和 web 应用,普通接口在不同环境下均可使用。手机的功能函数和 UI 控件,这些接口完全为了手机设定,为了更方便的提供跨平台功能,Worklight 对于不同手机操作系统实现的相同功能进行抽取,制作了这部分内容。桌面和 web 小工具的方法,这些函数主要用于非手机端开发。参数传递机制,这部分内容是在调用其他三部分时被使用的,但是因为这个机制,调用 API 的功能显得很强大,可以实现各种参数的设置和回调,提高了软件的灵活性和可读性。所以在解释其他部分函数时,需要首先了解第四部分的内容。
6 E$ i' V2 E0 FWorklight 方法的调用机制: [. x( Q( Q& Z) H: ^2 w( f
在所有的异步调用中,都需要传递一个 options 对象给函数,这个对象有三个公共属性,对于所有的函数来说都会使用,它们分别是 onSuccess,onFailure,invocationContext,相应的格式如清单 1 所示:) b/ L8 ]; Y3 Q: x* y, Q

; d5 a& V! g( |6 R) m清单 1. options 对象
0 o7 }2 @0 q% n) O  b1 O
options = {
8 c& Y" I3 `, X onSuccess: success-handler-function (response),
$ z# h3 u/ g, X8 Y onFailure: failure-handler-function (response), 6 ]9 |6 Z3 u; F9 \
invocationContext: invocation-context
; S! z) C# ^6 l7 J; b8 c; v( [* K% O$ w };
: S) H" h+ p! N4 G; o% w
属性 onSuccess 是一个回调函数,当异步调用成功时,这个函数被执行。参数 response 是一个对象,在不同的异步函数中内容不同,不过基本的参数包括两项:invocationContext 是传递过去的 options 中的内容;status 是异步调用的成功后返回的结果状态。. L" c) @" s* ~- F7 R! h- N
属性 onFailure 也是一个回调函数,当异步调用失败时(无论是客户端失败还是服务器端失败),这个函数被执行。参数 response 是一个对象,包括的基本参数四项,除了 invocationContext 和 status 外,还有 errorCode 和 errorMessage。第一项是在 Worklight 中已经定义的错误类型字段;第二项则是错误的具体信息,由服务器提供。
& [) S* X: q" b0 [属性 invocationContext 是一个存放异步函数上下文信息的地方。当调用结果从服务器返回的时候,需要通过它来确认客户端调用的函数,完成回调的过程。
1 ^' }; ?- N9 B& r当然这三个属性中的内容会因为调用函数的不同有差异,在具体用到相应函数时,可以通过查看相应函数的说明,了解内容的扩充情况,实现各自功能。
: c9 C% X1 h$ D  y% v
  a4 `; @. x' Y7 Y# i* b* c' M

) u) P/ R5 K! Y8 m) B- i1 V8 s客户端 API 的实现  k) }- I: p2 c
为了展现 Worklight 客户端 API 的丰富功能,本文将通过一个实际的应用来描述它的作用。3 |6 F& f2 ?, X8 s7 d$ N9 q
在应用创建后(应用名称为:ClientAPIApp),对 ClientAPIApp.html 文件中的 WL.Client.init 函数进行修改,修改后的内容如清单 2 所示:/ z. M8 R. z4 E) i9 u
: k* L! ?6 q2 G4 Z" h) s5 O8 h# H
清单 2. Worklight 客户端初始化
9 O4 o' J! }1 i2 R  ^3 t5 M
WL.Client.init({showLogger: true, timeout: 10000, heartBeatIntervalInSecs: 60})

) A% W2 f0 T5 ?从代码中可以看到,程序启动后将自动启动日志系统;每六十秒和服务器进行一次连接,判定网络是否通顺;在获取外部系统内容时,最大的等待时间为 10 秒。在启动应用后,通过 preview 界面显示应用,然后等待六十秒,在浏览器的窗口可以看到如下日志:
1 f" g: V' T( j# C3 R6 v
# ]. M* K1 `2 @图 1. 日志窗口
5 E$ z' v5 g. _
9 y8 g. u$ M: G2 ~1 b日志窗口的最后两行信息如下:
4 b# U+ e4 E6 a. K6 Q' t2 W8 B4 u  M" ^9 j+ \6 K
清单 2. 不同平台下心跳日志
& E/ J% w+ M. ?
浏览器/ ]& l6 p5 W, J0 ]" x9 C7 ~) |( s
- Request [/apps/services/api/ClientAPIApp/common/0/heartbeat] ( G$ }- c' o% J
( M" A, M$ I/ ~1 W; Y
- response [/apps/services/api/ClientAPIApp/common/0/heartbeat] success: $ M; A7 X$ d  f. d$ O/ G
* a( Z: M  P1 r6 j  W- k4 y
Android 模拟器' ], N$ D7 y  z* c
Request [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat]
0 _, W* S4 Z4 D1 n4 e/ Y! F6 N# u+ b: I+ }7 H4 O
response [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat] ( W( c. |& T5 l. X0 Z' a
success:
! x; I, _! R# Q% f% v2 c( i% w
创建 Android 的环境代码,并且在模拟器上运行,相应的内容将被打印在 Android 模拟器的日志系统中,这就说明在 Worklight 的日志系统中,相同的日志会根据不同的平台情况,被记录在不同地方。为了更好的说明这个问题,在本文的例子中,将在不同地方加入日志,并且查看在不同环境下的显示方式。
$ \1 W( u7 N6 \4 |1 m& Q8 V0 y& \7 J8 w与初始化相对应的一个函数是重启函数,它的格式很简单 WL.Client.reloadApp(),作用就是重新读入主页面,执行初始化的工作。
9 p7 D: J' _7 Y! S! c2 k接下来是将公有控件添加到应用中,在 Worklight 中比较常用的公有控件有三个(适应于 iPhone 和 Android),分别是等待提示、标签栏、和对话框。等待提示的主要作用就是在发送异步调用时锁住界面,防止用户进行其他的操作。
7 u  m- Q1 S! p在 Worklight 中创建等待提示比较简单,需要设定两个参数:分别是锁定的界面节点和显示内容的参数设定。在本例中,界面为全部界面,所以节点为 null,设置的参数包括显示的文字 text,窗口的透明度 opacity,以及用于显示等待提示的跳跃效果参数 bounceAnimation。
+ |2 c5 d( `1 M+ E( O标签栏的设置稍微复杂一点,在 iPhone 和 Android 环境中,标签栏的实现是不同的,前者依靠系统自带的本地控件,后者依靠 web 的实现方式,所以在 Android 中实现标签栏,需要设置一个父亲节点,并且是在初始化控件之前。标签栏还有一点需要注意的是代码的位置,在文件系统中,代码将被放入环境所在的那个 JavaScript 文件中(图 2 中绿色框处),这样才可以在运行特定环境的代码时有效果。: _5 Y3 `: r# A& m- ]& Y" G

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

8 }. M( V- H. T/ ?1 J' U4 |
$ ?+ A- ^" S  m
结束语
2 T6 O, ]: `9 b& G( R  t8 w在混合模式下开发良好的应用,就需要对 Worklight 的客户端 API 有足够的了解。本文介绍了很多常用的 API,实现了在客户端提供对公共控件的支持、多语言环境的支持和根据网络情况进行不同代码实现的支持。对于常用的调用外部系统的函数,可以查阅 《开始 Worklight 的开发之旅》《 Worklight 中适配器的开发》 获得详细的信息。
- v/ p8 S9 c7 L$ g在熟悉了这些 API 后,开发者可以利用 Worklight 提供的 LOG 和日志机制,记录运行时触发的各种日志信息,用于系统后期的调优、错误修复和数据统计。
- B0 ?( U; n' Q. J3 c% i2 [: ~) |0 |, r: J4 |1 I; i2 K

本帖子中包含更多资源

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

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

使用道具 举报

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

本版积分规则

关闭

SCMLife推荐上一条 /4 下一条

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

GMT+8, 2018-12-14 14:42 , Processed in 0.085610 second(s), 7 queries , Gzip On, MemCache On.

Powered by SCMLife X3.4 Licensed

© 2001-2017 JoyShare.

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