组件设计规范


此文档规定了组件的设计规范.为了保证组件的质量和用户体验,369云平台针对上传的组件拥有一套严格审核程序.

故此,请组件开发者阅读此文档.了解详细开发规范.保证组件的功能完成性和易用性.

受众


具有iOS或者Android开发经验的开发者,以及感兴趣的学习人员.

详细规范


以下为详细规范内容.点击链接可以选择章节阅读.

  • 使用文档设计规范 : 使用文档是前端开发者了解您的组件的唯一途径.

  • 组件接口设计规范 : 遵守设计规范将使您的组件层次清晰,简单明了.

  • 命名规范 : 遵守命名规范以便于前端开发者更好的理解您的组件.

  • 参数类型规范 : 遵守命名规范以便于前端开发者更好的理解您的组件.

  • 备注 : 我们还有一些忠告和建议.您可以选择阅读.

使用文档编写规范:


此文档由组件开发者书写,提供给前端开发人员阅读使用.按照以下顺序阅读即可理解书写规范.

作者:

  • 组件开发者.

受众:

  • 前端开发人员.

要求:

  • 初步敲定 :

      组件开发者在开发组件之前需要敲定本文档初稿.初步确定组件的功能,接口,参数,回调函数等内容.
    
  • 迭代修改 :

      敲定好初稿以后,组件开发者可以进行组件开发,在开发中如果发现实际开发内容与文档不符,应及时修改文档.
    
      如果是安卓和苹果开发者协同开发,应保证双方最终组件符合文档内容.
    
  • 条理清晰 :

      本文档是前端开发人员了解组件使用方法的唯一途径.因此需要文档内容有条理性,简单精炼.
    
      尽可能按照文档书写顺序调用接口即可实现组件的功能.
    
  • 格式规范 :

      文档书写有着严格的规范.文档统一编写成xml格式文件.
    
      请不要担心自己没有使用过xml的语法.因为这是非常简单易懂的.
    
      您只需要参考组件文档模板来书写您的文档就能达到要求.
    
      以下为组件文档模板的链接.点击下载.
    

请点击下载文档模板

详细规范:


在阅读以下内容之前,请您保证已经阅读了组件文档模板,并了解了文档的书写语法.接下来的内容是文档格式的详细规范.

一份完整的文档从头至尾包含以下部分.您可以点击各部分链接分模块查看规范,也可以按照顺序阅读.

目录部分:
  • 组件名称 : 定义了组件的名称.

  • 概述 : 对组件做了一些简单的描述.

  • demo目录 : 组件的演示demo,通过复制demo代码即可调用组件.一份即可.

  • 常量目录 : 罗列了组件的所有的常量值,按照值或者功能可以分组罗列.

  • 对象目录 : 罗列了一些JSON对象,这些对象一般是参数,返回值等.

  • 方法目录 : 组件所有的方法(接口)都在这里罗列,并且做简单描述.

  • 回调函数目录 : 组件所需要的回调函数,都在这个目录里,并且有简单描述

  • 相关操作目录 : 针对组件的代码外的一些操作,比如说填写配置文件,申请appKey的图文流程等.

内容部分:

点击下载实际文档案例

组件名称:


命名您的组件名称,要保证您在文档中命名的组件名称与前端对象名称一致.

例如:plugin.xml文件中的"domain"所指向的名字是"imageTailor",那么您的文档中的组件名称就是"imageTailor"

概述:


对您的组件进行简单的描述.有以下要求:

    1.概述组件基本功能.

    2.代码外是否需要其他配置.

    3.是否需要第三方appKey,appSecret等.

    4.使用注意事项简单描述.

demo目录:


demo目录里一般只有一个链接,点击跳转到"demo详细内容",前端开发者可以复制demo来运行组件.预览组件功能.

常量目录:


常量目录里罗列了本组件所有的常量,这些常量可能是一些错误状态值,分类等.

    1.可以按照常量的不同功能分组罗列.这就意味着您的文档里可以有多个常量目录.

    2.常量可以是Number类型,String类型,或者是JSON对象.

    3.没有常量时,此目录可以取消.

例如图片所示:

image

对象目录:


组件的参数中可能会用到一些JSON对象格式的参数,或者某个方法(接口)的返回值是一个JSON对象.

    1.这些JSON对象格式的参数需要详细的描述,便于开发者构建或者解析此类对象.

    2.没有对象时,此目录可以取消.

