finclip-js-sdk

web-view 网页中可使用 finclip-js-sdk 提供的接口与小程序/APP 进行交互

支持的接口有：

| 接口名称 | 说明 | 最低版本 | | --- | --- | --- | | ft.miniProgram.navigateTo | 参数与小程序接口一致 | 1.0.0 | | ft.miniProgram.navigateBack | 需要delta参数 | 1.0.0 | | ft.miniProgram.switchTab | 参数与小程序接口一致 | 1.0.0 | | ft.miniProgram.redirectTo | 参数与小程序接口一致 | 1.0.0 | | ft.miniProgram.reLaunch | 参数与小程序接口一致 | 1.0.0 | | ft.miniProgram.postMessage | 向小程序发送消息，会在特定时机（小程序后退、组件销毁、分享）触发组件的message事件 | 1.0.0 | | ft.miniProgram.getEnv | 获取当前环境 | 1.0.0 | | ft.miniProgram.downloadFile | 下载文件 | 1.0.0 | | ft.miniProgram.openDocument | 打开文件 | 1.0.0 | | ft.miniProgram.chooseImage | 拍照或上传 | 1.0.1 | | ft.miniProgram.getLocalImgData | 获取图片 base64 | 1.0.9 | | ft.miniProgram.close | 关闭小程序 | 1.0.3 | | ft.miniProgram.navigateToMiniProgram | 跳转小程序 | 1.0.4 | | ft.miniProgram.navigateBackMiniProgram | 返回上一个小程序 | 1.0.4 | | ft.miniProgram.onShow | 小程序 onShow 事件注册回调 | 1.0.6 | | ft.miniProgram.onHide | 小程序 onHide 事件注册回调 | 1.0.8 | | ft.miniProgram.onUnload | 小程序 onUnload 事件注册回调 | 1.0.8 | | ft.miniProgram.getStorage | 参数与小程序接口一致 | 1.0.9 | | ft.miniProgram.setStorage | 参数与小程序接口一致 | 1.0.9 | | ft.miniProgram.removeStorage | 参数与小程序接口一致 | 1.0.9 | | ft.miniProgram.clearStorage | 参数与小程序接口一致 | 1.0.9 | | ft.miniProgram.getStorageInfo | 参数与小程序接口一致 | 1.0.9 | | ft.miniProgram.canGoBack | 当前 H5 页面是否可返回上一页 | 1.2.0 | | ft.miniProgram.canNavigateBack | 当前小程序页面是否可返回上一页 | 1.2.0 | | ft.miniProgram.setNavigationBarTitle | 设置当前小程序页面 title | 1.2.0 | | ft.miniProgram.getAppletInfo | 返回当前小程序基础信息 | 1.0.0 | | ft.miniProgram.request | 发起网络请求，参数与小程序接口一致 | 1.3.9 |

示例代码

ft.miniProgram.navigateTo({url: '/path/to/page'})
ft.miniProgram.reLaunch({url: '/path/to/page'})
ft.miniProgram.postMessage({ data: 'foo' })
ft.miniProgram.postMessage({ data: {foo: 'bar'} })
ft.miniProgram.getEnv(function(res) { console.log(res.env) }) // miniprogram
// 判断环境的另一个方法
window.__fcjs_environment === 'miniprogram'
ft.miniProgram.downloadFile({ 
    url,
    header,
    timeout,
    filePath
})
ft.miniProgram.openDocument({ 
    filePath,
    fileType
})
ft.miniProgram.chooseImage({
    count: 1, // 默认9
    sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，默认二者都有
    sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
    success: (res) => {
        console.log(res);
    }
})
// 同步方式判断当前H5运行环境
console.log(window.__fcjs_environment) // miniprogram
// 关闭小程序
ft.miniProgram.close()
ft.miniProgram.navigateBackMiniProgram({
    extraData: {},
    success: function (res) {
        console.log('navigateBackMiniProgram success callback:');
        console.log(res);
    }
});
ft.miniProgram.navigateToMiniProgram({
    appId: '',
    success: function (res) {
        console.log('navigateToMiniProgram success callback:');
        console.log(res);
    }
});
// 获取当前 H5 页面是否可以返回上一页
ft.miniProgram.canGoBack({
    success: function (res) {
        console.log(res);
    }
});
// 获取小程序是否可以返回上一页
ft.miniProgram.canNavigateBack({
    success: function (res) {
        console.log(res);
    }
});
// 设置小程序页面 title
ft.miniProgram.setNavigationBarTitle({
    title: 'page title'
});

window.ft.miniProgram.onShow((res)=>{
    console.log(res)
    // res.data表示当前小程序路由query
})
window.ft.miniProgram.onHide((res)=>{
    // Do Some Thing
})
window.ft.miniProgram.onUnload((res)=>{
    // Do Some Thing
})
window.ft.miniProgram.getAppletInfo({
    success: (res) => {
        console.log('getAppletInfo',res);
        // {
        //     appAvatar = "小程序图标地址";
        //     appDescription = "小程序的描述信息";
        //     appId = "小程序id";
        //     path = "点击转发时的小程序页面路径";
        //     appThumbnail = "小程序封面图的路径，可能是网络路径或者本地路径，宽高比是5:4";
        //     appTitle = "小程序名称";
        //     userId = "小程序开发者id";
        // }
    }
})
window.ft.miniProgram.chooseImage({
    count: 1, // 默认9
    sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，默认二者都有
    sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
    success: (res) => {
      console.log(res);
      window.fc.miniProgram.getLocalImgData({
        path: res.tempFilePaths[0],
        success: (res) => {
          console.log(res)
        }
      })
    }
})

