FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

文档中心
  • 介绍
  • 开发
  • 小程序 SDK
  • 常见问题
  • 数据
  • 设计
  • 运营

# 小组件集成

小组件是FinClip SDK 提供的能力，所以只需要集成FinClip SDK即可。

# 1. 集成指引

# 2. 示例 DEMO

# 3. 版本说明

  • iOS SDK和Android SDK均是2.44.1以及之后版本才支持小组件功能。
  • iOS SDK和Android SDK均是2.44.1以及之后版本才支持小组件功能。
  • iOS SDK和Android SDK均是2.44.1以及之后版本才支持小组件功能。

# 4.打开小组件

# 4.1 iOS

通过FATClient类的widgetManager对象提供的API方法创建不同版本类型的小组件，以不同的request创建不同场景下的小组件。

# 4.1.1 打开服务器端正式版小组件

/// 创建widget
/// - Parameters:
///   - request: 请求参数
///   - parentViewController: 组件所在的视图控制器，如果不传，部分API可能没法使用
///   - completion: 创建结果，创建失败时widgetView为nil
- (void)createWidget:(FATWidgetRequest *)request parentViewController:(UIViewController *)parentViewController completion:(void (^)(FATWidgetView *_Nullable widgetView, FATError *error))completion;

示例代码：

FATWidgetRequest *widgetRequest = [[FATWidgetRequest alloc]init];
widgetRequest.widgetId = @"65e82e0778df2c00015c21a4";
widgetRequest.widgetServer = @"https://api.finclip.com";
[self showLoading];
[[FATClient sharedClient].widgetManager createWidget:widgetRequest parentViewController:self completion:^(FATWidgetView * _Nullable widgetView, FATError * _Nonnull error) {
    [self hideLoading];
    if (!error) {
        if (widgetView) {
            [self showWidgetView:widgetView];
        }
    }else {
        [self handleOpenWidgetFail:error];
    }
}];

# 4.1.2 二维码打开小组件

/// 以二维码方式创建widget
/// - Parameters:
///   - request: 请求参数
///   - parentViewController: 组件所在的视图控制器，如果不传，部分API可能没法使用
///   - completion: 创建结果，创建失败时widgetView为nil
- (void)createWidgetWithQRCode:(FATWidgetQRCodeRequest *)request parentViewController:(UIViewController *)parentViewController completion:(void (^)(FATWidgetView *_Nullable widgetView, FATError *error))completion;

# 4.1.3 打开本地小组件

/// 打开本地小组件
/// - Parameters:
///   - request: 请求参数
///   - parentViewController: 组件所在的视图控制器，如果不传，部分API可能没法使用
///    - completion: 创建结果，创建失败时widgetView为nil
- (void)createLocalWidget:(FATWidgetRequest *)request parentViewController:(UIViewController *)parentViewController completion:(void (^)(FATWidgetView *_Nullable widgetView, FATError *error))completion;

# 4.2 Android

# 4.2.1 打开服务器端正式版小组件

/**
 * 打开小组件
 *
 * @param activity 小组件将被添加到的activity
 * @param request 参数封装
 */
fun startComponent(
    activity: FragmentActivity,
    request: IFinAppletRequest,
    callback: ComponentCallback
)

request 使用RemoteFinAppletRequest类型即可。

示例代码：

// 打开小组件前先展示Loading
showLoading()

// 构造request对象
val request = IFinAppletRequest.Companion.fromAppId("https://api.finclip.com", "661ce3fb9876dc000158c94f")
// 可以通过request设置其他启动参数
// ...

FinAppClient.appletApiManager.startComponent(
    this,
    request,
    object : ComponentCallback {
        override fun onSuccess(result: String?) {
            // 小组件加载成功
        }

        override fun onError(code: Int, error: String?) {
            // 小组件加载失败，隐藏Loading，显示错误信息。
            hideLoading()
            showError(code, error.orEmpty())
        }

        override fun onComponentCreated(componentHolder: ComponentHolder) {
            // 小组件创建成功, 将小组件视图添加到宿主Activity视图内
            componentContainer.addView(
                componentHolder.view,
                ViewGroup.LayoutParams.MATCH_PARENT,
                ViewGroup.LayoutParams.MATCH_PARENT
            )
            this@ComponentActivity.componentHolder = componentHolder
        }

        override fun onContentLoaded() {
            // 小组件内容加载完成，隐藏Loading
            hideLoading()
        }
    }
)