例如图片所示:

image

方法目录:


组件的所有方法(接口)都在这个目录里.每个方法(接口)都有一句简单的描述.

    1.只要显示方法(接口)名称即可,详细参数和使用方法将在"方法详细描述"中体现.

    2.请尽量按照组件的调用顺序来排列方法(接口),前端开发者只要按照顺序调用方法就能启动组件.

例如图片所示:

image

回调函数目录:


组件接口返回参数有两种方式,一种是同步返回,另一种是异步回调.这就涉及到了回调函数的使用,回调函数目录中罗列了组件所需要的所有回调函数.
    1.在目录中简单描述每个回调函数的作用,被用作那个方法(接口)

    2.如果没有回调函数此目录可以取消.

例如图片所示:

image

相关操作目录:


您的组件在以上方法以外可能还需要进行其他操作,这些操作您可以指定一个目录.
比如需要在配置文件中添加URLScheme白名单,或者是申请第三方SDK的appKey等.

    1.制定每种操作的目录,详细操作配置方法将在"详细描述"中体现.

    2.如果没有可以取消此目录.

例如图片所示:

image

demo详细内容:


点击"demo目录"中的链接,跳转到"demo详细内容".

1.组件的演示代码"以代码格式"显示.

2.代码中添加注释,以便于更好的理解,如图:

image

3.demo要简单易懂.如下示例:

    <html>
        <head>
            <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

            <title>蓝牙传输演示Demo</title>

            <script type = "text/javascript">

                //操作回调函数  progress:进度值,0~1;data接收文件的路径,如果接收到的时字符串,直接返回字符串.
                function oprationCallBack(progress,data){
                    alert(progress +'::'+data);
                }

                //错误回调,在组件执行期间,错误统一由此返回. err:错误码.详情参阅使用手册,errCode常量目录.
                function errorCallBack(errCode){
                       alert(errCode);
                }

                //启动蓝牙  搜索域名称为"369"的伙伴设备
                function start(){
                    rd.BlueTooth.start(oprationCallBack,errorCallBack,'369');
                }

                //发送字符串
                function sendString(){
                    rd.BlueTooth.send('STRING','hello World');
                }

                //发送资源
                function sendURL(){
                    rd.BlueTooth.send('FILE','http://dzs.qisuu.com/txt/道印.txt');
                }

                //发送相册里的图片或者视频
                function sendImageOrVideo(){
                     rd.BlueTooth.send('ALBUM');
                }

                //终止传输
                function stop(){
                    rd.BlueTooth.stop();
                }

        </script>

    </head>

    <body>
        <h1 >蓝牙传输文件</h1>
            <h2  onclick ="start()">启动蓝牙</h2>
        <h2  onclick ="sendString()">发送字符串</h2>
        <h2  onclick ="sendURL()">发送资源文件</h2>
        <h2  onclick ="sendImageOrVideo()">发送图片或视频</h2>
        <h2  onclick ="stop()">停止传输</h2>
    </body>
</html>

对象详细描述:


点击对象目录中的每一条目录,即可链接到对象对应的详细描述.

    1.详细描述中要有演示代码.

    2.对象中的属性要有详细说明.包括类型说明,作用说明,可选必选,默认值.

    3.该对象要指明被那个方法作为参数使用,或者是那个方法返回的参数.

    2."对象详细描述",有固定的格式,如图所示:

image

方法详细描述:


点击方法(接口)目录中的每一条目录,即可链接到方法对应的详细描述.

    1.方法详细描述中要有演示代码.

    2.对方法要有更加细致的说明.

    3.方法所需要的参数,在参数列表中要一一说明.

    2.方法的返回值要在返回值列表中说明.

image

回调函数详细描述:


点击回调函数目录中的每一条目录,即可链接到函数对应的详细描述.

    1.回调函数详细描述中要有演示代码.

    2.对其要有更加细致的说明.

    3.若回调函数中有参数,在参数列表中要一一说明.

    4.指明此回调函数被那个方法调用.

image

相关操作详细描述:


在相关操作目录中已经提前预告读者需要做一些其他操作或者配置,读者点击目录链接即可跳转到详细描述.

    1.配置文件类操作需要有演示代码.

    2.申请流程类需要有图文演示.

    3.相关链接要在描述中体现.

    4.请定时更新相关操作流程,避免因为网站更新,导致教程与实际不符.