window.ft.miniProgram.request({
    url: 'https://some.url',
    method: 'GET',
    data: {
      param1: 'test'
    },
    success: function (res) {
      console.log('success', res)
    },
    fail: function (res) {
      console.log('fail', res)
    },
    complete: function (res) {
      console.log('complete', res)
    }
})

2. FinClip 特有接口

| 接口名称 | 说明 | 最低版本 | | --- | --- | --- | | window.ft.miniProgram.callNativeAPI | H5页面调用原生api | 1.4.1 | | window.ft.miniProgram.registNativeAPIHandler | 注册原生调用H5中的api | 1.4.1 | | window.ft.miniProgram.onWebviewEvent | 监听小程序发送的事件 | 1.4.1 | | window.ft.miniProgram.offWebviewEvent | 移除监听小程序发送的事件 | 1.4.1 | | window.ft.miniProgram.sendWebviewEvent | 触发 webview 标签绑定的 bindevent 方法 | 1.4.1 |

2.1 H5页面调用原生api

示例接口名：js2AppFunction

2.1.1 iOS 示例

[[FATClient sharedClient] fat_registerWebApi:@"js2AppFunction" handle:^(id param, FATExtensionApiCallback callback) {
        NSString *name = param[@"name"];
//        id params = param[@"data"];
        if ([name isEqualToString:@"getLocation"]) {
            // 执行定位逻辑
            
            // 返回结果给HTML
            NSDictionary *dict = @{@"errno":@"403", @"errmsg":@"无权限", @"result": @{@"address":@"广东省深圳市南山区航天科技广场"}};
            callback(FATExtensionCodeSuccess, dict);
        } else if ([name isEqualToString:@"getColor"]) {
            // 执行其他逻辑
            
            // 返回结果给HTML
            NSDictionary *dict = @{@"r":@"110",@"g":@"150",@"b":@"150"};
            callback(FATExtensionCodeSuccess, dict);
        }
    }];

2.1.2 Android 示例

api示例

public class WebApi extends BaseApi {


    public WebApi(Context context) {
        super(context);
    }

    @Override
    public String[] apis() {
        return new String[]{"js2AppFunction"}; //api名称
    }

    @Override
    public void invoke(String event, JSONObject param, ICallback callback) {
        // 调用方法时原生对应的操作
    }
}

Kotlin

FinAppClient.extensionWebApiManager.registerApi(WebApi(this))

Java

FinAppClient.INSTANCE.getExtensionWebApiManager().registerApi(new WebApi(this));

2.1.3 html 示例

在HTML内引用我们的桥接JSSDK文件，即可调用上面的注册的方法了。HTML内调用注册的方法示例：

window.ft.miniProgram.callNativeAPI('js2AppFunction', {name:'getLocation'}, (result) => {
    console.log(result)
});

2.2 原生调用html中的方法

示例接口名：app2jsFunction

2.2.1 iOS 中 API

原生端调用如下API来调用HTML中的JS函数：

NSString *jsonParams = @""; //这里应该是参数字典转换成的json字符串。
NSNumber *pageId = @(1234); //这里是HTML中传过来的pageId
[[FATClient sharedClient] fat_callWebApi:@"app2jsFunction" paramString:jsonParams pageId:pageId handler:^(id result, NSError *error) {
        
}];

2.2.2 Android 中 API

/**
 * 原生调用JS函数
 *
 * @param appId 小程序id
 * @param funcName JS函数名
 * @param funcParams JS函数参数
 * @param webViewId WebView的id
 * @return 函数调用结果，以[Single]<[String]>的形式返回
 */
fun callJS(appId: String, funcName: String?, funcParams: String?, webViewId: Int): Single<String?>

调用示例Kotlin

FinAppClient.appletApiManager.callJS("appId", "app2jsFunction", "funParams", 1)
        .subscribeOn(Schedulers.io())
        .observeOn(AndroidSchedulers.mainThread())
        .subscribe({
            context.toast("callJs successfully : $it")
        }) { Log.d(TAG, "callJs failed : ${it.localizedMessage}") }

Java

FinAppClient.INSTANCE.getAppletApiManager().callJS("appId", "app2jsFunction", "funParams", 1)
        .subscribeOn(Schedulers.io())
        .observeOn(AndroidSchedulers.mainThread())
        .subscribe(
                result -> Toast.makeText(context, "callJS successfully : " + result, Toast.LENGTH_SHORT).show(),
                throwable -> Toast.makeText(context, "callJS failed : " + throwable.getLocalizedMessage(), Toast.LENGTH_SHORT).show()
        );

2.2.3 html 中 API

同样的HTML中引用桥接用的JS文件，然后在HTML里注册好方法，比如方法名叫app2jsFunction。

window.ft.miniProgram.registNativeAPIHandler('app2jsFunction', function(res) {
    // app2jsFunction callback
})

2.3 H5 页面发送事件给小程序

2.3.1 H5

// H5 页面
window.ft.miniProgram.sendWebviewEvent({
  test: 123
})

2.3.2 小程序

逻辑层

// 小程序 /pages/index/index.js
Page({
  onEvent(e) {
    console.log(e.detail.test) // 123
  },
})

视图层

<!-- 小程序 /pages/index/index.fxml -->
<web-view src="https://xxx.xxx" bindevent="onEvent"></web-view>

2.4 小程序发送事件给 H5 页面

2.4.1 H5

function onEvent(e) {
  console.log(e.test) // 123
}
// 注册监听
window.ft.miniProgram.onWebviewEvent(onEvent)
// 移除监听
window.ft.miniProgram.offWebviewEvent(onEvent)

2.4.2 小程序

ft.sendWebviewEvent({ test: 123 })