@gov-api-package/widget-manager

widget桌面小组件 API

添加widget示意图

一、在开发之前

1.1 配置域名

接入前请将此域名 https://zw.baidusmartapps.com 添加到request的合法域名中

域名	添加方式
https://zw.baidusmartapps.com	开发者后台->小程序管理->设置->开发设置->服务器域名->request的合法域名

1.2 小程序需开通以下api的鉴权

需鉴权的API	说明
swan.addCustomWidget	添加桌面widget小组件
swan.updateCustomWidgetConfig	刷新widgetAPI
swan.openBdboxWebview	打开百度页面API，用于打开刷新widget的h5页面

二、接入

2.1 安装依赖

npm i @gov-api-package/widget-manager --save

2.2 API 使用

widget桌面小组件服务目前提供了初始化、判断当前宿主是否可添加、添加、更新API，具体如下表所示：

API	说明
canUse	判断当前宿主是否支持添加、更新widget
init	初始化widget，初始化后才可以调用添加、更新的API
add	添加widget桌面小组件
update	更新widget桌面小组件

// 引入
import {widgetManager} from '@gov-api-package/widget-manager';

2.2.1 查询当前宿主是否可创建widget canUse

API请求参数说明：

参数	类型	是否必传	默认值	说明
apiName	String	否	addCustomWidget	判断创建的时候：addCustomWidget 判断更新的时候：updateCustomWidgetConfig

API返回值说明：

值	类型	说明
true	Boolean	可用
false	Boolean	不可用

API示例：

/**
 * 初始化widget相关的API
 */
async initWidget() {
    const isCanAdd = await widgetManager.canUse();
    isCanAdd && widgetManager.init({
        widgetType: 'express',
        addConfig: {
            failType: '1',
            successType: '1'
        }
    });
}

2.2.2 初始化widget：init

API请求参数说明：

参数		类型	是否必传	默认值	说明
widgetInfo		Object	是		widget信息
	widgetType	String	是		widget类型
	appKey	String	是		小程序的appKey，可通过以下方式获得： 开发者后台->小程序管理->基础设置->开发设置->开发者ID模块->App Key
	addConfig	Object	否	不传则add方法添加成功、失败都执行以下默认操作	add方法的相关配置
	updateConfig	Object	否	不传则update执行成功后或失败后没有任何提示	update的相关配置

widgetType可选值说明：

值	说明
hesuan	核酸，也是桌面widget默认展示类型
express	快递
riskLevel	疫情风险地区
weather	天气
starSign	星座

addConfig参数说明：

参数	类型	是否必传	默认值	说明
failType	String	否	1	1 添加失败进行toast提示，系统不支持跳转到兜底h5。 2 添加失败进行toast提示，系统不支持添加小程序桌面快捷方式。
failToastText	String	否	添加失败	addConfig.failType有值时的toast提示文案，若addConfig.failType值为2，则系统不支持widget的时候创建小程序桌面快捷方式失败也提示此文案。
successType	String	否	1	1 添加成功toast提示
successToastText	String	否	添加成功	addConfig.successType有值时的toast提示文案。
webviewPagePath	String	否		addConfig.failType为1时承载h5兜底页、ios机型承载h5引导页的webview页面，若不传此参数toast提示添加失败 需以「/」开头
webviewParamName	String	否	url	webview页面内，接收h5链接的参数

updateConfig参数说明：

参数	类型	是否必传	默认值	说明
failToastText	String	否		更新失败的toast提示，不传则失败无提示
successToastText	String	否		更新成功的toast提示，不传则成功无提示

API使用示例：

/**
 * 初始化widget相关的API
 */
initWidget() {
    widgetManager.init({
        widgetType: 'express',
        addConfig: {
            failType: '1',
            successType: '1'
        }
    });
}

2.2.3 添加widget add

API请求参数：

参数		类型	是否必传	默认值	说明
addInfo		Object	否		添加widget相关的参数合集
	success	Function	否		接口调用成功的回调函数
	fail	Function	否		接口调用失败的回调函数

success回调参数说明：

参数	类型	说明
code	String	添加成功返回0，若系统不支持widget，且widgetInfo.addConfig.failType为2的时候，添加桌面快捷方式也会返回0，但没有widgetId
widgetId	String	添加成功后，桌面上生成的 widget 对应的实例 id

fail回调参数说明：

参数	类型	值	说明
errCode	String		add添加失败的code
		400：调用add接口，参数错误； 900：调用add接口，接口异常 1000：调用add接口无网络； 1001：添加失败； 1002：系统不支持； 1003：桌面已存在（13.19以下）；	add添加失败的公共code
		1005：系统不支持，且打开h5引导页失败	init方法中，widgetInfo.addConfig.failType值为1的时侯，打开h5引导页失败的code：
		1004：系统不支持，创建桌面快捷方式失败；	init方法中，widgetInfo.addConfig.failType值为2的时候addToDesktop失败的code：
errMsg	String		添加失败的具体原因

API使用示例:

/**
 * 添加widget桌面小组件
 */
addWidgetHdl() {
    widgetManager.add({
        success: () => {
            console.log('添加成功')
        },
        fail: err => {
            console.log('添加失败')
        }
    });
}

2.2.4 更新widget update

API请求参数：

参数		类型	是否必传	默认值	说明
updateInfo		Object	是
	updateId	String	若调用保存接口后刷新桌面widget时必传		开发者将一些数据提交给服务端之后，接口返回的updateId
	widgetId	String	是		桌面上widget的实例id
	success	Function	否		成功的回调
	fail	Function	否		失败的回调

fail回调参数说明：

参数	类型	值	说明
errCode	String	1001： 更新失败	更新失败的code
errMsg	String		更新失败的说明

API使用示例：

/**
 * 刷新widget桌面小组件
 */
updateWidgetHdl() {
    widgetManager.update({
        updateId: '123',
        widgetId: '123',
        success: () => {
            console.log('更新成功');
        },
        fail: err => {
            console.log('更新失败');
        }
    });
},