# 接口说明

# 1. 相关接口

web-view 组件加载的网页中可使用JSSDK 1.4.11 (opens new window), JSSDK 1.4.11(ESM) (opens new window)提供的接口调用小程序相关能力

支持的接口有:

接口名称 说明 最低版本
ft.miniProgram.navigateTo 参数与小程序接口一致 1.0.0
ft.miniProgram.navigateBack 需要 delta 参数,不传则为 1 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.close 关闭小程序 1.0.3
ft.miniProgram.navigateToMiniProgram 跳转小程序 1.0.4
ft.miniProgram.navigateBackMiniProgram 返回上一个小程序 1.0.4
ft.miniProgram.onWebviewEvent 监听小程序发送的事件 1.4.1
ft.miniProgram.offWebviewEvent 移除监听小程序发送的事件 1.4.1
ft.miniProgram.sendWebviewEvent 触发 webview 标签绑定的 bindevent 方法 1.4.1
ft.miniProgram.onShow 小程序 onShow 事件注册回调 1.0.6
ft.miniProgram.onHide 小程序 onHide 事件注册回调 1.0.8
ft.miniProgram.onUnload 小程序 onUnload 事件注册回调 1.0.8
ft.chooseImage 拍照或上传 1.0.1
ft.getLocalImgData 获取图片 base64 1.0.9
ft.getLocation 获取当前地理位置信息 1.0.9
ft.chooseLocation 打开地图位置 1.0.9
ft.downloadFile 下载文件 1.0.0
ft.openDocument 打开文件 1.0.0
ft.getAppletInfo 返回当前小程序基础信息 1.0.0
ft.getStorage 参数与小程序接口一致 1.0.9
ft.setStorage 参数与小程序接口一致 1.0.9
ft.removeStorage 参数与小程序接口一致 1.0.9
ft.clearStorage 参数与小程序接口一致 1.0.9
ft.getStorageInfo 参数与小程序接口一致 1.0.9
ft.canGoBack 当前 H5 页面是否可返回上一页 1.2.0
ft.canNavigateBack 当前小程序页面是否可返回上一页 1.2.0
ft.setNavigationBarTitle 设置当前小程序页面 title 1.2.0
ft.request 发起网络请求,参数与小程序接口一致 1.3.9
ft.callNativeAPI H5 调用原生方法 1.4.1
ft.registNativeAPIHandler 注册 H5 方法供原生调用 1.4.1
ft.complete 发送加载完成事件到小程序 1.4.11

# 部分 API 调用示例代码

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
// 同步方式判断当前 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)
  }
})

ft.miniProgram.onShow(res => {
  console.log(res)
  // res.data表示当前小程序路由query
})

ft.miniProgram.onHide(res => {
  // Do Some Thing
})

ft.miniProgram.onUnload(res => {
  // Do Some Thing
})

ft.downloadFile({
  url,
  header,
  timeout,
  filePath
})

ft.openDocument({
  filePath,
  fileType
})

ft.chooseImage({
  count: 1, // 默认9
  sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图,默认二者都有
  sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机,默认二者都有
  success: res => {
    console.log(res)
  }
})

ft.getAppletInfo({
  success: res => {
    console.log('getAppletInfo', res)
    // {
    //     appAvatar = "小程序图标地址";
    //     appDescription = "小程序的描述信息";
    //     appId = "小程序id";
    //     path = "点击转发时的小程序页面路径";
    //     appThumbnail = "小程序封面图的路径,可能是网络路径或者本地路径,宽高比是5:4";
    //     appTitle = "小程序名称";
    //     userId = "小程序开发者id";
    // }
  }
})
ft.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)
      }
    })
  }
})

// 获取当前 H5 页面是否可以返回上一页
ft.canGoBack({
  success: function(res) {
    console.log(res)
  }
})

// 获取小程序是否可以返回上一页
ft.canNavigateBack({
  success: function(res) {
    console.log(res)
  }
})

// 设置小程序页面 title
ft.setNavigationBarTitle({
  title: 'page title'
})

ft.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. 特有接口

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

ft.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 中引用桥接用的 JSSDK 文件,然后在 HTML 里注册方法,比如方法名叫 app2jsFunction。

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

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

# 2.3.1 H5

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

# 2.3.2 小程序

逻辑层

// 小程序 /pages/index/index.js
Page({
  onEvent(e) {
    console.log(e.detail.data.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
}
// 注册监听
ft.miniProgram.onWebviewEvent(onEvent)
// 移除监听
ft.miniProgram.offWebviewEvent(onEvent)

# 2.4.2 小程序

ft.sendWebviewEvent({ test: 123 })