小部件

更新时间:2023-09-19 08:17:41下载pdf

小部件是小程序表现形式的拓展,您通过类似于小程序的开发模式,构建出小部件产物。投放到对应 App 后,小部件即可在 App 中展示。相较于小程序,小部件显得更轻量、更便捷,更适合于展示性的场景。

功能

小部件支持在小程序和应用(Native)中接入。在小程序中的小部件,支持以弹窗的形式存在。在 Native 中的小部件,可以以弹窗、组件、页面组成部分的形式存在,具体形式由您自行决定。

API

创建小部件弹窗

小部件弹窗,类似于 Dialog,展示时会覆盖在页面之上。

/**
     * 创建弹窗小部件并展示
     * @param context 上下文
     * @param url 创建小部件 URL,格式参见下文参数说明部分
     * @param callback 执行回调
     */
    fun showWidgetDialog(context: Context, url : String, callback : IMiniAppWidgetDialogCB)

示例代码

ThingMiniAppClient
                .widgetClient()
                .showWidgetDialog(this, url, new IMiniAppWidgetDialogCB() {

                    @Override
                    public void result(Dialog result) {
                        // 弹窗展示后的触发
                    }

                    @Override
                    public void unSupport(Dialog dialog) {
                        // 不支持场景的回调通知
                    }
                });

创建小部件视图

小部件视图,类似于 View,可以在 Native 中以组件、页面组成部分的形式存在。具体展示形式,可以由您自行决定。


/**
     * 创建小部件视图
     * @param creator 参数构造
     */
    fun createWidgetView(creator : WidgetCreatorBuilder)

示例代码

ThingMiniAppClient
                .widgetClient()
                .createWidgetView(
                        WidgetCreatorBuilder.newInstance()
                                .addDeployCreatorBuilder(
                                        WidgetDeployCreatorBuilder.newInstance()
                                                .build(url)

                                )
                                .build(context));

预加载小部件

可以在合适的时机调用小部件预加载 API,以加快小部件的启动速度。

/**
     * 小部件预加载
     * @param appId 小部件 ID
     */
    fun preloadWidget(appId : String)

示例代码

ThingMiniAppClient.widgetClient().preloadWidget("tydhopggfziofo1h9h");

参数

创建小部件时,您需要设置一个 URL,URL 的格式如 godzilla://miniprogramId/widget/card/index?miniWidgetStyle=large&miniVersionType=release

URL 是一个标准的路径格式,其中包含了小部件的基本信息。具体参数说明如下:

  • scheme:固定为 godzilla
  • host:小程序对应的 appId
  • path:要打开的小部件页面路径,不设置时默认打开小部件配置文件中对应的 entryPagePath
  • query:小部件打开时一些必要的参数,主要的参数请参考下文 query

query

  • miniWidgetStyle:小部件样式。可选值:

    • small:高度与宽度比为一比一,宽度为屏幕宽度的二分之一。
    • middle(默认值):高度与宽度比为一比二,宽度为屏幕宽度。
    • large:高度与宽度比为二比二,宽度为屏幕宽度,高度为屏幕宽度。
    • custom:自定义宽高比,含义为以屏幕宽度为基准,高度为屏幕宽度乘以 custom
  • miniAppVersion:小部件版本号。默认填充最新版本号。

  • miniVersionType:小部件版本类型。可选值:

    • release(默认值):正式版本。用于线上正式环境。
    • preview:预览版本。用于您在开发过程中预览小部件。
  • miniPosition:弹窗小部件展示时,处于屏幕上的位置。可选值:

    • bottom(默认值):位于屏幕底部。
    • top:位于屏幕顶部。
  • miniAutoDismiss:单击蒙层小部件弹窗是否自动消失。可选值:

    • true(默认值):单击蒙层小部件弹窗自动消失。
    • false:单击蒙层小部件弹窗不自动消失,需要您手动调用关闭方法。
  • miniAutoCache:小部件是否自动缓存。可选值:

    • true(默认值):小部件自动缓存,下次展示时会先展示缓存对应的截图。
    • false:小部件不自动缓存,下次展示时会重新加载小部件。
  • 其他参数:除了上述参数外,还可以设置其他业务参数,小部件可以在 Widget.onLoad 中获取:

    参数名称 是否必填 备注 示例
    miniWidgetStyle 设置 custom 时需要设置具体小部件高宽比值 miniWidgetStyle=1.5
    miniAppVersion 每次拉取最新时不需要设置 miniAppVersion=2.0.0
    miniVersionType 上线时请确保设置 release 或者不传 miniVersionType=release
    miniPosition 小部件弹窗时需确认展示位置,默认居底 miniPosition=bottom
    miniAutoDismiss 小部件弹窗时单击蒙层不消失时需设置 miniAutoDismiss=false
    miniAutoCache 小部件不需要优先展示缓存图片时设置 miniAutoCache=false