# 小程序管理
小程序管理主要介绍操作小程序的 API,包括:打开小程序,关闭小程序
下面的 API 均是在调用
FinAppClient.init方法返回出来FinAppClient实例上的方法,示例代码中的client即为FinAppClient的实例。如有特殊会在对应 API 说明。
# 1. 打开小程序
不同的场景,所使用的打开小程序的api也不同。所以,我们提供了多种不同的打开小程序的api。
打开线上小程序,这里一般只需要小程序id和服务器地址即可,该api只能打开正式版的小程序。
二维码打开小程序,这个场景是扫描小程序平台上的二维码,得到二维码里的内容,然后使用该内容打开小程序。正式版、体验版、审核版、开发版、预览版本的小程序二维码都可以使用该 Api 打开。
# 1.1 普通打开小程序
下面各类型都是在 IFinApplet 命名空间下,比如 IFinApplet.IAppletRequest 、IFinApplet.IQrCodeRequest
IAppletRequest
| 属性 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| appId | string | 是 | 小程序 ID |
| apiServer | string | 是 | 小程序所属服务器 |
| startParams | IStartParams | 否 | 小程序启动参数 |
| offlineLibraryPath | string | 否 | 离线小程序包路径,可传入沙箱文件路径或 rawfile 路径,加快首次启动速度 |
| offlineFrameworkZipPath | string | 否 | 离线基础库压缩包路径,可传入沙箱文件路径或 rawfile 路径,加快首次启动速度 |
| sequence | number | 否 | 小程序索引 |
| hideCapsuleCloseButton | boolean | 否 | 是否隐藏小程序胶囊里的关闭按钮 |
| hideCapsuleMoreButton | boolean | 否 | 是否隐藏小程序胶囊里的更多按钮 |
| hideTransitionCloseButton | boolean | 否 | 是否隐藏 loading 页胶囊里的关闭按钮 |
| appletThemeStyle | IFinApplet.IThemeStyle | 否 | 小程序主题样式,同 UIConfig.themeStyle |
| backgroundColorContent | string | 否 | 小程序页面容器背景色 |
| enableWatermark | boolean | 否 | 是否显示水印,默认为false |
| enableScreenShot | boolean | 否 | 是否允许截屏录屏,默认为true |
| forceUpdate | boolean | 否 | 是否需要强制打开最新版本,默认为false |
| reLaunchMode | IFinApplet.ReLaunchMode | 否 | 小程序热启动时执行reLaunch的模式。枚举类型,默认为 [IFinApplet.ReLaunchMode.PARAMS_EXIST],即只要有启动参数(启动参数不为null也不为空字符串,不管启动参数是否和上一次的启动参数相同),就执行reLaunch |
| appletAutoAuthorize | boolean | 否 | 是否允许SDK自动授予小程序权限。默认为false.如果设置为true,则小程序里首次触发权限时不会展示权限弹框 |
| extraInfo | object | 否 | 业务透传扩展信息 |
IStartParams
| 属性 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| path | string | 否 | 启动的页面路径 |
| query | string | 否 | 启动的参数 |
| scene | number | 否 | 启动场景值 |
| shareDepth | number | 否 | 分享层级 |
| referrerInfo | IFinApplet.IReferrerInfo | 否 | 来源信息 |
# API
/**
* 根据提供的请求启动小程序。
* @param request - 小程序请求详情。
* @returns 包含小程序客户端或错误的结果。
*/
public startApplet(request: IFinApplet.IAppletRequest): Promise<IFinApplet.IFinAppResult<AppletClient>>
# 1.1.1 打开小程序(基础参数)
# 调用示例
client.startApplet({
appId: 'appId',
apiServer: 'apiServer'
})
# 1.1.2 打开小程序(带启动参数)
# 调用示例
client.startApplet({
appId: 'appId',
apiServer: 'apiServer',
startParams: {
path:'/pages/index/index',
query: "aaa=test&bbb=123"
}
})
# 1.2 二维码打开小程序
扫描平台中的小程序二维码,将解析出来的小程序二维码内容传给接口打开小程序。
IQrCodeRequest
| 属性 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| qrcode | string | 是 | 二维码内容 |
| hideCapsuleCloseButton | boolean | 否 | 是否隐藏小程序胶囊里的关闭按钮 |
| hideCapsuleMoreButton | boolean | 否 | 是否隐藏小程序胶囊里的更多按钮 |
| appletThemeStyle | IFinApplet.IThemeStyle | 否 | 小程序主题样式,同 UIConfig.themeStyle |
| backgroundColorContent | string | 否 | 小程序页面容器背景色 |
| enableWatermark | boolean | 否 | 是否显示水印,默认为false |
| enableScreenShot | boolean | 否 | 是否允许截屏录屏,默认为true |
| forceUpdate | boolean | 否 | 是否需要强制打开最新版本,默认为false |
| reLaunchMode | IFinApplet.ReLaunchMode | 否 | 小程序热启动时执行reLaunch的模式。枚举类型,默认为 [IFinApplet.ReLaunchMode.PARAMS_EXIST],即只要有启动参数(启动参数不为null也不为空字符串,不管启动参数是否和上一次的启动参数相同),就执行reLaunch |
# API
/**
* 使用二维码启动小程序。
* @param request - 二维码请求详情。
* @returns 包含小程序客户端或错误的结果。
*/
public startAppletByQrCode(request: IFinApplet.IQrCodeRequest): Promise<IFinApplet.IFinAppResult<AppletClient>>
# 调用示例
client.startAppletByQrCode({
qrcode: 'qrcode'
})
# 1.3 小程序热启动
在小程序已经打开过的情况下,再次打开时如果不是打开新版本,则会执行热启动,即直接唤起已打开的小程序,并根据启动小程序时设置的热启动执行ReLaunch的模式和启动参数判断是否重新加载页面:
- 如果热启动执行ReLaunch的模式为
IFinApplet.ReLaunchMode.PARAMS_EXIST,则表示只要有启动参数(启动参数中path,query,referrerInfo任意字段不为 null 也不为空字符串,不管启动参数是否和上一次的启动参数相同),就执行 reLaunch。 - 如果热启动执行ReLaunch的模式为
IFinApplet.ReLaunchMode.ONLY_PARAMS_DIFF,则表示有启动参数(启动参数中path,query,referrerInfo任意字段不为 null 也不为空字符串)且和上一次的启动参数不同时,才执行 reLaunch。 - 如果热启动执行ReLaunch的模式为
IFinApplet.ReLaunchMode.ALWAYS,则表示忽略启动参数(不管有没有启动参数,也不管启动参数是否和上一次的启动参数相同),始终执行 reLaunch。 - 如果热启动执行ReLaunch的模式为
IFinApplet.ReLaunchMode.NEVER,则表示忽略启动参数(不管有没有启动参数,也不管启动参数是否和上一次的启动参数相同),均不执行 reLaunch。
# 2. 关闭小程序
该 API 并不会真正结束小程序,而是将小程序移至系统后台,等同于右上角的关闭按钮。
# 2.1 关闭指定小程序
# API
/**
* 关闭小程序。
* @param appId - 要关闭的小程序 ID。
* @param apiServer - 与小程序关联的 API 服务器。
* @param appRunId - 小程序运行 ID,默认为空字符串。
* @returns 表示成功或失败的结果。
*/
public closeApplet(appId: string, apiServer?: string, appRunId: string = ''): Promise<IFinApplet.IFinAppResult<boolean>>
# 调用示例
client.closeApplet('appId', 'apiServer')
# 2.2 关闭所有小程序
# API
/**
* 关闭所有小程序但不删除其资源。
* @returns 表示成功或失败的结果。
*/
public closeAllApplet(): Promise<IFinApplet.IFinAppResult<boolean>>
# 调用示例
client.closeAllApplet()
# 3. 结束小程序
# 3.1 结束指定小程序
# API
/**
* 结束指定小程序。
* @param appId - 要结束的小程序 ID。
* @param apiServer - 与小程序关联的 API 服务器。
* @param appRunId - 小程序运行 ID,默认为空字符串。
* @returns 表示成功或失败的结果。
*/
public clearApplet(appId: string, apiServer?: string, appRunId: string = ''): Promise<IFinApplet.IFinAppResult<boolean>>
# 调用示例
client.clearApplet('appId', 'apiServer')
# 3.2 结束所有小程序
# API
/**
* 结束所有小程序。
* @returns 表示成功或失败的结果。
*/
public clearAllApplet(): Promise<IFinApplet.IFinAppResult<boolean>>
# 调用示例
client.clearAllApplet()
# 4. 删除小程序信息
由于小程序的运行,会将小程序包和小程序信息缓存在本地,以后打开时会优先使用缓存,所以打开时速度也就会很快。所以,如果想要将小程序的所有信息都删除,那么可以使用以下 api 删除某个小程序或者删除所有小程序。
# 4.1 删除指定小程序
# API
/**
* 从本地缓存中移除小程序。
* @param appId - 要移除的小程序 ID。
* @param apiServer - 与小程序关联的 API 服务器。
* @param appRunId - 小程序运行 ID,默认为空字符串。
* @returns 表示成功或失败的结果。
*/
public removeAppletFromLocalCache(appId: string, apiServer?: string, appRunId: string = ''): Promise<IFinApplet.IFinAppResult<boolean>>
# 调用示例
client.removeAppletFromLocalCache('appId', 'apiServer')
# 4.2 删除所有小程序
# API
/**
* 从本地缓存中移除所有小程序和基础库信息。
* @returns 表示成功或失败的结果。
*/
public async removeAllAppletFromLocalCache(): Promise<IFinApplet.IFinAppResult<boolean>>
# 调用示例
client.removeAllAppletFromLocalCache()
# 5. 批量下载小程序
提前查询并下载小程序包到本地,可以减少首次启动小程序的耗时。
# API
/**
* 批量查询小程序更新信息,并按需下载小程序包。
* @param apiServer - 已在初始化配置中注册的小程序服务器地址。
* @param appIds - 要查询的小程序 ID 数组。
* @param isBatchDownloadApplets - 是否下载需要更新的小程序包,默认为 false。
* @returns 批量查询或下载结果。
*/
public downloadApplets(
apiServer: string,
appIds: string[],
isBatchDownloadApplets: boolean = false
): Promise<IFinApplet.IFinAppResult<IFinApplet.IAppletDownLoadInfo[]>>
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| apiServer | string | 是 | 已在 IFinAppConfig.IStoreConfig 中配置的服务器地址。未注册时,调用结果的 errMsg 会提示服务器不存在。 |
| appIds | string[] | 是 | 要批量处理的小程序 ID 数组。 |
| isBatchDownloadApplets | boolean | 否 | 是否下载本地没有或需要更新的小程序包,默认为 false。传入 false 时仅查询并写入小程序信息,不下载小程序包。 |
IFinApplet.IAppletDownLoadInfo
| 属性 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| appId | string | 是 | 小程序 ID。 |
| success | boolean | 是 | 本次处理是否成功。接口返回失败或下载包失败时为 false。 |
| needUpdate | boolean | 是 | 是否检测到需要更新。若本地已缓存相同文件 MD5 的版本,则为 false。 |
# 调用示例
const result = await client.downloadApplets(
'https://api.example.com',
['appletId1', 'appletId2'],
true
)
if (result.data) {
// 每项包含 appId、success 和 needUpdate
console.info(JSON.stringify(result.data))
} else {
console.error(result.errMsg)
}
# 6. 预下载基础库
基础库预下载可以减少首次启动小程序时的下载耗时。在 IFinAppConfig.IStoreConfig 中配置 enablePreloadFramework;该字段默认值为 true。初始化 SDK 后,服务器完成在线校验时会异步预下载基础库;本地已有基础库信息或使用离线模式时不会重复下载。
将
enablePreloadFramework设为false后,初始化阶段不会预下载基础库;但调用downloadApplets时,SDK 仍会先尝试下载基础库,再查询或下载小程序。
# 配置示例
import { FinAppClient, IFinAppConfig } from '@finclip/sdk'
const finAppConfig: IFinAppConfig.IFinAppConfig = {
finStoreConfigs: [{
apiServer: 'https://api.example.com',
sdkKey: 'sdkKey',
sdkSecret: 'sdkSecret',
cryptType: 'sm',
// 开启基础库预下载,默认值为 true
enablePreloadFramework: true
}]
}
const client = FinAppClient.init(finAppConfig, this.context, 'AppletAbility')