rsp技术开发规范总结.doc

终 端RSP开 发 规 范2010-3-4目 录一、StoryBoard规范41、 场景描述规范42、 Service Tree规范4二、 命名规范41、 RSP命名规范42、 元素节点命名规范43、 RSP中Java代码命名规范54、 切图图片命名规范5三、 注释规范51、 RSP文件注释52、 RSP节点注释53、 业务条件注释6四、 开发框架规范61、 目录规范62、 RSP框架规范63、 屏幕适配框架使用规范104、 Cache使用规范135、 CacheObject使用规范14一、StoryBoard规范1、 场景描述规范1） 描述场景功能，对每个场景编号，该编号和Service Tree中场景编号对应；2） 描述场景中各个元素的来源，动画效果和交互效果；2、 Service Tree规范Service Tree要对没一个业务场景编号，该编号和Story Board的场景编号对应。ServiceTree要反映各个场景的跳转和层次关系，根据此层次关系确定开发框架中的场景级数。2、 命名规范1、 RSP命名规范RSP命名形式：文件所在位置_所属业务_场景名_类型l 文件所在位置是指文件是在客户端还是服务器端。在客户端的文件用c表示，在服务器端的文件用s表示；l 所属业务是指该文件属于哪个业务模块，比如该页面在客户端，且属于新闻模块则写成：c_news.rsp。业务名全部用英文表示;l 场景名是指该rsp所描述对应场景名，场景名用英文表示。如该页面在客户端是新闻模块，描述的是新闻类型则该rsp名是c_news_type.rsp;类型是指该rsp是View还是Content。比如该页面在客户端，且属于新闻模块且为View则写成：c_news_type_view.rsp;如果该rsp文件既不是View也不是Content则该类型可以不写。l 文件名一律小写。l 文件编码必须是UTF-82、 元素节点命名规范节点命名形式：节点域_所属业务_场景名_内容描述l 节点域，本地用“Local”，全局用“Global”禁止使用简写；l 内容描述，由开发人员定义。只要符合能表述清楚该节点的功能或内容的原则就行。内容描述用英文；l 节点名称遵循驼峰是命名规则，Global：newsDetail表示新闻明细或者Global：news_detail其他描述同RSP命名规范。3、 RSP中Java代码命名规范RSP中Java代码变量全小写，只要符合能表述清楚该变量的意义的原则皆可。代码编写必须遵循java1.5的规范.遵循匈牙利命名规则.4、 切图图片命名规范图片命名形式：图片所在位置_所属业务_内容l 图片所在位置是指图片是在客户端还是服务器端。在客户端的图片用c表示，在服务器端的文件用s表示；l 所属业务是指该图片属于哪个业务模块，比如该图片在客户端，且属于新闻模块则写成：c_news.png。图片名全部用英文表示;内容是指对该图片意思的表述，如该图片是按钮按下的图片，在客户端属于新闻模块则写成：c_news_button_down.png3、 注释规范1、 RSP文件注释在每个RSP文件开头要有如下形式的注释：2、 RSP节点注释对RSP文件中的每个节点或节点块头标明该节点对应StoryBoard中的场景或动作效果。如：.3、 业务条件注释如果由于业务条件的不同，同一个表示区域会有不同的效果或动作则要在条件判断处要标明在什么情况下会进入哪段代码。4、 开发框架规范1、 目录规范目录规范用于说明项目工作区的文档结构，规范文件放置。具体结构如下：src 公用目录业务组1 子业务1 子业务2 业务组2 子业务1 子业务2 . . .Res Devices设备配置目录 Layouts 界面布局配置目录 Skins 皮肤配置目录 不同分辨率图片文件夹 公用图片夹 业务1 业务2 如图:表示:240x320分辨率下的”无线生活”文件 下的”便民查询”查询文件夹整个工作去分src，res，libs文件夹，分别放置源代码，资源文件，外部包和配置文件。src下每个业务分别建立自己的源代码文件夹，文件夹名用能代表该业务的英文说明表示；res下分为devices，layouts，skins三个文件夹，主要放置配置文件.分别放置公共资源，客户端资源，服务器端资源。其中客户端资源和服务器端资源中的各个业务的资源放置到自己所属的业务资源文件夹中；libs下放置扩展包和交互API；2、 RSP框架规范RSP框架规范用于说明终端开发中要遵循的各项框架性的准则和要求，定义一个基本的开发结构框架。基本原则：1、 View/Content分离，View包含显示框架、显示逻辑和控制逻辑，放置在客户端；Content负责与后台交互并向View填充数据；2、 合理运用缓存；l 服务器端的场景要尽可能多的缓存；l 对于没有特定关联关系的业务场景（新闻，天气等）要使用一级缓存以减少服务器编译时间；l 常用的外部资源（美图业务的图片）要使用二级缓存以减少RMS与外部的服务交互；l 可预知用户操作的业务（读书）要使用CacheObect提前缓存，减少用户等待时间；l 使用缓存队列维护缓存；l 建立合理的缓存控制机制。3、 定义符合该项目的主体场景树；主体场景树要求包含该项目的所有框架节点，供开发业务时使用；4、 开发过程中不要使用无target的Insert节点，主体场景树定义RSP除外；5、 除主体场景树所在的RSP外不要有或减少Insert节点，特别是无target的Insert节点；6、 一个场景的Action尽量写在一个单独的Action节点中；7、 场景加载时按照Service Tree添加到对应的级别Transform；8、 在同一个业务中有本级向下一级跳转时不要删除本级页面代码而是将本级隐藏，当由下级向上级返回时删除本级代码，显示上级节点；9、 如果业务存在过多的跨业务的跳转需讨论决定是否使用6，7两点。因为此种情况下维护级别节点是个不小的开销；10、 服务器端的RSP要被try/cache包住，并处理异常；11、 将一个RSP分成多个单元，将优先显示的内容放在前面，次要的需要大量时间传输的内容放在后面。根据实际场景做具体调整12、 关闭超时,最后才渲染的场景放在 finally里面.主体框架示例：l 目录结构示例src basec_main.rspc_cache_clean_view.rsps_cache_clean_content.rsps_update_client.rspc_version_check_view.rsps_version_check_content.rspc_dummy.rsp common home c_home_view.rspc_home_content.rsp news c_news_base.rsp c_news_type_view.rsp s_news_type_content.rspres client common background.pngfoot.pngheader.png news servercommon newslibs client.jarconfl 文件说明c_main.rsp项目的主体场景树。其包含了整个项目中要使用的节点。文件内容见附件c_main.rspc_version_check_view.rsp，s_version_check_content.rsp这两个文件负责登录时的版本校验。在c_main.rsp最后会调用c_version_check_view.rsp这个文件，该文件中包含了所有需要校验版本的业务Text节点和Save节点以保存版本号。s_version_check_content.rsp负责从后台取最新的版本号并和已有的版本好比对，并更新版本号。如客户端需更新则调用s_update_client.rsp。 s_update_client.rsp负责更新客户端。关键代码如下： c_cache_clean_view.rsp和c_cache_clean_content.rsp这两个文件负责清理需要更新的缓存。用法如下这样把所有以news.rsp开头的缓存就都清除了。l 场景间的跳转每个场景在业务中都有其场景级别。当要跳转到该场景时要隐藏上一级的场景,需调用c_main.rsp中的对应级别的动作。如第0级到第一级要调用Global:replace_back_from_loading_for_content.L1这个方法隐藏第0级。返回时则调用Global:replace_back_from_loading_for_content.L0显示第0级的内容。返回示例代码：l 场景的更新每个场景页面要在开头替换掉之前该场景的内容，一个空场景的模板代码如下：以第零级为例:该场景的内容5、 实用代码规范1、 屏幕适配框架使用规范屏幕适配通过scale或layout组件实现。屏幕适配的好处是开发一套UI能适配其他分辨率的版本，降低了开发工作量。使用scale的好处是适配简单，能快速应用到一个新的分辨率。缺点是无法对场景进行微调，如果发现界面上有部分显示效果不佳只能以硬编码的方式解决，无法通用。Scale的使用已经在开发框架中搭建好。只要配上后台API就能使用。使用layout的好处是它能精细的调节场景上的每一个元素，通过配置文件进行管理，可以在不改变代码的情况下适配各种分辨率。缺点是配置文件过多过复杂，如果layout被放置在服务器端使用则会影响效率，放在客户端则不会。要使用Layout需要adaptaion.jar包。新版本的Developer新建service时会自动提供该包，并会产生一个adaptation.xml。以下是个标准的adaptation.xml 可以看出layout由Theme，Skin，Layout三部分组成。Theme包含多个Skin，每个Skin负责定义该分辨率下各个元素的显示样式，如高度，颜色等。比如QVGA.xml： 其指定了footer_bg这个Image节点读取图片的url是“QVGA/footer_bg.png”，高度是20，名字为footer_txt的Text节点颜色是“#FFFFFF”。LayoutSet是一个Layout集合，其可以包含多个Layout。Layout负责定义每个Transform的大小。如main.xml: 每个Container都定义了显示的百分比高度等属性，在RSP中只要调用这些ID就能将该Container的显示定义加载到调用的Transform上。在RSP中使用Layout的方法：首先要得到Container：设置加载资源和Transformimage source= streamID=footer_bg / 这里最关键的是root.getChildByIdRecurs(Search) .applyTo(currentTransform);它将配置文件中的属性加载到了当前的Transform，这样就实现了通过配置文件设置页面上元素的位子，大小，样式。2、 Cache使用规范Cache能将资源或页面缓存到客户端或服务器，提高了用户使用速度。Cache分为客户端Cache和服务器端Cache。l 客户端Cache客户端Cache是将访问的场景缓存到客户端。这样用户再次访问该页面时就不用访问服务器，既减少了数据流量又提高的显示速度。具体用法如下：在RSP的header中加入缓存的属性： cacheable设置为true则该页面会缓存clientCacheTtl设置缓存有效时间，以毫秒为单位。过了时间则缓存失效。Permanent是设置是否永久缓存，如果为true则会该缓存会保存到内存上永不失效，除非通过命令清除缓存。注意：由于RME默认缓存大小只有1024KB所以如果要获得更多的缓存空间需要修改默认缓存值后重新编译RME。l 服务器端cache服务器端cache分为cache L1和cache L2L1的作用是在服务器端将stz文件缓存到内存中。这样减少了服务器与后台交互以及生成stz的时间。用法如下:在中加入serverCacheTtl属性，如L2的作用是将外部资源缓存到服务器的内存中，这样可以减少RMS和外部服务器交互的时间。用法如下：关键就是stzRequest.getExternalResource这个方法。此例子就是把指定url的图片缓存到了服务器端。3、 CacheObject使用规范当用户在浏览某一个页面的时候，总是希望后台此时不是空闲状态，而是继续下载即将可能会被加载的下一页面，这样，当用户点击进入下一页面时，可以直接从本地缓存区读取，节省了用户的时间，达到更好的用户体验。使用方法如下：cacheObject标签在streamezzo标签下使用，置于AUnits之间。url是需要提前加载的页面，endTime是缓存页面的生存时间，permanent是缓存页面的存储方式，priority确定页面的下载顺序。此标签主要用于在浏览某一页面时提前在后台加载其他页面，并缓存在本地，当该缓存页面的生存时间结束时，将其从本地清除，或者提前加载该缓存页面的某一页面从服务器重新被加载，则该缓存页面被更新。注意：（假设a页面是主页面，利用cacheObject提前加载其他页面）1) a页面可以同时提前加载缓存多个页面，每个缓存页面也可以设置相应的生存时间，在生存时间内，缓存页面存在于内存中；2) 重新加载a页面时，会重新下载cacheObject中设置的缓存页面，即使该缓存页面生存时间尚未失效；3) 当priority设置为HIGH时，根据cacheObject在AUnits中所处的位置决定加载缓存页面的时间；当priority设置为LOW，则是在a页面所有的AUnits都加载完后再加载缓存页面；4) a页面加载的缓存页面不能利用cacheObject来cache a页面。我们假设a页面提前加载b页面，b页面提前加载a页面，当a页面加载b页面时会执行b页面中提前加载a页面的操作，然后会再次重新从服务器加载a页面，并再次执行a页面中提前加载b页面的操作，如此一来就会形成一个死循环； 5) 当a页面还在加载缓存页面时，这时触发动作跳转到其他页面，则加载操作中断，即最新的url请求会中断前一个url请求；6) 假设a页面提前加载b页面，b页面提前加载c页面，那么就会形成一个加载链，即在加载a页面后会将b页面和c页面都提前加载下来，如此一来就会造成一定的混乱，尤其是当这样的加载链太长的时候。所以在使用时要事先规划好页面间加载与被加载的关系。4、 异常处理异常处理在框架页面（c_main.rsp）中集中注册，并定义好出现异常后处理代码。首先注册异常：异常的名字在Java代码中用String数组定义，在这用循环统一捕获。每个异常捕获命令的target属性都是指向一个Action,该Action用于处理出现异常后的动作，比如显示出错信息并退出系统等。5、 上传下载文件上传文件关键命令：cmd:/uploadFile参数：fileName 上传文件名 fileType 文件类型 destURL 目的url onBegin 当上传开始时调用的动作 onSuccess 当上传成功时调用的动作 onError 当上传错误时调用的动作 progressTarget 指定反应上传进度的动画 segmentSize 上传文件每个包的大小 Resume 指定传输中断后能否恢复 onResume 传输回复后调用的动作 Stop 停止传输，这个参数只能单独使用示例：下载文件：关键命令：cmd:/download主要参数：contentURL 下载内容URL contentName 下载文件名 Type 下载文件类型（Mime-Type）如“image/jpge” beginDownloadTarget 下载开始时调用的动作 endOfDownloadTarget 下载结束时调用的动作 errorDownloadTarget 下载错误时调用的动作（该错误一共有6个） totalSizeTarget 指定显示总共下载大小的text节点 actualSizeTarget 指定已经下载的大小的text节点 progressTarget 指定反应下载进度的动画示例代码：6、 发送短信关键命令：cmd:/sms参数： num 电话号码 Msg 短信内容示例代码：7、 旋转图片示例代码：Replace的target指向一个Bitmap节点，roteateVal为一个旋转弧度的浮点值。8、 图片缩放示例代码：Replace的target指向一个Bitmap节点，vec2fvalue是x，y轴的缩放比例9、 调用电话薄命令：cmd:/getContactInfo参数：phoneNumber 显示选择的手机号码的text节点示例代码：10、 手动滚动Text节点文字示例代码：11、 监控设备声音示例代码：Source值为volume，target指定一个展示音量的动画节点12、 监控电量完整代码：关联电量：电量显示动画：13、 存储本地变量设定一个存储在本地的变量，利用此命令对此变量进行设定、获取、增量、减量的操作。命令：fs_varSet；fs_varGet；fs_Add；fs_varSub示例代码：14、 强制打开背景灯命令：defaultBacklight示例：15、 调用摄像头照相命令：cameraCapture，cameraVideo、cameraStopVideo、launchCameraApplicationcmd：cameraCapture使用：此命令用于调用手机摄像头，并将照片存于本地。cmd：cameraVideo、cameraStopVideo使用：此命令用于调用手机摄像头，并将视频存于本地，cameraVideo开始摄像，cameraStopVideo结束摄像。cmd：launchCameraApplication使用：此命令用于调用手机摄像头，并可以选择是采用picture或是video模式。示例代码16、 同一个图片的多次引用如果同一个图片需要多次改变大小在不同的地方引用,图片不要多次加载.示例代码必须用同一个streamID加载.然后对17、 repace语句的应用如果repace语句不需要在某种条件下调用,直接写在auit节点中.不需要插入节点,杜绝这种写法,如图正确写法: 如果是条件调用,应该插入相应的节点中.采用上述写法.18、 图片的加载顺序,场景的渲染顺序.图片在rsp中的渲染顺序必须,必须根据场景的顺序加载,首先展示的图片,放在靠前的aunit中.图文混排的情况分多个aunit加载,必须对图片进行监听.用户优先看到文字,文字场景优先渲染.让用户感到文字和图片是异步加载的.渲染文字 加载图片渲染图片,同时对图片做监听 19、 java代码动态加载图片.int state=0; boolean isSuc