桌面端更多用法

1. api说明

1. api风格

sdk的api采用C语言的风格设计，对外提供dll/so给外部调用，因此对于使用一些高级语言来调用时，需要注意本身不同语言惯用做法上的诸多差异和细节

2. 基本概念

sdk有2种重要的对象：服务器对象和小程序对象，其中服务器对象以appstore来区分，小程序对象以appid来区分，通常某个api需要使用/修改相应对象时，会以这两个值作为参数，举例：

// 操作小程序对象，关闭指定小程序
finclip_close_applet(const char* appid);

// 读取服务器对象的内容，启动指定appid的小程序
finclip_start_applet(const char* appstore, const char* appid);

3. 回调函数

部分api的参数里包含了回调函数，举例：

finclip_register_api(FinClipApiType type,
                     const char* apis,
                     void* (const char* event, const char* param, void* input, int callbackid),
                     void* input);

void* input

注意包含回调函数的api，通常都有一个void* input的传入参数，这个参数会在触发回调的时候原样传回来，且跟具体业务无关，常见做法是在需要保持上下文的地方，通过传入this/self等内容进去，以保证能在回调函数内使用

4. 返回值

api通常有两种返回值，返回整形错误码或返回指针 对于返回错误码的函数，可以在finclip_api_error.h里找到相应的错误信息 对于返回指针的函数，请注意销毁方法，需要手工控制销毁

5. 其它注意事项

在调用带回调函数的api时，一定要注意高级语言的垃圾回收问题，如果回调触发前被回收，将导致sdk崩溃

2. 自定义api

自定义api用于宿主和小程序/内嵌Webview页面之间的通信，常见的两个场景：

1. 宿主提供接口给小程序/内嵌Webview调用
2. 内嵌Webview提供接口给宿主调用

1. 宿主提供接口给小程序/内嵌Webview调用

调用finclip_register_api实现自定义api：

void WebApiExample(const char* event, const char* param, void* input,
                   int callbackid) {
    FinClipParams* res = finclip_create_params();
    finclip_params_set(res, "result", "ok");
    finclip_callback_success(callbackid, res);
    finclip_destory_params(res);
}

finclip_register_api(kWebView, "test", WebApiExample, this);

小程序内调用api获取宿主返回的结果：

wx.test({});

2. 内嵌Webview提供接口给宿主调用

Webview页面注册相应的事件：

window.ft.onNativeAPIHandler('test', cb)

宿主调用api获取结果：

finclip_invoke_api(0, appid, "test", params, callback, input);

3. 生命周期回调

小程序定义了7个生命周期事件, 您可以根据需要监听对应的事件

// 支持的回调类型
enum LifecycleType {
  kLifecycleStarted = 1,   // 小程序启动
  kLifecycleClosed = 2,    // 小程序关闭
  kLifecycleHide = 3,      // 小程序窗口隐藏
  kLifecycleShow = 4,      // 小程序窗口显示
  kLifecycleDomReady = 5,  // 小程序首屏渲染完毕
  kLifecycleCrashed = 6,   // 小程序崩溃
  kLifecycleError = 7,     // 小程序启动错误
};

// 定义生命周期处理函数
void LifecycleHandle(LifecycleType type, const char* appid, void* input) {
    // 注意，这里需要处理线程问题，如：
    // 1. 全局变量加锁
    // 2. 如果此handler需要处理ui界面，根据ui框架可能需要指派dispath到ui线程
    // ...
}

// 注册生命周期
finclip_register_lifecycle(appid, kLifecycleClosed, LifecycleHandle, window)

4. custom_event

custom_event事件用于宿主往小程序发送消息

首先小程序内监听onCustomEvent事件：

const callback = (res) => {
    console.log(res)
}
wx.onCustomEvent(callback)

宿主调用finclip_send_custom_event发送事件：

finclip_send_custom_event(app_id, params);

5. 嵌入模式

目前嵌入模式仅支持 Windows, Mac 和 Linux 正在开发中.

5.1 嵌入窗口

