Html容器机制说明

目录
 
1.设计概要                                                                                                                           3

2.MyWebChromeClient（Html基础支撑）                                                                  4

    1）ApiEx扩展（WebChromeClient + Js基础机制）                                         4

         CallbackController                                                                                             5

    2）窗口响应                                                                                                                5

    3）返回机制                                                                                                                5

    4）文件选择响应                                                                                                        5

    5）标题响应                                                                                                                5

    6）日志拦截                                                                                                                6

3.WebViewClient                                                                                                               6

    1）orange.js                                                                                                                6

    2）文件服务                                                                                                                6

4.HtmlSettings初始化设置                                                                                                6

    1）HtmlPackageCertificateFile                                                                                  6

    2）HtmlPackageList                                                                                                   6

    3）AccessibleAddressList                                                                                        6

    4）HttpsCertificateFileList                                                                                         6

5.ApiExController(ApiEx基础机制)                                                                                 7

    1）ApiExController                                                                                                    7

    2）ApiExRequest                                                                                                      7

    3）ApiExParams                                                                                                        8

    4）ApiExResult                                                                                                          8

    5）ApiEx                                                                                                                     8

    6）Exception                                                                                                               8

6.ApiEx基础扩展                                                                                                               9

    1）HttpClient                                                                                                              9

    2）Preference                                                                                                             9

    3）TitleBar                                                                                                                   9

          TitleBarView                                                                                                  10

    4）Toast                                                                                                                    10

    5）Photo                                                                                                                   11

7.ApiEx扩展：Auth(用户、登陆授权)未实现                                                              12

 

1.设计概要

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

