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&param2=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：拍照