如果要将小程序嵌入到您的窗口中, 首先需要获取窗口句柄, 记为 hwnd 我们提供了两个api完成窗口的嵌入.

  finclip_start_applet_embed(appstore, appid, params, hwnd); // 启动小程序时嵌入到指定窗口
  finclip_embed_applet(appid, hwnd); // 将已启动的小程序嵌入到指定窗口

5.2 处理缩放事件

当您的窗口发生变化时, 您需要监听窗口变化事件, 将高和宽通知小程序进程

  finclip_set_position(appid, left, top, width, height);

5.3 关闭处理

退出分两种情况:

1. 宿主窗口先关闭, 此时需要调用该finclip_close_applet通知FinClip进程退出, 或者使用其他方式杀掉进程
2. FinClip进程先关闭, 此时需要接受FinClip发过来的消息

  // 场景一, 宿主窗口先关闭, 您需要在窗口关闭事件中通知小程序退出
  finclip_close_applet(appid); // 通知小程序关闭

  // 场景二, 小程序先关闭, 您需要在小程序关闭的生命周期事件中关闭宿主窗口
  void LifecycleHandle(LifecycleType type, const char* appid, void* input) {
    if (type == kLifecycleClosed) {
      window.close();
    }
}

6. 调试模式

6.1 调试器简介

调试模式主要用于针对小程序的开发人员，通过调试界面可以做一些调用小程序api、观察小程序日志等操作，更方便定位问题

当进入调试器窗口，可以看到一个当前正在运行小程序的页面列表
其中service.html的页面类似于 vConsole 的界面，可以在上边执行小程序的 api，其余的页面为小程序已经打开的对应页面

console.log输出位置

当你在小程序代码里调用console.log打印某些变量时，有可能在service.html页面输出，也有可能在小程序对应的页面输出

6.2 如何开启调试模式

调试模式可以通过配置启动参数或设置环境变量两种方式开启，SDK 1.6.5 版本开始支持

• 配置启动参数

通过小程序启动时配置启动参数remote_debug，可以分别控制每个小程序是否开启调试模式，本步骤需要在集成sdk的时候处理

在调用api

finclip_start_applet_params(const char* appstore, const char* appid, FinclipParams* params);

启动小程序之前，通过给 params 追加启动参数：

finclip_params_set(params, "remote_debug", "1");

即可让该小程序开启调试模式

• 设置环境变量

通过配置环境变量FINCLIP_DEBUG为1的方式，让所有的小程序都开启调试模式（支持 Windows/Linux）

如何设置环境变量

Windows

1. 通过快捷键win + r打开运行对话框
   
2. 在运行对话框中输入sysdm.cpl进入系统属性窗口
3. 在系统属性窗口中切换到“高级”标签页，点击下方的“环境变量”按钮
   
4. 点击新建，输入变量名FINCLIP_DEBUG，值1即可添加成功
   

Linux 在终端输入export FINCLIP_DEBUG=1即可配置环境变量，注意该配置仅在当前终端生效

6.3 调试模式开启后的区别

• 开启调试模式后，SDK 的日志文件中将输出 Debug 级别的日志，比正常情况下 Info 级别的日志信息更加丰富
• 开启调试模式后，可以通过右上角的更多菜单进入小程序的调试界面（如图）
  

6.4 使用场景

针对不同使用场景开启调试模式的一些建议用法

• 集成 SDK 的开发者

集成 SDK 的开发者在开发阶段可以很方便的通过给小程序启动时追加remote_debug参数的形式开启调试模式，同时也可以将这个开启方法通过某种方式暴露给小程序开发人员或测试人员使用

• 小程序开发人员或测试人员

针对使用已经集成好的应用程序中进行小程序的开发或者测试工作的人员
如果 SDK 集成人员有提供途径设置remote_debug启动参数，则建议使用该方式
如果无法配置remote_debug参数，此时可以通过配置环境变量的方式来开启调试模式

• 用户

假如遇到某些用户使用过程中反馈了一些比较难复现的问题，需要在用户的环境中排查，此时通过设置环境变量的方式开启调试模式