# 4.2.2 二维码打开小组件

/**
 * 打开小组件
 *
 * @param activity 小组件将被添加到的activity
 * @param request 参数封装
 */
fun startComponent(
    activity: FragmentActivity,
    request: IFinAppletRequest,
    callback: ComponentCallback
)

request 使用QrCodeFinAppletRequest类型即可。

示例代码：

val request = IFinAppletRequest.Companion.fromQrCode(qrCode)
FinAppClient.appletApiManager.startComponent(
    this,
    request,
    object : ComponentCallback {
        override fun onSuccess(result: String?) {
            // 小组件加载成功
        }

        override fun onError(code: Int, error: String?) {
            // 小组件加载失败，隐藏Loading，显示错误信息。
            hideLoading()
            showError(code, error.orEmpty())
        }

        override fun onComponentCreated(componentHolder: ComponentHolder) {
            // 小组件创建成功, 将小组件视图添加到宿主Activity视图内
            componentContainer.addView(
                componentHolder.view,
                ViewGroup.LayoutParams.MATCH_PARENT,
                ViewGroup.LayoutParams.MATCH_PARENT
            )
            this@ComponentActivity.componentHolder = componentHolder
        }

        override fun onContentLoaded() {
            // 小组件内容加载完成，隐藏Loading
            hideLoading()
        }
    }
)

# 4.2.3 打开本地小组件

/**
 * 打开小组件
 *
 * @param activity 小组件将被添加到的activity
 * @param request 参数封装
 */
fun startComponent(
    activity: FragmentActivity,
    request: IFinAppletRequest,
    callback: ComponentCallback
)

request 使用LocalFinAppletRequest或LocalInterfaceFinAppletRequest类型即可。 示例代码：

val request = IFinAppletRequest.Companion.fromLocalInterface("https://abc.com","661ce3fb9876dc000158c94f")
FinAppClient.appletApiManager.startComponent(
    this,
    request,
    object : ComponentCallback {
        override fun onSuccess(result: String?) {
            // 小组件加载成功
        }

        override fun onError(code: Int, error: String?) {
            // 小组件加载失败，隐藏Loading，显示错误信息。
            hideLoading()
            showError(code, error.orEmpty())
        }

        override fun onComponentCreated(componentHolder: ComponentHolder) {
            // 小组件创建成功, 将小组件视图添加到宿主Activity视图内
            componentContainer.addView(
                componentHolder.view,
                ViewGroup.LayoutParams.MATCH_PARENT,
                ViewGroup.LayoutParams.MATCH_PARENT
            )
            this@ComponentActivity.componentHolder = componentHolder
        }

        override fun onContentLoaded() {
            // 小组件内容加载完成，隐藏Loading
            hideLoading()
        }
    }
)

# 4.2.4 动态设置小组件宽高

/**
 * 打开小组件
 *
 * @param activity 小组件将被添加到的activity
 * @param request 参数封装
 */
fun startComponent(
    activity: FragmentActivity,
    request: IFinAppletRequest,
    callback: ComponentCallback
)

val request = IFinAppletRequest.Companion.fromAppId("https://api.finclip.com", "661ce3fb9876dc000158c94f")

FinAppClient.appletApiManager.startComponent(
    this,
    request,
    object : ComponentCallback {
        override fun onSuccess(result: String?) {
            // 小组件加载成功
        }

        override fun onError(code: Int, error: String?) {
            // 小组件加载失败，隐藏Loading，显示错误信息。
            hideLoading()
            showError(code, error.orEmpty())
        }

        override fun onComponentCreated(componentHolder: ComponentHolder) {
            // 小组件创建成功, 将小组件视图添加到宿主Activity视图内
            componentContainer.addView(
                componentHolder.view,
                ViewGroup.LayoutParams.MATCH_PARENT,
                ViewGroup.LayoutParams.MATCH_PARENT
            )
            // 定义的变量保存componentHolder
            this@ComponentActivity.componentHolder = componentHolder
        }

        // 动态设置小组件宽高回调
        // 这方法触发条件是在小程序代码里面调用了 setWindowSize 方法
        // 示例：wx.setWindowSize({width: 200, height: 200})
        override fun onContentSizeChanged(width: Int, height: Int) {
            val componentView = componentHolder?.view
            componentView?.layoutParams?.apply {
                this.width = width
                this.height = height
                componentView.layoutParams = this
            }
        }

        override fun onContentLoaded() {
            // 小组件内容加载完成，隐藏Loading
            hideLoading()
        }
    }
)

