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

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

# 基础

# env

ft.env

环境变量

属性

string USER_DATA_PATH

文件系统中的用户目录路径 (本地路径)

# base64ToArrayBuffer

ArrayBuffer ft.base64ToArrayBuffer(string base64)

将 Base64 字符串转成 ArrayBuffer 对象

参数

string base64

要转化成 ArrayBuffer 对象的 Base64 字符串

返回值

ArrayBuffer

ArrayBuffer 对象

示例代码

const base64 = 'CxYh'
const arrayBuffer = ft.base64ToArrayBuffer(base64)

# arrayBufferToBase64

string ft.arrayBufferToBase64(ArrayBuffer arrayBuffer)

将 ArrayBuffer 对象转成 Base64 字符串

参数

ArrayBuffer arrayBuffer

要转换成 Base64 字符串的 ArrayBuffer 对象

返回值

string

Base64 字符串

示例代码

const arrayBuffer = new Uint8Array([11, 22, 33])
const base64 = ft.arrayBufferToBase64(arrayBuffer)

# base64ToTempFilePath

基础库1.3.9开始支持，iOS版本2.1.23，Android版本2.1.38

base64ToTempFilePath(Object object)

将图片的base64数据保存到本地沙盒，并返回本地缓存路径。

属性 类型 默认值 必填 说明
x number 0 否 待裁剪区域的左上角横坐标
y number 0 否 待裁剪区域的左上角纵坐标
width number canvas宽度-x 否 待裁剪区域的宽度
height number canvas高度-y 否 待裁剪区域的高度
destWidth number width x 屏幕像素密度 否 输出的图片的宽度
destHeight number height x 屏幕像素密度 否 输出的图片的高度
base64Data string 是 图片转成的base64类型字符串
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行

object.success 回调函数

参数

Object res

属性 类型 说明
tempFilePath string 图片的本地地址

# fileToBase64

fileToBase64(Object object)

将文件转换为 Base64 字符串

参数

Object res

属性 类型 说明
url string 文件地址

返回值

string

Base64 字符串

# 系统

# getSystemInfoSync

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

getSystemInfoSync(Object object)

getSystemInfoSync 同步版本。

# getSystemInfoAsync

ft.getSystemInfoAsync(Object object)

异步获取系统信息

参数

Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性 类型 说明 最低版本
brand string 设备品牌 1.5.0
model string 设备型号。新机型刚推出一段时间会显示unknown，会尽快进行适配。
pixelRatio number 设备像素比
screenWidth number 屏幕宽度，单位px 1.1.0
screenHeight number 屏幕高度，单位px 1.1.0
windowWidth number 可使用窗口宽度，单位px
windowHeight number 可使用窗口高度，单位px
statusBarHeight number 状态栏的高度，单位px 1.9.0
language string APP 设置的语言
version string 版本号
system string 操作系统及版本
platform string 客户端平台
SDKVersion string 客户端基础库版本 1.1.0
safeArea Object 在竖屏正方向下的安全区域 2.7.0
theme string 系统当前主题，取值为light或dark，全局配置"darkmode":true时才能获取，否则为 undefined （不支持小游戏） 2.11.0
enableDebug boolean 是否已打开调试。可通过右上角菜单或 ft.setEnableDebug 打开调试。 2.15.0
deviceOrientation string 设备方向
appVersion string 宿主app的版本号
runtimeSDKVersion string 宿主app集成的SDK版本号
bundleId string 宿主app的bundleId
deviceId string 设备的唯一标识
inFinChat string 是否为 小程序环境

safeArea 的结构

属性 类型 说明
left number 安全区域左上角横坐标
right number 安全区域右下角横坐标
top number 安全区域左上角纵坐标
bottom number 安全区域右下角纵坐标
width number 安全区域的宽度，单位逻辑像素
height number 安全区域的高度，单位逻辑像素

theme 的合法值

值 说明 最低版本
dark 深色主题
light 浅色主题

deviceOrientation 的合法值

值 说明 最低版本
portrait 竖屏
landscape 横屏

示例代码

在开发者工具中预览效果

ft.getSystemInfoAsync({
  success(res) {
    console.log(res.model)
    console.log(res.pixelRatio)
    console.log(res.windowWidth)
    console.log(res.windowHeight)
    console.log(res.language)
    console.log(res.version)
    console.log(res.platform)
  }
})

