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 })