# 小程序管理

小程序管理主要介绍操作小程序的 API,包括:打开小程序,关闭小程序

下面的 API 均是在调用 FinAppClient.init 方法返回出来 FinAppClient 实例上的方法,示例代码中的 client 即为 FinAppClient 的实例。如有特殊会在对应 API 说明。

# 1. 打开小程序

不同的场景,所使用的打开小程序的api也不同。所以,我们提供了多种不同的打开小程序的api。

  1. 打开线上小程序,这里一般只需要小程序id和服务器地址即可,该api只能打开正式版的小程序。

  2. 二维码打开小程序,这个场景是扫描小程序平台上的二维码,得到二维码里的内容,然后使用该内容打开小程序。正式版、体验版、审核版、开发版、预览版本的小程序二维码都可以使用该 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的模式和启动参数判断是否重新加载页面:

  1. 如果热启动执行ReLaunch的模式为IFinApplet.ReLaunchMode.PARAMS_EXIST ,则表示只要有启动参数(启动参数中 path, query,referrerInfo 任意字段不为 null 也不为空字符串,不管启动参数是否和上一次的启动参数相同),就执行 reLaunch。
  2. 如果热启动执行ReLaunch的模式为IFinApplet.ReLaunchMode.ONLY_PARAMS_DIFF ,则表示有启动参数(启动参数中 path, query,referrerInfo 任意字段不为 null 也不为空字符串)且和上一次的启动参数不同时,才执行 reLaunch。
  3. 如果热启动执行ReLaunch的模式为IFinApplet.ReLaunchMode.ALWAYS ,则表示忽略启动参数(不管有没有启动参数,也不管启动参数是否和上一次的启动参数相同),始终执行 reLaunch。
  4. 如果热启动执行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')
© FinClip with ❤ , Since 2017