# getSystemInfo

基础库 1.3.9 开始支持，iOS 版本 2.1.23，Android 版本 2.1.38

getSystemInfo(Object object)

获取系统信息。

参数

Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数 ​ 参数

Object res

属性 类型 说明 最低版本
brand string 设备品牌 1.5.0
model string 设备型号。新机型刚推出一段时间会显示unknown，会尽快进行适配。
pixelRatio number 设备像素比
screenWidth number 屏幕宽度，单位px 1.1.0
screenHeight number 屏幕高度，单位px 1.1.0
windowWidth number 可使用窗口宽度，单位px
windowHeight number 可使用窗口高度，单位px
statusBarHeight number 状态栏的高度，单位px 1.9.0
language string APP 设置的语言
version string 版本号
system string 操作系统及版本
platform string 客户端平台
SDKVersion string 客户端基础库版本 1.1.0
safeArea Object 在竖屏正方向下的安全区域 2.7.0
theme string 系统当前主题，取值为light或dark，全局配置"darkmode":true时才能获取，否则为 undefined （不支持小游戏） 2.11.0
enableDebug boolean 是否已打开调试。可通过右上角菜单或 ft.setEnableDebug 打开调试。 2.15.0
deviceOrientation string 设备方向
appVersion string 宿主app的版本号
runtimeSDKVersion string 宿主app集成的SDK版本号
bundleId string 宿主app的bundleId
deviceId string 设备的唯一标识
inFinChat string 是否为 小程序环境

示例代码

ft.getSystemInfo({
  success(res) {
    console.log(res.model)
    console.log(res.pixelRatio)
    console.log(res.windowWidth)
    console.log(res.windowHeight)
    console.log(res.language)
    console.log(res.version)
    console.log(res.platform)
  }
})

# 更新

# getUpdateManager

基础库 1.5.30 开始支持，iOS 版本 2.5.6，Android 版本 2.8.76

获取全局唯一的版本更新管理器，用于管理小程序更新。 返回值 UpdateManager

UpdateManager 方法

UpdateManager.applyUpdate() 强制小程序重启并使用新版本。在小程序新版本下载完成后（即收到 onUpdateReady 回调）调用。​

UpdateManager.onCheckForUpdate(function callback) 监听向后台请求检查更新结果事件。SDK 在小程序冷启动时自动检查更新，不需由开发者主动触发。

UpdateManager.onUpdateReady(function callback) 监听小程序有版本更新事件。客户端主动触发下载（无需开发者触发），下载成功后回调 UpdateManager.onUpdateFailed(function callback) 监听小程序更新失败事件。小程序有新版本，客户端主动触发下载（无需开发者触发），下载失败（可能是网络原因等）后回调。

示例代码

const updateManager = ft.getUpdateManager()

updateManager.onCheckForUpdate(function(res) {
  // 请求完新版本信息的回调
  console.log(res.hasUpdate)
})

updateManager.onUpdateReady(function() {
  ft.showModal({
    title: '更新提示',
    content: '新版本已经准备好，是否重启应用？',
    success: function(res) {
      if (res.confirm) {
        // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启
        updateManager.applyUpdate()
      }
    }
  })
})

updateManager.onUpdateFailed(function() {
  // 新版本下载失败
})

# 小程序

# getLaunchOptionsSync

Object ft.getLaunchOptionsSync() 获取小程序启动时的参数。与 App.onLaunch 的回调参数一致。

返回值

Object

启动参数

属性 类型 说明
path string 启动小程序的路径 (代码包路径)
<!-- scene number
query Object 启动小程序的 query 参数
<!-- shareTicket string
referrerInfo Object 来源信息

referrerInfo 的结构

属性 类型 说明
appId string 小程序的 appId
extraData Object 来源小程序传过来的数据

# getEnterOptionsSync

Object ft.getEnterOptionsSync()

获取本次小程序启动时的参数。如果当前是冷启动，则返回值与 App.onLaunch 的回调参数一致；如果当前是热启动，则返回值与 App.onShow 一致。

返回值

Object

启动参数

属性 类型 说明
path string 启动小程序的路径 (代码包路径)
<!-- scene number
query Object 启动小程序的 query 参数
<!-- shareTicket string
referrerInfo Object 来源信息

