# ZWebView

**Repository Path**: chinasoft2_ohos/ZWebView

## Basic Information

- **Project Name**: ZWebView
- **Description**: 移动端和Web的JS桥接框架
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 1
- **Created**: 2021-06-07
- **Last Updated**: 2024-05-30

## Categories & Tags

**Categories**: harmonyos-advanced

**Tags**: None

## README

# ZWebView

## 项目介绍
项目名称：ZWebView

所属系列：OpenHarmony的第三方组件适配移植

功能：建立移动端和Web的JS桥接框架，实现通过容器WebView实现移动端与js的互调功能。

基线版本：master分支

项目移植状态：主功能完成

调用差异：无

开发版本：sdk6，DevEco Studio 2.2 Beta1

## 效果演示
![输入图片说明](https://gitee.com/chinasoft2_ohos/ZWebView/raw/master/ohos/img/2.gif  "2.gif")

## 安装教程
1.在项目根目录下的build.gradle文件中，
 ```
allprojects {
    repositories {
        maven {
            url 'https://s01.oss.sonatype.org/content/repositories/releases/'
        }
    }
}
 ```

2.在entry模块的build.gradle文件中，
 ```
 dependencies {
    implementation('com.gitee.chinasoft_ohos:zwebview:1.0.0')
    ......  
 }
```
在sdk6，DevEco Studio 2.2 Beta1下项目可直接运行
如无法运行，删除项目.gradle,.idea,build,gradle,build.gradle文件，
并依据自己的版本创建新项目，将新项目的对应文件复制到根目录下

## 使用说明
* Step1，初始化：
在自定义的AbilityPackage中初始化 `ZWebView`，方法如下：
```java
@Override
public void onInitialize() {
    super.onInitialize();
    ZWebInstance.init(this);
}
```

* Step2，构建 `ZWebConfig` 配置文件，并创建 `ZWeb` 对象实例。
```java
String MAIN_HTML = "xxx.html";

// 1. 创建配置文件，并带入主页 URL
ZWebConfig config = new ZWebConfig.Builder(ZWebConstant.MAIN_HTML)
    // 注册状态监听
    .setOnStateListener(this)
    // 注册原生协议UI实现
    .setNativeMethodImplement(this)
    // 注册一些特殊的实现方法
//  .setOnSpecialStateListener(this)
    // 选择注入模式
    .setInjectionMode(InjectionMode.VuePlugin)
    // 自动注入框架脚本JS（建议配置）
    .autoInjectFramework()
    // 自动注入扩展方法
    .autoInjectExtendsJS()
    // 添加 assets 中js文件注入
//  .addInjectJSAssetsFile("js/test.js")
    // 添加 raw 中js文件注入
//  .addInjectJSRawFile(R.raw.index_test)
    .build();

// 2. 创建ZWeb对象实例.
mZWebInstance = ZWebInstance.createInstance(config);

```

* Step3，传递Activity的生命周期，如下：
```java
// mRootView 为根ComponentContainer容器 （必须）
@Override
protected void onStart(Intent intent){
    //...
    mRootView = new StackLayout(this);
    mRootView.setLayoutConfig(new ComponentContainer.LayoutConfig(
                ComponentContainer.LayoutConfig.MATCH_PARENT,
                ComponentContainer.LayoutConfig.MATCH_PARENT));
    groupView.addComponent(mRootView);

    super.setUIContent(groupView);    
    //...
}

@Override
public void onBackPressed(){
    if (!mZWebInstance.onActivityBack()){
        super.onBackPressed();
    }
}

// 分别实现其他生命周期传递
@Override
protected void onActive() {
   mZWebInstance.onActivityResume();
   super.onActive();
}

@Override
protected void onInactive() {
    mZWebInstance.onActivityPause();
    super.onInactive();
}

@Override
protected void onBackground() {
    mZWebInstance.onActivityStop();
    super.onBackground();
}

@Override
protected void onStop() {
    mZWebInstance.onActivityDestroy();
    super.onStop();
}
```

* 一些内部状态监听实现

以下为实现监听状态接口时，所需要实现的方法。

```java
/**
* 框架初始化成功后回调
*
* @param zWebHandler
* @param width 宽
* @param height 高
*/
void onZWebCreated(IZWebHandler zWebHandler, int width, int height);

/**
* 异常（JS如果有异常会在这里回调）
*
* @param zWebHandler
* @param errorCode 错误码
* @param message 错误信息
*/
void onZWebException(IZWebHandler zWebHandler, long errorCode, String message);

/**
* 网络请求处理
*
* @param zWebHandler
* @param url         链接
* @param method      请求方法
* @param data        数据
* @param type        返回类型
* @param controller
*/
void onZWebRequire(IZWebHandler zWebHandler, String url, String method, String data, String type, IZRequireController controller);

/**
* 异步消息请求
*
* @param zWebHandler
* @param cmd 命令名称
* @param data 数据
*/
void onZWebMessage(IZWebHandler zWebHandler, String cmd, String data, IZMessageController controller);

/**
* JS销毁
*
* @param zWebHandler
*/
void onZWebDestroy(IZWebHandler zWebHandler);

/**
* JS日志信息回调，可在这里记录或打印
*
* @param zWebHandler
* @param type        类型
* @param msg         信息
*/
void onZWebLog(IZWebHandler zWebHandler, String type, String msg);
```

* IOC实现 js 请求方法封装

1. 定义调用JS的方法接口
```java
public interface RequireService{
    @ZMethod("a") // callReceiver
    boolean callA(@ZKey("KeyA") String a, @ZKey("KeyB") String b, @ZKey("Time") long time);

    @ZFunction("init")
    boolean init(@ZKey("A") String a, @ZKey("B") String b, @ZKey("C") int c);

    @ZMethod(ZMethodName.ON_READY)
    void initParam(@ZKey("Msg") String msg, @ZKey("Skin") int skin, @ZKey("Color") int color);

    @ZFunction(ZFunctionName.REFRESH)
    void refresh();

    @ZFunction("newInit")
    boolean newInit(@ZJson String oJson);

    @ZFunction("newInit2")
    boolean newInit2(@ZData String str);
}
```

**各种注解介绍：**
> @ZFunction("方法名称")： 用于调用JS中 `ZWebSDK.extends('方法名称', function(oData){});` 扩展方法的调用。

> @ZMethod("监听名称")：用于JS中 `ZWebSDK.on('监听名称', function(oData){});` 注册监听的方法调用。

> @ZKey("参数名称")：JS中Object参数键值名称。

> @ZCmd("cmd名称")：用于 `onZWebMessage` 方法回调中，cmd参数的映射。具体使用方法可以参考Demo。（针对Message做映射解析时使用）。

> @ZJson：JS中Object参数的字符串（json）。

> @ZData：参数为字符串。

2. 创建接口服务对象实例，并进行调用
```java
mRequireService = mZWebInstance.create(RequireService.class);
```

通过使用 `mRequireService` 提供的方法，调用JS。如下：

```java
mRequireService.callA("我是一个坚挺的消息。。。", "小A你好啊！", time);
```

* JS调用原生提供的方法

1. 使用现有的 `void onZWebMessage(IZWebHandler zWebHandler, String cmd, String data, IZMessageController controller);` 进行方法解析，并异步返回结果。

    参数 `cmd` ：定义的命令名称。

    参数 `data `： 定义的参数。

    `controller` ：可进行异步的结果返回。或者利用 `controller.parseMessage(this.mParseMessage);` 此方法进行方法解析。

2. 框架在 ZWebConfig 中提供了 `setExposedName (String exposedName);` 方法，可以扩展一个原生的接口协议名称。

    然后，利用 ` mZWebInstance.addJavascriptInterface(object);` 进行对象中的方法注入。

## 测试信息
CodeCheck代码测试无异常

CloudTest代码测试无异常

病毒安全检测通过

当前版本demo功能与原组件基本无差异

## 版本迭代
- 1.0.0

## 版权和许可信息
```
Copyright 2017 Zyao89

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
 ```