@wtminiapp/api
v2.5.6
Published
1、终端使用命令安装 npm 包
Readme
安装/更新
1、终端使用命令安装 npm 包
npm install --save @wtminiapp/api@latestnpm install --save @wtminiapp/components@latest
2、在小程序开发者工具中:菜单选择工具 -> 构建 npm
使用
import {
onLoginReady,
waitLogin,
getHasTrademark,
injectApp,
injectPage,
injectComponent,
hijackApp,
hijackAllPage,
gatewayHttpClient,
baseHttpClient,
apiHttpClient,
HttpClient,
adManager,
supabase,
} from '@wtminiapp/api'waitLogin/onLoginReady - 确保登录完成
- 同步的写法
async function onLoad() {
await waitLogin()
// 此处代码将在已登录或登陆完成后执行。请求将自动携带Token
await gatewayHttpClient.request('/xxx', 'GET', {})
}- 异步的写法
function onLoad() {
onLoginReady(() => {
// 此处代码将在已登录或登陆完成后执行。请求将自动携带Token
gatewayHttpClient.request('/xxx', 'GET', {})
})
}getHasTrademark - 获取是否有商标
- 登录时由服务端下发(
hasTrademark),内部会自动waitLogin,返回Promise<boolean>
Component({
data: { hasTrademark: false },
lifetimes: {
async attached() {
this.setData({ hasTrademark: await getHasTrademark() })
}
}
})injectApp - 向App注入基础代码
- 注入之后实现自动登录、广告初始化等功能
- 参数(均可省略,省略时使用内置默认值):
- gatewayUrl / baseUrl / apiUrl: 覆盖对应的接口地址
- supaUrl / supaAnonKey: 覆盖
supabase的地址与 anon key - loginExtra: 登录请求的附加字段,详见下文「登录携带的字段」
// app.js
App(injectApp()({
// 业务代码
onLaunch() {
}
}))登录携带的字段
injectApp 触发的登录会自动携带场景值与来源信息,无需任何配置,也不必再在业务侧拦截 gatewayHttpClient.request:
{
appId, code, brand, model, platform, // 基础字段
scene, // 场景值,如 1001(发现页) / 1011(扫码) / 1007(单聊会话卡片)
path, // 启动路径
query, // 启动参数
referrerInfo // 来源小程序/公众号信息,非跳转进入时为 {}
}来源是 wx.getEnterOptionsSync()(基础库 2.9.4+,低版本自动回退到 wx.getLaunchOptionsSync())。取的是最近一次进入小程序的信息,因此 token 失效后的自动重登也能拿到当次的正确场景值。取不到时对应字段直接省略,不会阻断登录。
如需追加自定义字段(渠道号、邀请码等),用 loginExtra:
// 对象形式
App(injectApp({
loginExtra: { channel: 'ad-a' }
})({ /* 业务代码 */ }))
// 函数形式:每次登录时求值,适合值会变化的场景
App(injectApp({
loginExtra: () => ({ inviteCode: wx.getStorageSync('invite') })
})({ /* 业务代码 */ }))loginExtra 在自动采集之后合并,因此同名字段会覆盖自动值(例如 loginExtra: { scene: 9999 } 可强制指定场景值)。函数抛异常不会影响登录,仅记录日志。
injectPage - 向Page注入基础代码
- 注入之后实现页面自动统计、自动展示插屏广告以及激励视频广告的调用支持
- 参数:
- showInterstitialAd: 是否自动展示插屏广告
// pages/xxx/xxx.js
Page(injectPage({
showInterstitialAd: true
})({
// 业务代码
onLoad() {
}
}))injectComponent - 向Component注入基础代码
- 适用于使用Component构造页面的场景
- 注入之后实现页面自动统计、自动展示插屏广告以及激励视频广告的调用支持
- 参数:
- showInterstitialAd: 是否自动展示插屏广告
// pages/xxx/xxx.js
Component(injectComponent({
showInterstitialAd: true
})({
// 业务代码
methods: {
onLoad() {
}
}
}))hijackApp - 劫持全局App方法,注入基础代码
- 在不方便使用injectApp时使用(如解包后代码复杂,难以修改App调用)
- 此方法会修改全局App方法,存在未知风险,使用时请进行完整测试
- 不可与injectApp同时使用
// app.js
hijackApp()hijackAllPage - 劫持全局Page方法,注入基础代码
- 在不方便使用injectPage/injectComponent时使用(如解包后代码复杂,难以修改Page/Component调用)
- 此方法会修改全局Page方法,并影响所有的页面,存在未知风险,使用时请进行完整测试
- 参数同injectPage/injectComponent方法,不可与这些方法同时使用
// app.js
hijackAllPage({
showInterstitialAd: true
})gatewayHttpClient - 网关API调用封装
- 同步的写法
async function onLoad() {
try {
// 网关请求。参数:路径、方法、数据、其他选项(如headers、responseType)
const data = await gatewayHttpClient.request(path, method, data,options)
// 头像上传。参数:文件路径
const data = await gatewayHttpClient.uploadAvatar(filePath)
// 文件上传。参数:文件路径、数据
const data = await gatewayHttpClient.uploadFile(filePath, data)
// 文件删除。参数:文件ID
const data = await gatewayHttpClient.deleteFile(fileId)
} catch(err) {
// 响应HTTP状态码非200时自动showToast并抛出异常
}
}- 所有方法均支持异步的写法
function onLoad() {
gatewayHttpClient.request('/xxx')
.then(data => {
console.log(data)
})
.catch(err => {})
}baseHttpClient/apiHttpClient - 为老版本兼容保留,不推荐使用
HttpClient - API底层类,用于封装自定义请求
- 示例:封装一个百度的请求客户端,并调用百度搜索
const baiduHttpClient = new HttpClient({
baseURL: 'https://www.baidu.com',
timeout: 5000,
});
baiduHttpClient.request('/s', 'GET', { wd: '测试' }, { responseType: 'text' })
.then(data => console.log(data))adManager - 广告管理器
- 确保广告数据加载完成,支持同步/异步的写法
// 同步的写法
async function onLoad() {
await adManager.waitAdData()
// 此处代码将在广告数据加载完成后执行
await adManager.createAndShowInterstitialAd()
}
// 异步的写法
function onLoad () {
adManager.onDataReady(() => {
// 此处代码将在广告数据加载完成后执行
adManager.createAndShowInterstitialAd()
})
}- 广告数据
// 格式化之后的广告数据对象,如{banner: "adunit-f7709f349de05edc", custom: "adunit-34c76b0c3e4a6ed0", ...}
const ads = adManager.ads
// 友情链接顶部广告数据
const top = adManager.top
// 友情链接数据
const link = adManager.link- 创建并展示插屏广告
function onLoad() {
adManager.createAndShowInterstitialAd()
}- 创建并展示激励视频广告
- 传入当前页面的上下文this,返回用户是否已看完广告
- 由于微信的底层限制,需要先在调用的页面上进行injectPage注入,且该方法必须放在用户的点击事件里调用
- 使用示例可参考jdwx-demo
// 同步的写法
page({
async handleClick() {
const isEnded = await adManager.createAndShowRewardedVideoAd(this)
}
})
// 异步的写法
page({
handleClick() {
adManager.createAndShowRewardedVideoAd(this).then((isEnded) => {
})
}
})- 客服(作者)微信号
// 服务端下发的客服微信号,未下发时为内置默认值
const kfWx = adManager.kfWxsupabase - 数据库查询
- 链式构造查询,直接
await即可执行,无需调用 execute - 使用登录时下发的 base_token 鉴权,因此必须在
injectApp之后使用(内部会自动waitLogin) - 不会抛异常,错误统一放在返回值的
error字段里
// 查询
const { data, error } = await supabase
.from('article')
.select('id,title')
.eq('status', 1)
.order('id', { ascending: false })
.limit(10)
if (error) {
console.error(error)
} else {
console.log(data)
}返回值格式:
{ data, error, count }- data: 成功时为响应数据,失败时为 null
- error: 成功时为 null,失败时为服务端返回内容或网络错误对象
- count: 仅在使用
range()时返回总条数,其余情况为 null
过滤器
supabase.from('t').select().eq('a', 1) // a = 1
supabase.from('t').select().neq('a', 1) // a != 1
supabase.from('t').select().gt('a', 1) // a > 1,另有 lt / gte / lte
supabase.from('t').select().like('a', '%x%') // 模糊匹配,另有 ilike(忽略大小写)
supabase.from('t').select().is('a', null) // a is null
supabase.from('t').select().not('a', 'eq', 1) // not a = 1
supabase.from('t').select().or('a.eq.1,b.eq.2')
supabase.from('t').select().contains('tags', ['x', 'y'])
supabase.from('t').select().inFilter('a', [1, 2, 3]) // in 是保留字,故命名为 inFilter- 分页与单条
// 分页。使用 range 时会额外返回 count(总条数)
const { data, count } = await supabase.from('t').select().range(0, 9)
// 也可用 limit / offset
await supabase.from('t').select().limit(10).offset(20)
// 只取一条:single 查不到会返回 error,maybeSingle 查不到返回 data 为 null
const { data } = await supabase.from('t').select().eq('id', 1).single()
const { data } = await supabase.from('t').select().eq('id', 1).maybeSingle()- 写入
// 新增,支持单条或数组
await supabase.from('t').insert({ name: 'x' })
// 更新,用过滤器限定范围,data 里只写要改的字段
await supabase.from('t').update({ name: 'y' }).eq('id', 1)
// 新增或更新
await supabase.from('t').upsert({ id: 1, name: 'z' })
// 指定冲突列(需该列上有唯一约束),列名可传字符串或数组
await supabase.from('t').upsert({ openid: 'o_x', name: 'z' }, { onConflict: 'openid' })
await supabase.from('t').upsert({ a: 1, b: 2, n: 3 }, { onConflict: ['a', 'b'] })
// 删除,需配合过滤器限定范围
await supabase.from('t').delete().eq('id', 1)update支持eq等全部过滤器,且和其他写入方法一样返回更新后的行:
const { data, error } = await supabase
.from('t')
.update({ status: 2 })
.eq('id', 1)
.select('id,status')
.single()
update的平台差异:标准的 PostgREST 更新走 HTTP PATCH,但 PATCH 不在wx.request支持的 method 列表内,实际表现分两种:
- iOS / Android 真机:PATCH 能正常发出,直接走标准实现,过滤器写在 query string 里;
- 开发者工具 / PC 端微信 / 未知平台:PATCH 会被静默降级成 GET(不报错、body 被丢弃),因此自动改走等价实现——先按过滤器
SELECT出整行,在本地合并 patch 字段,再用POST+Prefer: resolution=merge-duplicates写回。读回的整行带主键,因此命中的是原记录,不会多插一条。降级路径有几点需要留意:
- 变成了两次请求,且读与写之间不是原子的,并发改同一行时后写覆盖先写;
- 因为实际执行的是 upsert,表上除 UPDATE 外还需要 INSERT 权限/RLS 策略;
- 整行写回,所以表里如果有
GENERATED ALWAYS之类不可写入的列会报错;- 过滤器没有命中任何行时不会插入新记录,返回空数组(
maybeSingle返回null),与 PATCH 行为一致。如果希望两端行为完全一致,可以只用
upsert并自行带全所需字段。