referrerInfo 的结构

属性 类型 说明
appId string 小程序的 appId
extraData Object 来源小程序传过来的数据

# onPageNotFound

ft.onPageNotFound(function callback)

监听小程序要打开的页面不存在事件。该事件与 App.onPageNotFound 的回调时机一致。

参数

function callback

小程序要打开的页面不存在事件的回调函数

参数

Object res

属性 类型 说明
path string 不存在页面的路径 (代码包路径)
query Object 打开不存在页面的 query 参数
isEntryPage boolean 是否本次启动的首个页面（例如从分享等入口进来，首个页面是开发者配置的分享页面）

注意

  • 开发者可以在回调中进行页面重定向，但必须在回调中同步处理，异步处理（例如 setTimeout 异步执行）无效。
  • 若开发者没有调用 ft.onPageNotFound 绑定监听，也没有声明 App.onPageNotFound，当跳转页面不存在时，将推入原生的页面不存在提示页面。
  • 如果回调中又重定向到另一个不存在的页面，将推入原生的页面不存在提示页面，并且不再第二次回调。

# onError

ft.onError(function callback)

监听小程序错误事件。如脚本错误或 API 调用报错等。该事件与 App.onError 的回调时机与参数一致。

参数

function callback

小程序错误事件的回调函数

参数

string error

错误信息，包含堆栈

# onAppShow

ft.onAppShow(function callback)

监听小程序切前台事件。该事件与 App.onShow 的回调参数一致。

参数

function callback

小程序切前台事件的回调函数

参数

Object res

属性 类型 说明
path string 小程序切前台的路径 (代码包路径)
<!-- scene number
query Object 小程序切前台的 query 参数
<!-- shareTicket string
referrerInfo Object 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {}。(参见后文注意)

referrerInfo 的结构

属性 类型 说明
appId string 小程序的 appId
extraData Object 来源小程序传过来的数据

# onAppHide

ft.onAppHide(function callback)

监听小程序切后台事件。该事件与 App.onHide 的回调时机一致。

参数

function callback

小程序切后台事件的回调函数

# offPageNotFound

ft.offPageNotFound(function callback)

取消监听小程序要打开的页面不存在事件

参数

function callback

小程序要打开的页面不存在事件的回调函数

# offError

ft.offError(function callback)

取消监听小程序错误事件。

参数

function callback

小程序错误事件的回调函数

# offAppShow

ft.offAppShow(function callback)

取消监听小程序切前台事件

参数

function callback

小程序切前台事件的回调函数

# offAppHide

ft.offAppHide(function callback)

取消监听小程序切后台事件

参数

function callback

小程序切后台事件的回调函数

# onThemeChange

ft.onThemeChange(function callback)

监听系统主题改变事件。

参数

function callback

系统主题改变事件的回调函数

# onUnhandledRejection

ft.onUnhandledRejection(function callback)

监听未处理的 Promise 拒绝事件

参数

function callback

未处理的 Promise 拒绝事件的回调函数

# offUnhandledRejection

ft.offUnhandledRejection(function callback)

取消监听未处理的 Promise 拒绝事件

参数

function callback

onUnhandledRejection 传入的回调函数,不传此参数则移除所有监听函数。

# offThemeChange

ft.offThemeChange(function callback)

取消监听系统主题改变事件

参数

function callback

onThemeChange 传入的回调函数。不传此参数则移除所有监听函数。

# 调试

# setEnableDebug

ft.setEnableDebug(Object object)

设置是否打开调试开关。此开关对正式版也能生效。

参数

Object object

属性 类型 默认值 必填 说明
enableDebug boolean 是 是否打开调试
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

// 打开调试
ft.setEnableDebug({
  enableDebug: true
})

// 关闭调试
ft.setEnableDebug({
  enableDebug: false
})

Tips

  • 在正式版打开调试还有一种方法，就是先在开发版或体验版打开调试，再切到正式版就能看到 vConsole。

# console

向调试面板中打印日志。console 是一个全局对象，可以直接访问。在微信客户端中，向 vConsole 中输出日志

console.debug()

向调试面板中打印 debug 日志

console.error()

向调试面板中打印 error 日志

console.group()

在调试面板中创建一个新的分组

console.groupEnd()

结束由 console.group 创建的分组

console.info()