# 4.3 Harmony

鸿蒙使用小组件需要在想创建的位置添加 FinWidget，并传入 widgetId 标识小组件的 id。 当打开小组件遇到错误的时候，会触发代理方法中的 appletLifeCycleHandler.onError，开发者可以根据错误信息或错误码自行处理错误。

示例代码:

import { FinWidget } from '@finclip/sdk';

@Entry
@Component
struct WidgetPage {
    @State widgetId:string = '1'
    // ...
    build(){
        FinWidget({ widgetId: this.widgetId })
                .width('100%')
                .height(200)
    }
}

# 4.3.1 打开服务器端正式版小组件

/**
 * 打开小组件
 *
 * @param context 小组件所在的 context
 * @param request 参数封装
 * @param widgetId 小组件的标识 id
 */
function startWidget(
    context: common.UIAbilityContext,
    request: IFinApplet.IAppletRequest,
    widgetId: string
)

示例代码：

import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';

@Entry
@Component
struct WidgetPage {
    @State widgetId:string = '1'
    client?: FinAppClient

    aboutToAppear() {
        // sdk 初始化逻辑
    }

    startWidget(){
        this.client?.startWidget(this.context, {
            appId: 'appid',
            apiServer: 'apiServer',
            startParams: {}
            }, this.widgetId)
    }

    // ...
    build(){
        FinWidget({ widgetId: this.widgetId })
                .width('100%')
                .height(200)
    }
}

# 4.3.2 二维码打开小组件

/**
 * 打开小组件
 *
 * @param context 小组件所在的 context
 * @param request 参数封装
 * @param widgetId 小组件的标识 id
 */
fun startWidgetByQrCode(
    context: common.UIAbilityContext,
    request: IFinApplet.IQrCodeRequest,
    widgetId: string
)

示例代码：

import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';

@Entry
@Component
struct WidgetPage {
    @State widgetId:string = '1'
    client?: FinAppClient

    aboutToAppear() {
        // sdk 初始化逻辑
    }

    startWidgetByQrCode(qrcode: string) { // 扫码拿到的二维码数据
        this.client?.startWidgetByQrCode(this.context, {
        qrcode
        }, this.widgetId)
    }

    // ...
    build(){
        FinWidget({ widgetId: this.widgetId })
                .width('100%')
                .height(200)
    }
}

# 4.3.3 动态设置小组件宽高

小组件默认宽高为父组件 100%，可以手动给 FinWidget 设置宽高，也可以在小程序内部调用 wx.setWindowSize 来设置

wx.setWindowSize({width: 200, height: 200})

示例代码：

import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';

@Entry
@Component
struct WidgetPage {
    // ...
    build(){
        FinWidget({ widgetId: this.widgetId })
    }
}

# 5. 删除小组件

# 5.1 iOS

# 5.1.1 删除指定小组件缓存

删除小组件，会将小组件从页面上移除，并从内存中销毁

/// 清理wdiget
/// - Parameter widgetId: widgetId
- (void)cleanWidget:(NSString *)widgetId;

# 5.1.2 删除所有小组件缓存

删除所有的小组件，将小组件从页面上移除，并从内存中销毁

/// 清理所有widget
- (void)cleanAllWidget;

# 5.2 Android

# 5.2.1 清除指定小组件缓存

针对添加的小组件，调用其destroy方法。

示例代码：

componentHolder?.destroy()
componentHolder = null

# 5.2.2 清除所有小组件缓存

针对所有小组件，调用其destroy方法即可。

# 5.3 Harmony

# 5.3.1 清除指定小组件缓存

针对添加的小组件，通过 @State 来控制，小组件会在组件被销毁时自动清理数据。不建议使用其他方式清除小组件。

示例代码：

import { FinAppClient, FinWidget, IFinApplet } from '@finclip/sdk';

@Entry
@Component
struct WidgetPage {
    @State showWidget: boolean = false
    // ...
    build(){
        if(showWidget){
            FinWidget({ widgetId: this.widgetId })
        }
    }
}
© FinClip with ❤ , Since 2017