image

组件接口设计规范:


组件以接口形式暴露给前端开发者,供其调用来实现具体功能.因此您的组件需要遵守以下规范.

通用规范:

    1.保证您的组件都有一个回调函数.这个回调函数是异步的,可以实时返回当前组件的状态,比如说初始化成功,当前路径错误等,便于前端开发者实时跟踪组件状态.

    2.您的组件会被很多前端开发者调用,保证您的组件拥有良好的兼容性和全面性.让前端开发者调用组件实现功能时可以有更多的选择.

    3.确定您的组件的作用域,如果您的组件是UI类型的,一般作用域为createNew,如果您的组件是全局的,一般作用域为app.详情请参阅<组件作用域>

    4.您的组件内容不可以有恶意代码和广告嵌入.

    5.您的组件内容不可以有违反国家法规的内容.比如情色内容,赌博讯息.

    6.在保证良好的兼容性同时,请您保证每个接口不要过于复杂冗余.您可以通过多个接口来拆分一个复杂的功能.降低前端开发者的使用难度.

    7.如果通过您的组件可以生成更多的前端对象,您要保证这些前端对象是可控的,您可以通过分配id的方式来管理这些对象.

UI组件:

    1.如果您开发的组件带有UI界面.那么您必须要实现setFrame,show,hide,remove,isShowing五个方法.
    以下为五个方法的详细描述.

    1.1.setFrame:
        设置视图的坐标及尺寸.参数格式固定:{x:0,y:0,width:0,height:0}.
    1.2.show:
        显示视图.
    1.3.hide:
        隐藏视图.再次调用show()方法可以显示原视图.
    1.4.remove:
        移除视图.此时组件已经销毁.若想再次显示,需要重新初始化组件.
    1.5.isShowing:
        是否处于显示状态.返回值为布尔类型.

    2.当组件的宽度和高度设置为0时,代表撑满屏幕.这里iOS开发者需要做处理.

    3.可自定义的图片文字等元素,需要有占位图片和文本.

    4.可自定义的颜色需要支持8进制和16进制颜色. 

第三方组件:

    1.如果您开发的组件是对第三方组件的封装或者扩展,在组件命名时请您包含第三方SDK的名称.

    2.对于接口复杂的第三方SDK,请尽量精简接口数量和复杂度.给前端开发者呈现一个简单易用的组件.

    3.组件所需要用到的第三方appKey,appSecret等,需要在文档中详细介绍申请流程.如果可以,请您在文档中留一份可用的appKey.

    4.建议您定期更新第三方的SDK库,保证您的组件实时更新.

功能性组件:

    1.如果您开发的组件是功能性为主的组件.在接口命名时要保证通俗易懂.

    2.及时与前端开发者达成交互,及时通过回调函数或者返回值来返回组件的工作结果.

文件路径:

    1.如果您开发的组件涉及到了文件的存储读取等相关操作.应当支持协议路径.详细协议路径请您点击以下<附件链接>.

    2.对于从网络获取资源的组件,需要同时支持http和https访问.

    3.请做好图片,音频等资源的缓存处理.避免不必要的网络请求.

    4.您的组件要有清理本地缓存的接口.避免本地垃圾堆积,影响用户体验.

错误处理:

    1.如果您期望通过回调函数或者返回值来返回一些错误描述.请您先预定义好错误码,并将其作为常量书写在使用文档.
    这样可以方便前端开发人员及时了解错误内容.

    2.良好的错误描述可以使前端开发者准确的定位他的调用错误.而不是放弃您的组件.

    3.您的组件需要保证良好的容错性,保证在传参错误的情况下,及时通过回调函数提醒前端开发者,避免出现崩溃现象.

组件命名规范:


组件以接口形式暴露给前端开发者,供其调用来实现具体功能.良好的命名可以让前端开发人员更容易理解您的接口,因此您的组件需要遵守以下命名规范.

总览:

    1.命名法则: 驼峰命名法则.

    2.简单易懂: 英文单词为主,不要过长,例如  citySelector(城市选择器)  baiduLocation(百度定位) setFrame(设置坐标尺寸).

    3.功能提示: 根据名称可以推断出基本功能.

