# 基础
# 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)
# 系统
# 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 | 是否为FinClip 小程序环境 |
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 | 是否为FinClip 小程序环境 |
示例代码
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 | shareTicket，详见获取更多转发信息 |
| referrerInfo | Object | 来源信息 |
referrerInfo 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| appId | string | 来源小程序、公众号或 App 的 appId |
| extraData | Object | 来源小程序传过来的数据，scene=1037 或 1038 时支持 |
forwardMaterials 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| type | string | 文件的 mimetype 类型 |
| name | string | 文件名 |
| path | string | 文件路径（如果是 webview 则是 url） |
| size | number | 文件大小 |
返回有效 referrerInfo 的场景
| 场景值 | 场景 | appId 含义 |
|---|---|---|
| 1020 | 公众号 profile 页相关小程序列表 | 来源公众号 |
| 1035 | 公众号自定义菜单 | 来源公众号 |
| 1036 | App 分享消息卡片 | 来源 App |
| 1037 | 小程序打开小程序 | 来源小程序 |
| 1038 | 从另一个小程序返回 | 来源小程序 |
| 1043 | 公众号模板消息 | 来源公众号 |
| 1069 | 移动应用 | 来源 App |
# getEnterOptionsSync
Object ft.getEnterOptionsSync()
获取本次小程序启动时的参数。如果当前是冷启动，则返回值与 App.onLaunch 的回调参数一致；如果当前是热启动，则返回值与 App.onShow 一致。
返回值
Object
启动参数
| 属性 | 类型 | 说明 |
|---|---|---|
| path | string | 启动小程序的路径 (代码包路径) |
| scene | number | 启动小程序的场景值 |
| query | Object | 启动小程序的 query 参数 |
| shareTicket | string | shareTicket，详见获取更多转发信息 |
| referrerInfo | Object | 来源信息 |
referrerInfo 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| appId | string | 来源小程序、公众号或 App 的 appId |
| extraData | Object | 来源小程序传过来的数据，scene=1037 或 1038 时支持 |
返回有效 referrerInfo 的场景
| 场景值 | 场景 | appId 含义 |
|---|---|---|
| 1020 | 公众号 profile 页相关小程序列表 | 来源公众号 |
| 1035 | 公众号自定义菜单 | 来源公众号 |
| 1036 | App 分享消息卡片 | 来源 App |
| 1037 | 小程序打开小程序 | 来源小程序 |
| 1038 | 从另一个小程序返回 | 来源小程序 |
| 1043 | 公众号模板消息 | 来源公众号 |
注意
部分版本在无 referrerInfo 的时候会返回 undefined，建议使用 options.referrerInfo && options.referrerInfo.appId 进行判断。
# 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 | shareTicket，详见获取更多转发信息 |
| referrerInfo | Object | 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {}。(参见后文注意) |
| forwardMaterials | Array.<Object> | 打开的文件信息数组，只有从聊天素材场景打开（scene 为 1173）才会携带该参数 |
referrerInfo 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| appId | string | 来源小程序、公众号或 App 的 appId |
| extraData | Object | 来源小程序传过来的数据，scene=1037 或 1038 时支持 |
forwardMaterials 的结构
| 属性 | 类型 | 说明 |
|---|---|---|
| type | string | 文件的 mimetype 类型 |
| name | string | 文件名 |
| path | string | 文件路径（如果是 webview 则是 url） |
| size | number | 文件大小 |
返回有效 referrerInfo 的场景
| 场景值 | 场景 | appId 含义 |
|---|---|---|
| 1020 | 公众号 profile 页相关小程序列表 | 来源公众号 |
| 1035 | 公众号自定义菜单 | 来源公众号 |
| 1036 | App 分享消息卡片 | 来源 App |
| 1037 | 小程序打开小程序 | 来源小程序 |
| 1038 | 从另一个小程序返回 | 来源小程序 |
| 1043 | 公众号模板消息 | 来源公众号 |
注意
部分版本在无referrerInfo的时候会返回 undefined，建议使用 options.referrerInfo && options.referrerInfo.appId 进行判断。
# 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
小程序切后台事件的回调函数
# 调试
# 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。
# 版本信息
# getAccountInfoSync
获取当前小程序信息
返回值
Object object
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| miniProgram | Object | 是 | 小程序帐号信息 |
Object miniProgram
| 属性 | 类型 | 说明 |
|---|---|---|
| appId | string | 小程序 appId |
| envVersion | string | 小程序版本 develop:开发版 trial:体验版 release:正式版 review:审核版 |
# Object getAccountInfoSync()
功能描述 获取当前帐号信息。线上小程序版本号仅支持在正式版小程序中获取，开发版和体验版中无法获取。
返回值
Object
帐号信息
| 属性 | 类型 | 说明 |
|---|---|---|
| miniProgram | Object | 小程序帐号信息 |
| plugin | 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 | 繁体中文 |
