# API/组件自定义

如果小程序里需要调用一些宿主 App 提供的能力，而 FinClip 小程序 SDK 未实现或无法实现时，就可以通过注册自定义 API 来实现，使得小程序里也能够调用 App 中注册的 API 了。

注册自定义 API 分两个场景：

注册给原生小程序使用的自定义 API；
注册给小程序中 WebView 组件加载的 H5 使用的自定义 API。（暂不支持）

# 1. 自定义小程序 API

注册自定义小程序 api 以及使用自定义小程序 api 有四步：

实现自定义 api
注册自定义 api
在小程序配置中声明自定义 api
小程序中调用自定义 api

# 1.1 注册自定义小程序异步 API

# 1.1.1 实现自定义异步 api

实现自定义小程序异步 api 示例

import { IApiManager } from "@finclip/sdk";
function finclipLogin(args: IApiManager.IInvokeArgs) {
  /**
   * params 小程序发送的参数
   * callback 用于执行成功或失败的回调
   */
  const params = args.params;
  const callback = args.callback;
  const extInfo = args.extInfo;
  console.log("finclipLogin params", JSON.stringify(params));
  // do something
  const res = true;
  // do something end
  if (res) {
    callback.onSuccess({ message: "finclipLogin success !!" });
  } else {
    callback.onFail({ errMsg: "finclipLogin fail !!" });
  }
}

# 1.1.2 注册自定义异步 api

# 1.1.2.1 全局注册

const instance = FinAppClient.getInsance();
instance?.registerCustomApi("finclipLogin", finclipLogin);

# 1.1.2.2 单独注册

async function startApplet() {
  const appletClient = await client.startApplet({
    appId: "小程序的 appId",
    apiServer: "服务器的地址",
  });
  appletClient.registerCustomApi("finclipLogin", finclipLogin);
}

单独注册的优先级最高，即存在同名 api 的时候，单独注册的 api 会覆盖全局注册的 api

# 1.1.3 在小程序配置文件中声明自定义 api

在小程序根目录创建 FinClipConf.js 并进行相应的自定义 api 配置，或通过 loadExtApi 传入配置参数

module.exports = {
  extApi: [
    {
      //普通交互API
      name: "finclipLogin", //扩展api名 该api必须Native方实现了
      sync: false, //是否为同步api
      params: {
        //扩展api 的参数格式，可以只列必须的属性
        url: "",
      },
    },
  ],
};

小程序端更多配置信息可参考 ft.loadExtApi (opens new window)

# 1.1.4 小程序里调用自定义小程序异步 api

ft.finclipLogin({
  url: "https://www.baidu.com",
  success: function (res) {
    console.log("调用customEvent success");
    console.log(res);
  },
  fail: function (res) {
    console.log("调用customEvent fail");
    console.log(res);
  },
});

# 1.2 注册自定义小程序同步 API

# 1.2.1 实现自定义同步 api

实现自定义小程序同步 api 示例

import { IApiManager } from "@finclip/sdk";

interface ILoginApIRes extends IApiManager.IInvokeBaseResponse {} // 定义返回类型

function finclipLoginSync(args: IApiManager.IInvokeArgs): ILoginApIRes {
  /**
   * params 小程序发送的参数
   */
  const params = args.params;
  const extInfo = args.extInfo;
  console.log("finclipLoginSync params", JSON.stringify(params));
  // do something
  const res = true;
  // do something end
  // 同步 API 需要同步返回结果
  return {
    errMsg: "finclipLoginSync:ok", // 调用信息，如果有则会拼接到 callback 的 errMsg 字段中
    data: "finclipLoginSync success !!", // 返回给小程序的数据
  };
}

# 1.2.2 注册自定义同步 api

# 1.2.2.1 全局注册

const instance = FinAppClient.getInsance();
instance?.registerCustomApi("finclipLogin", finclipLogin);

# 1.2.2.2 单独注册

async function startApplet() {
  const appletClient = await client.startApplet({
    appId: "小程序的 appId",
    apiServer: "服务器的地址",
  });
  appletClient.registerCustomApi("finclipLogin", finclipLogin);
}