2.MyWebChromeClient（Html基础支撑）

    1）ApiEx扩展（WebChromeClient+ Js基础机制）

         通过WebChromeClient.onJsPrompt()方法拦截特定格式的message，调用指定的本地Java方法，Js通过prompt触发该逻辑。

 

         1.使用这种方式的原因纪录：

            a）基于WebView.addJavascriptInterface()的Js扩展方式存在安全漏洞，在Android4.2以下，Js可通过反射机制调用任意本地代码（CVE-2012-6636）

            b）基于Url拦截的方式（WebViewClient.shouldOverrideUrlLoading()）难以实现同步Js方法

 

         2.Message特定格式（orange://type/method?param1=1¶m2=2 ），其中

            type：扩展对象，例如Toast

            method：对象方法，例如makeToast

            queryString：方法参数，例如text=Hello Me&duration=0

 

         3.Message必须：

            合法的url格式

               以orange://开头

               包含非空的Authority部分，作为type

               包含唯一的path segment，作为method

            否则会被忽略而调用默认的onJsPrompt实现，即弹出输入对话框

 

         4.方法参数：

            只支持Int，String，Bool，null

            必须进行encode()处理

            忽略无效参数

            对于null参数，不应传入参数字段

 

           5.返回值

            返回值会以合法的Js变量的字符串形式返回，Js可通过eval()方法获得相应值

            支持Int，String，Bool，null，简单的key-value对象

               如果找不到指定的Type或Method，或提供参数不合法，则返回“undefined”

 

         6.异步函数

            方法的异步性取决于本地Java的具体实现，Js可通过在queryString中传入callback参数，获取方法的结果回调，callback在具体Js函数中说明

 

         7.Js部分

            orangewealth.js文件提供对机制调用的封装，包括基础接口exec()和具体的功能函数，具体查看源码注释

 

         CallbackController

         对于函数中的回调接口传递，通过js中的CallbackController对象管理，源于可在java代码中简单的定位回调函数，尤其是inner function类型的回调

           a.通过CallbackController.addCallback(callback)将回调函数加入到Controller中，返回值为管理key值

           b.将key值传递到相应的接口中

           c.如果回调函数为inner function，则不能从外部传递回调参数，需在函数体中使用this.params获得回调参数列表

    2）窗口响应

          a）对Html中<a>标签的target=‘_black’属性，或window.open(url, ‘_blank’)的支持

               通过WebChromeClient.onCreateWindow()，在新Activity中打开指定的Html页面，以实现和浏览器上一致的机制

          b）对window.close()的支持

                通过WebChromeClient.onCloseWindow()，关闭当前Activity，以实现和浏览器上一致的机制

    3）返回机制

          a）不支持setNotice()方法

          b）标题栏左端无“菜单”与“返回”相互变换的逻辑，替代方案是使用（2）方案新建窗口打开指定页面

          c）对于单页面Html，可使用H5的history.pushState()，popstate事件监听的方式处理跳转逻辑

          d）在新打开的Activity中，原生代码通过canGoBack()和goBack()方法处理返回逻辑

    4）文件选择响应

          对于Html中type＝’file’的<input>标签，通过WebChromeClient.openFileChooser(<5.0)和WebChromeClient.onShowFileChooser(>=5.0)，处理文件选择逻辑，以实现和浏览器上的一致

          <5.0的系统中，不知持capture属性

          >=5.0的系统中，capture属性行为不确定

          ps：当前的实现是直接使用系统或第三方App做文件选择，可以考虑实现自身的选择程序

                当前只处理image/*类型的选择

    5）标题响应

          通过WebChromeClient.onReceivedTitle()拦截Html文件中<title>标签的变更，显示在标题栏上，一实现和浏览器上的一致

          ps：通过赋值document.title和TitleBar.setTitle()的方式都可设置标题栏，但两种方法的混合使用会产生不一致性，不要同时使用这两种方式

   6）日志拦截

           通过WebChromeClient.onConsoleMessage()拦截Js中console.log()等日志输出，如果日志以“ApiEx$”开始，则其之后的内容将从Logcat输出，并使用“ApiEx.JS”作为TAG

 

 

 

3.WebViewClient

   1）orange.js

         可通过orange:///orange.js获取接口js文件

    2）文件服务

            通过orange:///file?key=file_key的方式，获取制定文件的输入流，其中key_file通过Photo等ApiEx接口返回获得

 

 

4.HtmlSettings初始化设置

    1）HtmlPackageCertificateFile

          H5更新验证证书，指向assets下的文件，证书必须通过OrangeColor CA的签名

    2）HtmlPackageList

         初始化H5Package，用于加载assets下的h5源码数据

    3）AccessibleAddressList

         H5可访问的服务器列表

    4）HttpsCertificateFileList

         建立Https所信任的证书，指向assets下的文件，证书必须通过OrangeColor CA的签名

 

 

 

 

 

 

 

 

 

 

 

5.ApiExController(ApiEx基础机制)

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

   1）ApiExController

          ApiEx扩展控制器，用于统一管理ApiEx扩展

          init：构造函数中初始化了基础类型的ApiEx扩展，例如Toast、TitleBar等

          addApiEx：加入新的ApiEx扩展，用于另外的扩展模块，例如Payment、Auth

                   实现细节：可通过HtmlFragment.getApiExController获取控制器

          requestApiEx：请求入口，传入调用参数，返回ApiExResponse，或抛出异常

                   实现细节：方法用@NonNull标识，要求返回值不为null

          destroy：释放控制资源

                   实现细节：ApiExController使用维护后台工作线程，ApiEx扩展可通过workingHandler执行异步任务，所以必须主动调用释放方法

    2）ApiExRequest

          请求对象，定位ApiEx请求

          type：扩展对象

          method：扩展方法

          params：ApiExParams对象，包含请求参数

          callback：异步方法的回调函数（或对象），相当于params.getStringParam(‘callback’)

   3）ApiExParams

          请求参数，基于key-value逻辑的参数封装

          其中value只支持简单的Int、String、和Bool值

    4）ApiExResult

          请求结果，支持null，整型，Bool，字符串，简单的key-value对象

          getJsString：返回结果的合法Js格式文本字符串，用于将结果返回到Js模块

    5）ApiEx

          ApiEx扩展基类，封装基本机制，子类需提供具体的逻辑实现

                   实现细节：ApiEx可用运行以下对象

                            fragment：当前HtmlFragment引用

                            mainHandler：主线程Handler

          invoke：处理ApiExRequest，子类必须实现具体的调用逻辑，默认实现抛出异常

                   实现细节：

                   a）ApiExController中是用Map方式维护调用导航

                   b）invoke方法使用@NonNull标识，确保返回值不为null

          checkParamsAvailed：便捷函数，用于测试参数是否可用

          ApiEx.OnActivityResultListener：用于ApiEx获取onActivityForResult的结果

                   实现细节：可通过HtmlFragment.setOnActivityResultListener方法设置结果获取逻辑

   6）Exception

          ApiExTypeNotFoundException：找不到指定的type

          ApiExMethodNotFoundException：对于type对象，找不到method方法

          ApiExIllegalArgumentException：却少必要参数，或参数类型不合法

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

6.ApiEx基础扩展

    1）HttpClient

          提供http基础访问接口，用于js获取json数据

          实现细节：由于Html源码的管理、升级机制，本地Html中的js不能直接访问网络，而必须通过HttpClient做网络访问

          a）request：一般访问接口，服务器返回被解析为字符串

                   url：请求地址

                   method：http方法，HEAD，GET，POST，PUT，DELETE

                   timeout：连接超时时长，毫秒，默认为30000

                   header：http请求头部

                   data：http负载，字符串类型

                       succeed：成功回调，回调参数为服务器返回负载，字符串类型

               failed：失败回调，回调参数为(code，message)，皆为字符串类型

                   noCache：是否使用缓存

            b）uploadImage：上传图片

                        key：文件key，参看文件服务

                   url：上传的url

                   compress：压缩比率，0-100

                   succeed：成功回调，参数(0)

                   failed：失败回调，参数(code，message)

                   progress：进度回调，参数(progress)

    2）Preference

          对应于Android系统的SharedPreferences，存储基本的key-value数据

          a）putValue：存入数据

                   key：数据key

                   value：数据值

                   domain：数据所属域，默认DEFAULT

          b）getValue：读取数据

                   key：数据key

                   domain：数据所属域，默认DEFAULT

                   返回值，或null

          实现细节：数据会以字符串方式存储和读取

    3）TitleBar

          导航栏控制组件，包括标题、返回、左菜单、右菜单

 

 

 

 

 

 

 

 

 

          a）setTitle：设置标题

                   title：标题文字

          b）setTitleColor：设置标题颜色

                   colorString：颜色字符串，#AARRGGBB，#RRGGBB，null设为默认(BLACK)

          c）setBackgroundColor：设置导航栏背景颜色

                   colorString：颜色字符串，#AARRGGBB，#RRGGBB，null设为默认(WHITE)

          d）setBackgroundImage：设置导航栏背景图片

                   imgFile：图片绝对路径

          e）setRightItem：设置右菜单

                   imgFile：图标绝对路径，如果为null，则显示文本

                   text：说明文本，图标为null，则显示在标题菜单

                   callback：点击回调函数名，回调无参数，如果imgFile和text均为null，则被忽略

          实现细节：如果imgFile和text均为null，则菜单被自动设为隐藏状态，否则，菜单被自动设置为可见

          TitleBarView

                   实现导航栏的自定义View控件

                   样式控制，详见res/values/attrs_view_title_bar.xml

                            android:layout_height：高度控制，默认56dp

                            android:background：背景控制，颜色、图片

                             app:title：标题

                            app:titleColor：标题颜色

                            app:backIcon：返回按钮

                            app:leftMenuIcon：左菜单图标

                            app:rightMenuTextColor：右菜单文字颜色

                            app:mode：导航模式

                                     normal：显示菜单

                                     navigation：显示返回

   4）Toast

          对应于Android中的Toast调用

          a）makeText：显示Toast

                   text：需要显示的文本

                   duration：显示时长，0：短，1：长

          实现细节：如果duration为其他数值，则当作0值处理

   5）Photo

         图片选择、拍照接口

         a）pick：选取图片

                   onSucceed 成功回调, 回调参数:

                            key:图片引用key, 用于访问图片, js不能直接获取图片的路径信息

                            width: 图片宽度

                                height: 图片高度

                                size: 图片大小,单位字节

                       onCanceled 取消回调, 无回调参数

                       onError 错误回调, 回调参数:

                        code: 错误代码

                            message: 错误描述

         a）capture：拍照

                   onSucceed 成功回调, 回调参数:

                            key:图片引用key, 用于访问图片, js不能直接获取图片的路径信息

                            width: 图片宽度

                                height: 图片高度

                                size: 图片大小,单位字节

                       onCanceled 取消回调, 无回调参数

                       onError 错误回调, 回调参数:

                        code: 错误代码

                            message: 错误描述

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

7.ApiEx扩展：Auth(用户、登陆授权)未实现