SCMLife.com

 找回密码
 立即注册

QQ登录

只需一步,快速开始

扫一扫,访问微社区

查看: 4101|回复: 1

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

[复制链接]
发表于 2013-2-17 15:03:05 | 显示全部楼层 |阅读模式
本帖最后由 技术狂人 于 2013-2-17 15:08 编辑
6 O, f3 Y& _" {7 Y, z0 b6 z# D9 ?8 e0 C! g  d' t5 r4 W
客户端 API 的作用
9 G3 |' i& _7 ~  T+ |2 m+ W: x在混合模式下开发的手机端应用,需要处理的一个主要问题就是:通过一种合理的语言,获取本地的信息(比如手机的类型,操作系统的版本,硬件的资源)和服务器端的信息(比如各种数据,网络的连接情况)。同时,能够通过一种合理的语言,创建一些公共的控件,比如对话框,这样就可以减少在不同手机环境下,代码的开发量。/ }8 w' V" z, S; F
从广义的角度来讲,Worklight 混合模式的客户端 API 分为三个层次:普通的 JavaScript 框架,例如 jQuery mobile,dojo mobile,prototype 等等,它们主要负责和 HTML,CSS 的互动,来实现丰富的页面效果;基于 phonegap 的 JavaScript 框架提供了和手机本地硬件的交互能力,通过它能够很好的调用本地的一些资源;Worklight 开发的客户端 API 则提供了基于 Worklight 整体框架的 JavaScript 功能,比如常规的调用 adapter。 的方法,创建各种通用控件的方法,甚至还可以通过类似反射机制,和本地的代码进行交互的方法。这些功能为创建强大的混合模式应用提供了工具。9 K2 a  ^. \2 M
+ G5 h* Z- p6 a- M
表 1. 客户端的不同选择
9 d5 z) P- P$ ]0 A1 w& a0 r
功能需求描述示例技术选择
标准的界面和图形表格、图片、列表标准的 HTML 页面技术,附加第三方 JavaScript 库
本地化控件对话框、菜单、标签栏Worklight 的客户端 API
对于不同客户端的优化在 iOS 情况下对于 iPhone 和 iPad 的适应在使用标准页面技术情况下,创建 Worklight 的环境
适应不同的设备环境同一应用提供的不同皮肤使用 Worklight 的皮肤设置
调用设备本地功能照相机、GPS、重力感应、名片夹、媒体播放使用 PhoneGap 的 JavaScript 库
第三方本地库的协作调用加密之后的本地库编写 PhoneGap 的插件
应用中集成 web 和本地 UI条形码检测使用 Worklight 的 API 调用本地的功能,实现 native 和 web 页面之间的共享
开发完全本地应用将原有项目导入到 Worklight 平台使用 Worklight 的本地 SDK

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


) `  X1 E( H9 D% V/ E9 `( i2 y( ?7 u! d) @# L  M7 H
客户端 API 的分类
4 R$ Z' V! A. ^2 q/ E( O7 y' nWorklight 将 API 分为四类:普通应用接口,Worklight 可以创建手机应用外,还可以创建桌面应用和 web 应用,普通接口在不同环境下均可使用。手机的功能函数和 UI 控件,这些接口完全为了手机设定,为了更方便的提供跨平台功能,Worklight 对于不同手机操作系统实现的相同功能进行抽取,制作了这部分内容。桌面和 web 小工具的方法,这些函数主要用于非手机端开发。参数传递机制,这部分内容是在调用其他三部分时被使用的,但是因为这个机制,调用 API 的功能显得很强大,可以实现各种参数的设置和回调,提高了软件的灵活性和可读性。所以在解释其他部分函数时,需要首先了解第四部分的内容。; U" v5 T* L8 E9 Y5 y* k
Worklight 方法的调用机制
* k# b7 a: b  z7 e- q在所有的异步调用中,都需要传递一个 options 对象给函数,这个对象有三个公共属性,对于所有的函数来说都会使用,它们分别是 onSuccess,onFailure,invocationContext,相应的格式如清单 1 所示:2 b8 i; k: l/ G, J) f; c6 r- s
8 m. @. C+ @& }0 F+ K) J, c- s
清单 1. options 对象% j9 _0 m  f9 W% P9 m
options = { 8 J& P3 K) s" R6 H0 @
onSuccess: success-handler-function (response), ; z: S1 f' @, E% H
onFailure: failure-handler-function (response), 4 m# H9 q7 Q; D' ~
invocationContext: invocation-context % |- P. ]6 O; y4 P! B; c
};
3 i2 Z6 t6 b9 r1 ]2 K0 p
属性 onSuccess 是一个回调函数,当异步调用成功时,这个函数被执行。参数 response 是一个对象,在不同的异步函数中内容不同,不过基本的参数包括两项:invocationContext 是传递过去的 options 中的内容;status 是异步调用的成功后返回的结果状态。
% u/ _1 S& W7 M2 z- j* h属性 onFailure 也是一个回调函数,当异步调用失败时(无论是客户端失败还是服务器端失败),这个函数被执行。参数 response 是一个对象,包括的基本参数四项,除了 invocationContext 和 status 外,还有 errorCode 和 errorMessage。第一项是在 Worklight 中已经定义的错误类型字段;第二项则是错误的具体信息,由服务器提供。# P& \8 B, Q+ h3 ~, p
属性 invocationContext 是一个存放异步函数上下文信息的地方。当调用结果从服务器返回的时候,需要通过它来确认客户端调用的函数,完成回调的过程。5 o+ g! g& k, n9 b. T+ b1 N; {
当然这三个属性中的内容会因为调用函数的不同有差异,在具体用到相应函数时,可以通过查看相应函数的说明,了解内容的扩充情况,实现各自功能。
! t1 |6 f( j) g! ^7 M

3 A9 k5 k: V. [& b
6 \6 q' u% W& a# M  a7 y客户端 API 的实现# m1 ^, r. P5 H9 Q4 X
为了展现 Worklight 客户端 API 的丰富功能,本文将通过一个实际的应用来描述它的作用。0 r6 @( O! Y  F
在应用创建后(应用名称为:ClientAPIApp),对 ClientAPIApp.html 文件中的 WL.Client.init 函数进行修改,修改后的内容如清单 2 所示:
3 n' H" `( \0 d; u5 d( R- F) V, [" F' B  N7 K4 i2 ]
清单 2. Worklight 客户端初始化: V, b: M0 L9 H. i
WL.Client.init({showLogger: true, timeout: 10000, heartBeatIntervalInSecs: 60})

5 N8 E: y# K# m: H9 a( X9 x; d从代码中可以看到,程序启动后将自动启动日志系统;每六十秒和服务器进行一次连接,判定网络是否通顺;在获取外部系统内容时,最大的等待时间为 10 秒。在启动应用后,通过 preview 界面显示应用,然后等待六十秒,在浏览器的窗口可以看到如下日志:) a+ Q3 w8 V1 z! a% u# A9 p
  o* e) M0 }5 T: n8 [- k! O
图 1. 日志窗口) j6 n  O9 o* [+ i$ [9 D' d

- D! ]0 ~0 ~0 U8 r: V日志窗口的最后两行信息如下:7 d) p. r: S4 t( `. |, A

* o" O6 a, d$ N8 a. p9 }+ ]& }% q清单 2. 不同平台下心跳日志
, ?' Y0 W# ^7 `2 L
浏览器
: ^; o. e1 T- q: u' J' Z' j/ m - Request [/apps/services/api/ClientAPIApp/common/0/heartbeat]
+ y) T0 o# v' S3 B+ j" S0 l* K: C+ q7 ~) ]" Q
- response [/apps/services/api/ClientAPIApp/common/0/heartbeat] success:
- I9 g8 D* s/ m: m# w+ d2 m# w* D9 j) H9 \* @
Android 模拟器
" L& e3 x: N/ ~7 @, Q Request [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat] 8 ]3 [8 E0 X6 o3 G# P
8 q2 A/ x" Z3 _, }
response [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat]
9 e# M  ?, T/ w: i; ~2 `8 V success:
* O4 m( U$ [4 O
创建 Android 的环境代码,并且在模拟器上运行,相应的内容将被打印在 Android 模拟器的日志系统中,这就说明在 Worklight 的日志系统中,相同的日志会根据不同的平台情况,被记录在不同地方。为了更好的说明这个问题,在本文的例子中,将在不同地方加入日志,并且查看在不同环境下的显示方式。) a; c! n% S5 J( p
与初始化相对应的一个函数是重启函数,它的格式很简单 WL.Client.reloadApp(),作用就是重新读入主页面,执行初始化的工作。4 L/ u0 U$ v1 A* V( z
接下来是将公有控件添加到应用中,在 Worklight 中比较常用的公有控件有三个(适应于 iPhone 和 Android),分别是等待提示、标签栏、和对话框。等待提示的主要作用就是在发送异步调用时锁住界面,防止用户进行其他的操作。
/ E/ H: F+ W! C+ p9 p. i在 Worklight 中创建等待提示比较简单,需要设定两个参数:分别是锁定的界面节点和显示内容的参数设定。在本例中,界面为全部界面,所以节点为 null,设置的参数包括显示的文字 text,窗口的透明度 opacity,以及用于显示等待提示的跳跃效果参数 bounceAnimation。8 q- U, I* ~5 h
标签栏的设置稍微复杂一点,在 iPhone 和 Android 环境中,标签栏的实现是不同的,前者依靠系统自带的本地控件,后者依靠 web 的实现方式,所以在 Android 中实现标签栏,需要设置一个父亲节点,并且是在初始化控件之前。标签栏还有一点需要注意的是代码的位置,在文件系统中,代码将被放入环境所在的那个 JavaScript 文件中(图 2 中绿色框处),这样才可以在运行特定环境的代码时有效果。0 R5 [4 `; X9 ?' |

/ \$ v8 c* I8 W图 2. 标签栏代码位置; D6 F4 d. G8 ]$ Y' e; @4 I9 W

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


: L& p' X& R  T3 H' M0 c
6 t* F  b/ Y" e6 E7 o7 @1 p0 t结束语
; X' R9 u7 e  A! D在混合模式下开发良好的应用,就需要对 Worklight 的客户端 API 有足够的了解。本文介绍了很多常用的 API,实现了在客户端提供对公共控件的支持、多语言环境的支持和根据网络情况进行不同代码实现的支持。对于常用的调用外部系统的函数,可以查阅 《开始 Worklight 的开发之旅》《 Worklight 中适配器的开发》 获得详细的信息。; M5 Z" @1 q( _; L# X7 `6 X
在熟悉了这些 API 后,开发者可以利用 Worklight 提供的 LOG 和日志机制,记录运行时触发的各种日志信息,用于系统后期的调优、错误修复和数据统计。
0 A( j2 p% \5 \0 D+ c4 [- ^' ?  x7 z, A, p  i

本帖子中包含更多资源

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

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

使用道具 举报

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

本版积分规则

关闭

SCMLife推荐上一条 /4 下一条

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

GMT+8, 2018-6-23 18:11 , Processed in 0.090035 second(s), 7 queries , Gzip On, MemCache On.

Powered by SCMLife X3.4 Licensed

© 2001-2017 JoyShare.

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