组件本身命名:

    1.原生组件,名称要突出基本功能.比如citySelector(城市选择器), barcode(二维码).

    2.第三方sdk封装的组件,要尊重第三方名称,可以适当修改,缩写, 例如 baiduMap(百度地图),BDMap(百度地图),XGPush(信鸽推送),
    xinGePush(信鸽推送).

    常用示例:

    浏览类 --- photoBrowser(图片浏览器)

    推送类 --- baiduPush(百度推送)

    支付类 --- aliPay(阿里支付)

    地图类 --- baiduMap(百度地图)

    播放类 --- videoPlayer(视频播放器)

    功能类 --- zip(压缩)  imageTailor(图片裁剪)

    列表类 --- cityList(城市列表)

    选择类 --- citySelector(城市选择)

接口命名:

    1.如果您开发的组件带有UI界面.那么您必须要实现setFrame,show,hide,remove,isShowing五个方法.
    这些方法是带有UI组件的统一方法.目的是便于前端开发人员的调用.

    2.望文知义,接口命名要简短精炼,通过接口名称一般即可推断出此接口的具体功能.不要定义没有意义的接口名称,例如abc(),ddd().

    3.接口的开关性,某些功能具有开关性,例如start()--end(); play()----stop(); login()---logout().

    4.避免与前端关键字重复,以免前端开发者对接口的理解产生混淆.

        常用示例:

        启动接口 --- init(),start()

        登录接口 --- login(), logout()

        显示接口 ---  show(), hide()

        取值接口 --- getDuration()

        添加接口 --- addClickListener()

        设置接口 --- setStyle()

        生成接口 ---  createCode()

        捕获接口 --- captureImage()

        开启接口 ---  openWindow()

        删除接口  --- deleteDataBase()

        选择接口   --- selectAll()

        功能接口  --- dial()

参数/常量命名:

    1.遵守通用性原则,常用参数一般都具有通用性,例如 width, height ,titleColor,url,bgColor.

    2.布尔值,布尔值建议遵守前端语法,使用true和false.

    3.后缀统一,一般颜色统一以Color为后缀,尺寸以Size为后缀.

        常用后缀示例:

        颜色 -- **Color

        尺寸 -- **size

        字体 -- **Font

        图片 -- **Img

        路径 -- **path

        资源 -- **URL,URI

        类型 -- **Type

        回调 -- **Callback

        错误 -- **Error

        状态 -- **State

        标题 __ **Title

    4.如果单个方法参数过多,建议分拆成多个方法或者将参数封装成JSON对象整体作为参数传参.

    5.JSON对象类型的参数要符合JSON规范,格式错误的JSON对象会导致参数无法解析.

    5.常量建议采用大写字母方式来命名.

        常用示例:

        标题字体 -- titleFont

        背景颜色 -- bgColor

        启动图片 -- startImg

        文件路径 -- filePath

        图片资源 -- imgURL

        列表尺寸 -- listSize

        当前状态 --  currentType

        列表标题 -- listTitle

回调函数命名:

        1.建议统一以**Callback作为后缀.

        2.回调函数中的参数如果过多,建议封装为JSON对象,作为整体返回.

        常用示例:

        成功回调函数 --- successCallback()
        失败回调函数 --- errorCallback(errCode)
        操作回调函数 --- operationCallback(stateCode)

参数类型规范:

    组件的作用是提供给前端开发者来调用,所以,组件的参数定义及返回,都要严格遵守前端JS语言的规范.否则会导致前端解析出错的问题.

    1.要注意区分String类型和Number类型的参数.如果可以,要做到彼此兼容.

    2.要注意区分Bool类型和String类型,如果可以,要做到彼此兼容.

    3.应该避免用Number类型值来替代Bool类型,同理,字符串类型也要尽量避免混用.

    4.为了明确参数类型,在定义参数时,要在文档中明确定义参数的具体类型.

    5.JSON对象格式的参数,如果过于复杂,要保证返回给前端的JSON对象符合Json规范.避免发生无法解析的问题.

备忘:

    为了营造和谐共享的完美云生态体系,请进遵守以下约定.

    1.代码内容遵守中华人民共和国相关法律.

    2.不宣扬封建迷信以及恐怖主义.

    3.不侵犯他人合法著作权.

    4.不恶意上传垃圾组件.

    5.您可以将您的宝贵意见通过平台发送给客服,我们将不胜感激.