向调试面板中打印 info 日志

console.log()

向调试面板中打印 log 日志

console.warn()

向调试面板中打印 warn 日志

# 版本信息

# getAccountInfoSync

ft.getAccountInfoSync()

功能描述 获取当前帐号信息。线上小程序版本号仅支持在正式版小程序中获取，开发版和体验版中无法获取。

返回值

Object

帐号信息

属性 类型 说明
miniProgram Object 小程序帐号信息

示例代码

const accountInfo = ft.getAccountInfoSync()
console.log(accountInfo.miniProgram.appId) // 小程序 appId
// console.log(accountInfo.plugin.appId) // 插件 appId
// console.log(accountInfo.plugin.version) // 插件版本号， 'a.b.c' 这样的形式

# getUserProfile

获取用户信息。

参数

Object object

属性 类型 默认值 必填 说明
lang string en 否 显示用户信息的语言
desc string 是 声明获取用户个人信息后的用途，不超过 30 个字符
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性 类型 说明 最低版本
userInfo UserInfo 用户信息对象 2.10.4
rawData string 不包括敏感信息的原始数据字符串，用于计算签名 2.10.4
signature string 使用 sha1( rawData + sessionkey ) 得到字符串，用于校验用户信息，详见 用户数据的签名验证和加解密 2.10.4
encryptedData string 包括敏感数据在内的完整用户信息的加密数据，详见 用户数据的签名验证和加解密 2.10.4
iv string 加密算法的初始向量，详见 用户数据的签名验证和加解密 2.10.4
cloudID string 敏感数据对应的云 ID，开通云开发的小程序才会返回，可通过云调用直接获取开放数据，详细见云调用直接获取开放数据 2.10.4

# getUserInfo

获取用户信息。

参数

Object res

属性 类型 默认值 必填 说明
withCredentials boolean 否 显示用户信息的语言
lang string en 是 声明获取用户个人信息后的用途，不超过 30 个字符
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性 类型 说明 最低版本
userInfo UserInfo 用户信息对象
rawData string 不包括敏感信息的原始数据字符串，用于计算签名
signature string 使用 sha1( rawData + sessionkey ) 得到字符串，用于校验用户信息，详见 用户数据的签名验证和加解密
encryptedData string 包括敏感数据在内的完整用户信息的加密数据，详见 用户数据的签名验证和加解密
iv string 加密算法的初始向量，详见 用户数据的签名验证和加解密
cloudID string 敏感数据对应的云 ID，开通云开发的小程序才会返回，可通过云调用直接获取开放数据，详细见云调用直接获取开放数据 2.7.0

# UserInfo

用户信息

属性 string nickName 用户昵称

string avatarUrl 用户头像图片的 URL。URL 最后一个数值代表正方形头像大小（有 0、46、64、96、132 数值可选，0 代表 640x640 的正方形头像，46 表示 46x46 的正方形头像，剩余数值以此类推。默认 132），用户没有头像时该项为空。若用户更换头像，原有头像 URL 将失效。

number gender 用户性别。不再返回，参考 相关公告

gender 的合法值

值 说明 最低版本
0 未知
1 男性
2 女性

string country 用户所在国家。不再返回，参考 相关公告

string province 用户所在省份。不再返回，参考 相关公告

string city 用户所在城市。不再返回，参考 相关公告

string language 显示 country，province，city 所用的语言。强制返回 “zh_CN”，参考 相关公告

language 的合法值

值 说明 最低版本
en 英文
zh_CN 简体中文
zh_TW 繁体中文
© 2022 FinClip with ❤

👋🏻 嘿，你好！

「FinClip」是一套基于云原生框架设计的小程序容器。能够让任何移动应用在集成小程序SDK之后，获得可用、安全的小程序运行能力。

>> 点我免费注册体验

查看产品文档
了解与 FinClip 相关的一切信息

产品博客 👈  了解产品更新与核心功能介绍
资源下载 👈  获取小程序 SDK 与开发工具
文档中心 👈  查询 FinClip 小程序开发指南与答疑

商务咨询热线
预约 FinClip 产品介绍，咨询商务报价或私有化部署事宜

0755-86967467

获取产品帮助
联系 FinClip 技术顾问，获取产品资料或加入开发者社群

联系线上
人工客服

或 👉  点击这里，提交咨询工单