# 账户卡片
# 一、功能介绍
为了方便用户查看、操作自己在小程序中的资金类账户,一键触达小程序,微信在「发现-小程序」入口新增「我的账户」板块。
具体功能示意图如下:
# 二、功能介绍
支持微信版本:8.0.41 for Android 及以上;8.0.46 for ios及以上
支持基础库版本:3.1.1 及以上
# 1. 开通功能
开发者首先需要明确自己的服务业态,当前账户卡片支持的业态包括:
卡片id | 卡片名称 | 类目要求 | 使用场景 | 展示字段 |
---|---|---|---|---|
5001 | 基金账户 | 金融业-公募基金、私募基金 | 向用户展示资产、收益情况等信息 | 总资产、昨日收益 |
5002 | 电信账户 | IT科技-基础电信运营商、电信业务代理商 | 向用户展示话费余额、剩余流量等信息 | 话费余额、流量余额 |
5003 | 信用卡账户 | 金融业-银行、信用卡 | 向用户账单、可用额度、还款日等信息 | 账单剩余应还、可用额度、还款日 |
5004 | 贷款账户 | 金融业-非金融机构自营小额贷款、贷款信息服务 | 向用户展示本期账单、总计应还,还款日等信息 | 本期应还、总计应还、还款日 |
5005 | 个人养老金卡片账户 | 金融业-银行、金融业-信用卡 | 向用户展示养老金资产、收益情况等信息 | 总资产、昨日收益 |
5006 | 保险卡片 | 金融业-保险、第三方互联网保险 | 向用户展示已购买保险名称、保险状态、有限期 | 保险名、是否生效、保险日期 |
5007 | 证券卡片 | 金融业-证券/期货、证券/期货投资资讯、股票信息平台、股票信息服务平台(港股/美股) | 向用户展示已购买总资产、今日盈亏、证券名称 | 总资产、今日盈亏 |
登录微信公众平台 ,符合类目要求即可在开发管理-其他接口找到「发现页账户卡片」,点击开通,即可开通该功能开发权限
# 2. 在代码包中创建卡片分包
账户卡片为小程序代码包中的独立组件分包。为保证 UI 统一,微信侧会提供不同类型的账户卡片模板,页面样式( WXML 与 WXSS )是由微信提供的固定的代码,JS 逻辑由开发者控制,包括数据请求、渲染、缓存等。
开发者需使用微信开发者工具开发版 Nightly Build 1.06.2309062及以上版本进行创建。具体步骤如下:
# 2.1 创建分包目录 accountCardPackage
- 在 app.json 中开启小程序「按需注入」特性(lazyCodeLoading)、声明一个独立分包 accountCardPackage 并进行配置:
{
// app.json
// ...
"lazyCodeLoading": "requiredComponents",
"subpackages": [
{
"root": "accountCardPackage",
"pages": [],
"independent": true
}
],
"accountCardPackage": {
"root": "accountCardPackage",
"cardList": []
}
}
- 在accountCardPackage 分包目录中右键,点击新建卡片,输入组件名后创建(图为示例,所有类型卡片都从该入口新建)
- 完成以上步骤后,可在 accountCardPackage 目录下看到创建好的卡片,同时 app.json 中也会出现相关配置
注意事项:
- 一个小程序若符合对应卡片类目要求,可以接入多个不同类型的卡片,但是同一类型的卡片只能接入一个。
- 卡片分包的目录结构取决于卡片被添加时的
app.json
的配置,卡片一旦被普通用户添加过,就不能再改动其目录结构,否则已添加过的用户就无法正常使用卡片。 - 卡片是运行在一个独立的环境中,卡片之间相互隔离。用户提供的卡片组件在渲染时,其
wxml
、wxss
和json
会被替换成固定模板,只有开发者的js
代码会被注入执行。
# 2.2 实现卡片JS逻辑
创建卡片分包后,开发者可在js文件中实现卡片组件逻辑,包括获取登录态、请求数据、加解密数据等。一个卡片组件逻辑示例如下:
// 以 5001 为例
Component({
data: {
totalAmount: 0,
yesterdayEarnings: 0,
},
lifetimes: {
attached() {
// 更新卡片数据
this.setData({
totalAmount: 6000000,
yesterdayEarnings: 10000,
})
// 数据已准备完毕,通知嵌入卡片方
this.updateStatus('loaded')
},
},
})
具体实现步骤如下:
- 设置卡片展示的变量信息。由于WXML文件不支持开发者自定义,因此每种卡片支持显示的字段由平台定义,开发者实现获取与加密逻辑后通过 setData 变更变量信息。不同卡片类型支持的变量信息通过可参考下表:
卡片id | 卡片名称 | 字段 | 描述 | 是否可隐藏 |
---|---|---|---|---|
5001 | 基金账户 | totalAmount | 总资产,单位为分 | 否 |
yesterdayEarnings | 昨日收益,单位为分 | 否 | ||
5002 | 电信账户 | telephoneBalance | 话费余额,单位为分 | 否 |
residualData | 剩余流量,单位为 MB | 否 | ||
5003 | 信用卡账户 | remainingRepayment | 本期账单剩余应还款金额,单位为分 | 否 |
availableCreditLimit | 信用卡可用额度,单位为分 | 是 | ||
dueDateMonth | 还款日期中的月 | 是 | ||
dueDateDay | 还款日期中的日 | 是 | ||
cardNumber | 卡片尾号,仅展示后四位,默认不显示 | 是 | ||
pendingRepayCardCnt | (多卡情况)共有多少张卡,默认不展示 | 是 | ||
allCardsEnterPath | (多卡情况)若调用了“pendingRepayCardCnt”,则需设置多卡显示区域设置对应的跳转路径 | |||
5004 | 贷款账户 | currentRepayment | 本期账单剩余应还款金额,单位为分 | 否 |
totalDebt | 贷款总计应还金额,单位为分 | 是 | ||
dueDateMonth | 还款日期中的月 | 是 | ||
dueDateDay | 还款日期中的日 | 是 | ||
cardNumber | 卡片尾号,仅展示后四位,默认不显示 | 是 | ||
loanAccountCardCnt | (多卡情况)共x个贷款账户代还,默认不展示 | 是 | ||
allCardsEnterPath | (多卡情况)若调用了“loanAccountCardCnt”,则需设置多卡显示区域设置对应的跳转路径,必填 | |||
5005 | 个人养老金账户 | totalAmount | 总资产,单位为分 | 否 |
yesterdayEarnings | 昨日收益,单位为分 | 否 | ||
cardNumber | 卡片尾号,仅展示后四位,默认不显示 | 是 | ||
pensionAccountCnt | (多卡情况)共x个养老金账户,默认不展示 | 是 | ||
allCardsEnterPath | (多卡情况)若调用了“pensionAccountCnt”,则需设置多卡显示区域设置对应的跳转路径,必填 | |||
5006 | 保险账户 | insurance_name | 保险名称 | 否 |
insurance_status | 分为三种状态:1 未生效 2 生效中 3 已过期 | 否 | ||
start_date | 时间戳,保险开始日期 | 否 | ||
end_date | 时间戳,保险结束日期 | 否 | ||
cardNumber | 卡片尾号,仅展示后四位,默认不显示 | 是 | ||
insuranceAccountCnt | (多卡情况)共x个保险,默认不展示 | 是 | ||
allCardsEnterPath | (多卡情况)若调用了“insuranceAccountCnt”,则需设置多卡显示区域设置对应的跳转路径,必填 | |||
5007 | 证券账户 | totalAmount | 总资产,单位为分 | 是 |
todayEarnings | 今日盈亏,单位为分 | 是 | ||
securitiesName | 证券名称,默认不显示 | 是 | ||
securitiesCnt | (多证券情况)全部x个证券账户,默认不展示 | 是 | ||
allSecuritiesEnterPath | (多卡情况)若调用了“securitiesCnt”,则需设置多卡显示区域设置对应的跳转路径 |
- 更新卡片状态。为了满足不同情况下的展示诉求,卡片自身是存在状态的,开发者根据需求可以通过组件的 updateStatus 接口来更新状态。目前支持的状态与变更状态的方法如下:
// 目前支持四种状态:loading、loaded、nologin,默认为 loading 态
this.updateStatus('loading') // 数据准备中,卡片会显示 loading 动画
this.updateStatus('loaded') // 数据准备完毕,卡片会正常显示
this.updateStatus('nologin') // 需要用户进入小程序登录,卡片会展示引导文案
this.updateStatus('error') //卡片状态异常,需要用户进入小程序检查卡片状态,卡片会展示引导文案
- 更新卡片点击跳转路径。卡片被点击时,默认是跳转至小程序首页,如果需要跳转到其他路径,可以通过组件的 updateEnterPath 接口来调整点击跳转路径:
this.updateEnterPath('pages/other/index')
- 隐藏/显示部分字段。由于业务原因,部分字段无法展示,开发者可以隐藏/显示该字段的展示,具体方法为:
this.showField('cardNumber')
this.hideField('remainingRepayment')
其中,需要注意的是,如5003/5004卡片有可隐藏日期的能力,需要隐藏整个日期字段
this.hideField('dueDate')
- 开发业务逻辑。目前在卡片组件内仅支持以下 wx 接口,开发者可通过以下接口实现业务逻辑:
- wx.login
- wx.checkSession
- wx.getStorage
- wx.setStorage
- wx.batchGetStorage
- wx.batchSetStorage
- wx.getStorageInfo
- wx.removeStorage
- wx.clearStorage
- wx.request
- wx.getUserCryptoManager (基础库 3.3.3 版本开始支持)
- wx.cloud.init (基础库 3.3.3 版本开始支持)
- wx.cloud.callFunction (基础库 3.3.3 版本开始支持))
注意事项:
- wx 接口调用上下文与卡片所属小程序一致,即在卡片中调用 wx 接口和在小程序中调用效果一致
- 卡片通过 wx.setStorage 或 wx.batchSetStorage 写入的数据不建议小程序侧直接依赖,因为小程序侧存在一层读缓存,可能读取不到最新写入的数据
# 3. 调试逻辑
- 开发过程中,开发者可以进入「账户详情页」,长按导航栏中的“账户”二字,打开调试面板:
- 只有体验版卡片支持输出内容到调试面板,若列表中没有体验版卡片,调试面板便无法打开。开发者可调用卡片组件的 debugLog 接口输出内容到调试面板中:
// 输出内容到调试面板上
// 目前只支持 String、Number、Boolean 等基本类型,Object 等类型则需要开发者自行进行序列化处理
if (this.debugLog) this.debugLog('str1', 'str2', 123, false, ...)
- 支持云函数,基础库版本需要3.3.3以上:示例
Component({
data: {
totalAmount: 0,
yesterdayEarnings: 0,
},
lifetimes: {
created() {
if (wx.cloud) {
wx.cloud.init({
env: 'xxxx', // 换成真实的云环境
traceUser: true,
})
}
},
attached() {
this.setData({
totalAmount: 6000000,
yesterdayEarnings: 10000,
})
this.updateStatus('loaded')
if (wx.cloud) {
// promise 形式
wx.cloud.callFunction({
name: 'xxx', // 换成真实的云函数
data: {},
}).then(res => {
console.log('[Cloud Function Call Success] Result:', res)
}).catch(err => {
console.log('[Cloud Function Call Failure] Error Message:', err)
})
// callback 形式
wx.cloud.callFunction({
name: 'xxx', // 换成真实的云函数
data: {},
success: res => {
console.log('[Cloud Function Call Success] Result:', res)
},
fail: err => {
console.log('[Cloud Function Call Failure] Error Message:', err)
},
})
}
},
},
})
注意事项:
- 卡片组件内支持组件基础生命周期(如 created、attached 等)和页面生命周期 show 和 hide,但不支持如 selectorQuery 等接口,故开发者的代码逻辑中只需要关心数据即可。
- 卡片组件内不支持使用 setTimeout、setInterval 等定时器。
- 在卡片隐藏阶段不允许调用 wx 接口。
# 4. 向用户添加卡片
- 卡片准备完成后,需要通过 addAccountCard 接口让用户主动触发添加卡片:
wx.addAccountCard({
type: 5001, // 卡片类型
success(res) {
console.log(res)
},
})
以下情况会导致用户添加失败:
- 用户已添加过该小程序同一类型的卡片
- 用户添加过,但后续从「发现-小程序」中删除卡片
- 用户添加过,但后续从「小程序右上角“…”-设置」中关闭展示开关
- 用户当前微信版本不支持此功能(需为8.0.41 for Android 及以上或8.0.46 for iOS及以上)
1.开发者可以提前通过 checkAccountCardAddState 检测卡片是否可添加、是否已添加:
wx.checkAccountCardAddState({
type: 5001, // 卡片类型
success(res) {
// res.couldAdd - 当前是否可以调用接口添加
// res.hasAdded - 当前是否已添加对应卡片组件
console.log(res)
},
})
返回的结果对应的情况:
状态描述 | couldAdd | hasAdded |
---|---|---|
正常添加,且开启 | true | true |
正常添加,手动在设置里关闭了卡片/在发现页账户里删除了卡片 | false | false |
正常添加,又完全删除小程序(在最近使用删除) | true | false |
未添加过,且符合类目要求,已经开通权限的小程序 | true | false |
注意事项:
- wx.addAccountCard 必须在触发点击行为后才可以调用。
- wx.addAccountCard 当前仅支持在体验版/正式版小程序中调用。
- 不支持重复添加同一张卡片。如果当前用户已添加卡片,必须先删除小程序后才可以触发添加。
- 目前 wx.addAccountCard 仅支持在体验版/正式版调用。如果在体验版调用,那么发现页则会拉取体验版的卡片组件分包进行展示,如果此时要重新添加正式版卡片,需要先删除体验版小程序,反之同理。
# 5. 用户取消卡片展示
用户有2个方式取消展示:
- 在小程序的设置中关闭对应卡片的开关
- 在「发现-小程序」中的账户卡片中长按可展示「删除卡片」入口,用户点击后可删除卡片的展示
注意事项:
- 若用户直接从「最近使用」中删除小程序,则会同步完全删除账户卡片。若想重新展示账户卡片,用户需要重新添加。