UAP_Mobile_JS编程API.docx

UAP Mobile JS编程框架与编程模型此部分要记录该文档形成过程中的历次版本变更过程及变更的内容版本修改与参与人修改时间修改原因修改内容审批人V1.0勾成图2013-09-01原始文档建立勾成图V2.0勾成图2013-12-3更新至V2.0勾成图V3.0杜莎莎2015-01-04更新至V3.01. 概述本文将描述UAP Mobile端上的JS编程框架和编程模型，其中包括如下内容：n JS编程框架n JS数据编程模型n JS控件编程模型2. JS编程2.1. JSControllern 每一个页面都对应有一个JSController文件和一个JSControllerBase文件n JSCotrollerBase是自动生成框架代码文件，JSController是书写JS代码逻辑的地方n ControllerBase文件为系统框架文件，框架自动调用，每次生成代码都会重新生成n Controller文件框架扩展文件，即应用开发人员代码文件，仅仅生成一次，删除后会重新生成n 每一个JSController文件中都有一个JSController类n 每一个控件的事件处理函数都在JSController中有对应的function2.2. 生成Controller代码生成JSController代码有两种方式：n 双击控件生成事件处理函数双击生成的默认JS方法名为“控件id_onEvent”的形式，可以再属性栏中修改默认JS方法名。例如：点击选择其含义是当点击label19的时候，会执行JSController中的label19_onclick方法。其中this的含义代码当前JSController。n 选择页面文件通过鼠标右键菜单生成每一个window都对应一个Controller和一个ControllerBase，通过设计器可以生成指定window的jscontroller。操作如下：2.3. 通过Action定义一个JS方法n Action可以被事件调用n Action都对应于JSControllerBase中的一个function，function的名称是Action的IDn Action中的Method都对应于JSController类中的一个function，function的名称是method的值n 开发人员的JS代码逻辑只能写在JSController的function中n 每次生成JSController都会自动重新生成JSControllerBase文件n JSController文件只会在第一次自动生成，除非删除后生成。DSL定义如下：com.yonou.um.View1中有action定义如下生成JSController后，在com.yonyou.um.view1ControllerBase中会有一个myload function在com.yonyou.um.view1Controller中会有一个login的function3. 数据（Context）编程3.1. 基本概念基于Context的编程实际上是对数据结构进行编程，通过JS代码来对当前页面的数据结构进行操作来完成自己的业务逻辑。理解Context编程需要理解以下几个基本概念n 数据上下文Contextn 绑定字段n 数据绑定3.2. 数据上下文Context我们规定一个页面有且仅有一个数据上下文对象Context，在JS中通过$ctx对象访问Context是当前页面的数据源Context内部的数据结构是一个JSONObject，即一个JS 的JSON对象Context中的字段对应JSONObject中的一个Key-Value，字段名是Key，字段值是Value通常情况下；n 一个页面的数据结构总是一个JSONObjectn 一个简单控件（例如Label、input）对应的一个字段n 一个列表对应的数据结构式JSONArray，同时JSONArray是Context中的一个字段3.3. Context API常用的API如下：$ctx.getString()/获取整个Context的字符串形式$cts.getString(fieldName)/获取指定字段的值，以字符串形式返回$ctx.getJSONObject()/获取整个Context的值，以JSONObject形式返回$ctx.getJSONObject(fieldName) /获取指定字段的值，以JSONObject形式返回$ctx.getJSONArray(fieldName) /获取指定字段的值，以JSONArray形式返回$ctx.put(fieldname,value) /修改执行字段值，不执行数据绑定$ctx.push(json) /重新提交Context，并自动实现数据绑定$ctx.dataBind() /数据绑定$ctx.dataCollect() /数据收集大家想一想，为什么没有$ctx.getJSONObject()?因为Context一定是一个JSONObject，不可能是一个JSONArray，所以使用$ctx.getJSONArray()会将Context的数据转化为JSONArray，会转化失败。3.4. 复杂Context结构Context对应的数据结构本质上是一个JSONObject，所以其内部可以是String、JSONObject和JSONArray的组合。其对应的JSON结构如下 name: 用友软件, address: 北清路68号, tel: 62435072, depts: did: d2013001, dcode: dept001, dname: 部门1, empls: eid: e20130011, ecode: EM0011, ename: 员工11 , eid: e20130012, ecode: EM0012, ename: 员工12 , eid: e20130013, ecode: EM0013, ename: 员工13 , did: d2013002, dcode: dept002, dname: 部门2, empls: eid: e20130021, ecode: EM0021, ename: 员工21 , eid: e20130022, ecode: EM0022, ename: 员工22 , eid: e20130023, ecode: EM0023, ename: 员工23 , did: d2013003, dcode: dept003, dname: 部门3, empls: eid: e20130031, ecode: EM0031, ename: 员工31 , eid: e20130032, ecode: EM0032, ename: 员工32 , eid: e20130033, ecode: EM0033, ename: 员工33 , linkm: lkid: lk2013001, lkcode: zhangsan, lkname: 张三 例如：$ctx.getString()结果：得到整个Context的字符串形式$ctx.getString(“name”)结果：得到字符串”用友软件”$ctx.getJSONObject(“linkm”)结果：得到一个JSONObject$ctx.getJSONArray(“depts”)结果：得到一个数组4. 控件编程4.1. 基本概念在Controller中可以通过全局对象$document对象来获取当前页面的控件模型。$document是一个全局对象，在JSController的任何function中都可以直接使用4.2. $document对象在JSController中可以通过全局对象$document来获取和操作当前页面内的控件。$document是一个全局对象，在JSController的任何function中都可以直接使用$document对象近似于HTML DOM编程中的document对象，区别在于多加了一个$符号。访问控件getElementById: 通过ID获取指定的控件4.3. getElementByIdgetElementById是最常用的一个方法。其含义是根据指定的控件Id（查找）获取该控件，其返回值是一个抽象控件类型Element。其使用形式为$document.getElementById(“xxxid”)注意：widget内部的控件的id，在JS编程时要使用widgetId_ControlID的形式访问。例如内的JS代码访问时，需要通过$document.getElementById(“w1_label0”)访问4.4. getAttribute和setAttribute通过getElementById获取控件对象后，如何对控件进行操作呢？4.4.1. 访问属性通过getAttribute(attrName)方法可以获取控件的属性值示例代码：var text = $document.getElementById(label1).getAttribute(value);/获取控件属性4.4.2. 设置属性通过setAttribute(attName,attrValue)方法可以设置控件的属性值示例代码：$document.getElementById(label1).setAttribute(text,我是label1);/设置控件属性5. $view$view是一个可以调用页面相关公共服务的全局对象。通过$view提供不同的方法，可以进行页面导航、页面传值等。5.1. open():打开新页面参数viewid：目标页面的全名，注意：页面首字母大写参数isKeep：打开新页面的同时是否关闭自己用法1：$view.open(viewid : com.yyuap.myref.List,isKeep : false)用法2：参数callback：viewid页面关闭后，执行的回调JS，【注意】使用callback时，isKeep需为true$view.open(viewid : com.yyuap.myref.List,isKeep : true,callback:mycallback()function mycallback() var ret = $param.getJSONObject(result); $document.getElementById(label4).setAttribute(value, ret.id); $document.getElementById(label9).setAttribute(value, ret.code); $document.getElementById(label14).setAttribute(value, );5.2. close():关闭页面用法1、直接close$view.close()用法2、有返回值的close参数resultCode：返回值代码，当为15时，如果父页面有callback，则会执行callback自定义参数：key-value形式，例如下例中的result$view.close(resultCode : 15,result : $document.getElementById(listview0).getAttribute(row);下例中result、x、y均为自定义参数$view.close(resultCode : 15,result :a:1,b:2x : abc,y : a:1,b:2);获取参数使用如下API，详细说明参见$param$param.getString(paramName)$param.getJSONObject(paramName)$param.getJSONArray(paramName)5.3. openPop():打开浮动窗口参数viewid：当前页面的widget参数isTouch：是否弹开模式浮动，默认值为false参数single：是否单例，默认值为true参数popwidth：宽度参数popheight：高度参数single：是否单例参数single：是否单例参数popgravity：弹开方式参数isdatabinding：数据绑定，默认值为false用法：var params = viewid : widget0,isTouch : false,single : true;$view.openPop(params);5.4. closePop():关闭浮动窗口参数viewid：当前页面的widget参数isdatabinding：数据绑定，默认值为false用法：var params = viewid : widget1;$view.closePop(params);5.5. openDialog():打开对话框参数style：对话框弹出样式参数title：标题参数bindfield：当style为带文本框的dialog时有效参数message：提示信息参数okaction：点击确定按钮时触发的action参数cancelaction：点击取消按钮时触发的action参数okbuttontitle：确定按钮显示名称参数cancelbuttontitle：取消按钮显示名称参数animation：动画效果用法：var params = title : dialog,message : 天空中最亮的星也有权利争取最美的灿烂,okbuttontitle : 确定,cancelbuttontitle : 取消,style : ok-cancel,okaction : ok(),cancelaction : cancel();$view.openDialog(params);function ok() $alert(click ok button);function cancel() $alert(click cancel button);5.6. openPicker():打开选择控件参数pickercount：picker的段数，默认值为1参数datasource：绑定特殊结构的数据源参数title：标题参数okbuttontitle：确定按钮显示文本参数cancelbuttontitle：取消按钮显示文本参数picker1binder：picker1收集再context中的字段名参数picker2binder：picker2收集再context中的字段名参数picker3binder：picker3收集再context中的字段名参数okaction：点击确定按钮时触发的action，事件中会收集picker中所选中的数据加入到context中参数onselectchange1：picker1选中值发生改变后的事件，用户可在该事件中动态改变context中数据参数onselectchange2：picker2选中值发生改变后的事件，用户可在该事件中动态改变context中数据参数onselectchange3：picker3选中值发生改变后的事件，用户可在该事件中动态改变context中数据用法：var params = okaction : save(),title : Hello Picker,pickercount : 3,datasource : picker : select : value : 1,content : 1, value : 2,content : 2, value : 3,content : 3, select : value : 1,content : 张三, value : 2,content : 李四, value : 3,content : 王五, select : value : 25,content : 25, value : 23,content : 23, value : 26,content : 26,picker1binder : no,picker2binder : name,picker3binder : age;$view.openPicker(params);6. $param页面间交互可以传递、接受参数。通过$param对象提供的API可以获取当前页面间传递的参数在目标页面获取参数有3种方式：n $param.getString(paramName)，将参数值转化为一个字符串n $param.getJSONObject(paramName)，将参数值转化为一个JSON对象，转化失败有提示，返回nulln $param.getJSONArray(paramName)，将参数值转化为一个JSON数组，转化失败有提示，返回null下面举例说明这3个API的使用方法，例如存在如下代码：$view.open(viewid : com.yyuap.demo.List, /目标页面（首字母大写）全名，isKeep : false,data1 : a:1, b:2,/参数是JSONObjectdata2 : a:1, b:2,x:1,y:2,/参数是JSONArraydata3 : x:1,y:2,/参数是JSONObject对应的Stringdata4 : a:1, b:2,x:1,y:2,/参数是JSONArray对应的Stringdata5 : hello world/参数是String);下面说明一下目标页面com.yyuap.demo.List页面如何使用这3个API获取参数过来的参数6.1. getString无论参数值原始类型，该方法统一将参数转化为字符串类型var data1 = $param.getString(data1);结果：a:1,b:2解释：open方法中data1是一个JSONObject，使用getString方法会将参数值转化为Stringvar data2 = $param.getString(data2);结果为：a:1,b:2,x:1,y:2解释：open方法中data2是一个JSONArray，使用getString方法将参数值转化为String形式var data3 = $param.getString(data3);结果为：x:1,y:2解释：open方法中data3原本就是字符串，使用getString方法将参数值转化为String形式var data4 = $param.getString(data4);结果为：a:1,b:2,x:1,y:2解释：open方法中data4原本就是字符串，使用getString方法将参数值转化为String形式var data5 = $param.getString(data5);结果为：hello world解释：将参数值转化为String形式6.2. getJSONObject 无论参数值原始类型，该方法统一将参数转化为JSONObject类型，如果转化失败，返回nullvar data = $param.getJSONObject(data1);结果为：a:1,b:2解释：open方法中data1是一个JSONObject，使用getJSONObject方法会将参数值转化为JSONObjectvar data = $param.getJSONObject(data3);结果为：a:1,b:2解释：将参数值转化为JOSNObject以下转化失败，以下返回nullvar data2 = $param.getJSONArray(data2);var data4 = $param.getJSONObject(data4);var data5 = $param.getJSONObject(data5);结果为：null解释：转化失败，返回null6.3. getJSONArrayvar data = $param.getJSONObject(data2);结果为：a:1,b:2,x:1,y:2解释：将参数值转化为JSONArrayvar data3 = $param.getJSONArray(data4);结果为：a:1,b:2,x:1,y:2解释：将参数值转化为JOSNArray 以下转化失败，以下返回null$param.getJSONArray(data1);$param.getJSONArray(data3);$param.getJSONArray(data5);7. $cache$cache是当前本地缓存服务对象7.1.1. read和write$cache.read(key) -读取缓存中的key值$cache.write(key, value) -将value加入缓存，以key作为键值缓存7.1.2. 示例代码 write和read/该用例说明如何缓存一个字符串/如何缓存一个JSON对象function com$yonyou$um$Cache_read_writeController$cache_write_read(ctx)var salarypswd=000001;$alert(_开始测试缓存+salarypswd+*);$cache.write(salarypswd, salarypswd); var newpsw = $cache.read(salarypswd);$alert(newpsw)$alert(取出来的值为: + newpsw);/应该为000001var str1=m:1,n:2,p:aaa;$alert(*开始测试缓存字符串+str1+*);$cache.write(str1, str1); var new_str1 = $cache.read(str1);$alert(new_str1)$alert(取出来的值为: + new_str1);/应该为字符串m:1,n:2,p:aaavar obj1=m:1,n:2,p:aaa;$alert(*开始测试缓存json对象为+$jsonToString(obj1)+*);$cache.write(obj1, obj1); var new_obj1 = $cache.read(obj1);$alert(new_obj1);/取出来的是一个字符串$alert(取出来的值为: + new_obj1);var json1 = $stringToJSON(new_obj1);$alert($stringToJSON(new_obj1) = + json1);/此时json1是一个object$alert($jsonToString(json1) = + $jsonToString(json1);8. $sqlite$sqlite是数据库服务对象，可以进行数据库增、删、改、查等操作8.1.1. $sqlite.execSql参数： db : dbname, sql : sql 8.1.2. $sqlite.queryByPage参数 db : dbName, sql : sql, pageSize : pageSize, / pageSize，每页的记录数，从1开始 pageIndex : pageIndex / pageIndex，页号索引，从0开始8.1.3. $sqlite.query参数 db : dbname, sql : sql, startIndex : 0, /从第几条记录开始， Index表示从0开始 endIndex : 9 /到第几条记录结束（返回值包含该条）以上返回结果为索引09，共10条记录8.1.4. $sqlite.exist参数 db : dbname, 9. $menu$menu是实现菜单的服务对象9.1. openDropDownList ():打开下拉菜单参数controlid：目标控件的id 参数dropDownListWidth：菜单项的宽度参数dropItemsArray：菜单项内容，格式为JSON数组用法：$menu.openDropDownList(controlid : menubtn,dropDownListWidth : 200,dropItemsArray : name : 菜单1,/菜单项名称action : menu1action(),/点击该菜单项时执行的JS方法image : btn_fav.png/菜单项的icon,name : 菜单2,/菜单项名称action : menu2action(),/点击该菜单项时执行的JS方法 image : btn_fav.png/菜单项的icon,name : 菜单3,/菜单项名称action : menu3action(),/点击该菜单项时执行的JS方法image : btn_fav.png/菜单项的icon);function menu1action()$alert(menu 1 test normally);function menu2action()$alert(menu 2 test normally);function menu3action()$alert(menu 3 test normally);10. $badge$badge是提供标记显示、隐藏的服务对象10.1. showBadge ():显示标记参数target：要显示角标的目标控件的id 参数text：角标显示的内容参数position：显示在target控件的位置 topright | topleft | bottomright | bottomleft用法：$badge.showBadge(target : image0,text : 1, position : topright);10.2. hideBadge ():隐藏标记参数target：要隐藏角标的目标控件的id 用法：$badge.hideBadge(target : image1);11. $net$net是获取当前设备网络信息的服务对象11.1. available()用法：var infor = $net.available();11.2. getNetworkInfo ()用法：var info = $net.getNetworkInfo();12. $camera$camera是对相机、图库等操作的服务对象12.1. open ():打开相机参数bindfield：存储照片的字段 参数callback：回调用法：$camera.open(bindfield : image,callback : imageCallback();function imageCallback()var img = $ctx.getString(image);$id(image0).set(src, img);12.2. openPhotoAlbum ():打开相册参数bindfield：存储照片的字段 参数callback：回调用法：$camera.openPhotoAlbum(bindfield : image,callback : imageCallback()function imageCallback()var img = $ctx.getString(image);$id(image0).set(src, img);13. $tel$tel是与电话、短信、邮件相关的服务对象13.1. call ():打电话参数tel：拨打的电话号码用法：var tel = $id(telnum).get(value);/获取文本框中输入的电话号码$tel.call(tel);13.2. sendMsg ():发短信参数tel：发送短信的电话号码参数body：发送短信的内容用法：var telnum = $id(telnum).get(value);$tel.sendMsg(tel : telnum,/电话号码body : hello send message test/短信内容);13.3. sendMail ():发邮件参数receive：收件人的邮箱账号参数title：邮件主题参数content：邮件内容用法：$tel.sendMail(receive : 1165448650,/收件人title : hello,/邮件主题content : 欢迎使用UAP Mobile/邮件内容);13.4. saveContact ():保存联系人参数tel：手机号码参数employeename：联系人名称参数jobname：职位参数orgname：部门名称参数address：单位地址参数email：邮箱参数officetel：办公电话$tel.saveContact(tel : 139*, employeename : 张三, jobname : 职员,orgname : 开发部,address : 北京市海淀区*,email : ,officetel : 6243*);14. $device$device是获取设备信息的服务对象14.1. getTimeZoneID ():获取时区ID用法：$device.getTimeZoneID();14.2. getTimeZoneDisplayName ():获取时区DisplayName用法：$device.getTimeZoneDisplayName();14.3. getLocation ():获取位置信息参数bindfield：位置信息回写的绑定字段参数callback：回调执行的JS方法参数single：是否只获取1次参数isgetaddress：是否需要获取地址参数network：是否使用wifi定位用法：$device.getLocation(bindfield : location,callback : getLocationCallBack(), single : true,isgetaddress : false, network : false );14.4. openWebView ():打开网页参数url：打开网页的URL $device.openWebView(url : );14.5. getInternalMemoryInfo():获取内部存储信息用法：$device.getInternalMemoryInfo()14.6. getExternalStorageInfo ():获取外部存储信息用法：$device.getExternalStorageInfo();14.7. getMemoryInfo ():获取存储信息用法：$device.getMemoryInfo();14.8. getDeviceInfo ():获取设备信息用法：$device.getDeviceInfo();14.9. capturePhoto ():获取图片参数bindfield：存储照片的字段 参数callback：回调用法：$device.capturePhoto(bindfield : image,/存放图片返回值的Context字段名callback : imageCallback()/回调JS方法);14.10. openAddressBook ():打开通讯录用法:$device.openAddressBook();15. $scanner$scanner是提供二维码扫描的服务对象15.1. open ()参数bindfield：二维码扫描结果保存字段参数callback：扫描完成后回调用法：$scanner.open(bindfield : code,callback : scanok();function scanok() var json = $ctx.getJSONObject(code); json = $jsonToString(json); $alert(扫描结果: + json);16. $file$file是提供上传下载文件的服务对象16.1. upload ()上传的文件保存在tomcat的路径下即apache-tomcat-7.0.57webappsumserverdownload目录下。有关tomcat文档请看同目录下的“MAServer关键文档.docx。参数url：上传服务器端路径,即配有tomcat的电脑的IP参数filename：上传文件的路径+文件名参数bindfield：上传后的返回值，类型为JSONObject（其中从键值url可以获取上传后该文件的url）参数callback：上传后的回调方法用法：$file.upload( url : 2:8080/umserver/upload, filename : xxx/xxx/file.xxx, bindfield : upload, callback : uploadImageCallback();function uploadImageCallback()var upload = $ctx.getString(upload);upload = $stringToJSON(upload);/upload.url即上传文件存放的URL，可根据该URL下载该文件$alert(服务器上文件存放的URL为: + upload.url);flag = f