安装/更新

1、终端使用命令安装 npm 包

npm install --save @wxshot/api@latest

2、在小程序开发者工具中：菜单选择工具 -> 构建 npm

使用

import {
  onLoginReady,
  waitLogin,

  injectApp,
  injectPage,
  injectComponent,
  hijackApp,
  hijackAllPage,

  gatewayHttpClient,
  baseHttpClient,
  apiHttpClient,
  HttpClient,

  adManager,
  supabase,
} from '@wxshot/api'

waitLogin/onLoginReady - 确保登录完成

• 同步的写法

async function onLoad() {
  await waitLogin()
  // 此处代码将在已登录或登陆完成后执行。请求将自动携带Token
  await gatewayHttpClient.request('/xxx', 'GET', {})
}

• 异步的写法

function onLoad() {
  onLoginReady(() => {
    // 此处代码将在已登录或登陆完成后执行。请求将自动携带Token
    gatewayHttpClient.request('/xxx', 'GET', {})
  })
}

injectApp - 向App注入基础代码

• 注入之后实现自动登录、广告初始化等功能
• 参数（均为可选）：
  • gatewayUrl: 自定义网关地址
  • baseUrl: 自定义基础地址
  • apiUrl: 自定义API地址
  • supaUrl: 自定义Supabase地址
  • supaAnonKey: 自定义Supabase匿名Key

// app.js
App(injectApp({
  // 可选：覆盖默认API地址
  gatewayUrl: 'https://your-gateway.com',
  supaUrl: 'https://your-supabase.com',
  supaAnonKey: 'your-anon-key',
})({
  // 业务代码
  onLaunch() {
    
  }
}))

injectPage - 向Page注入基础代码

• 注入之后实现页面自动统计、自动展示插屏广告以及激励视频广告的调用支持
• 参数：
  • showInterstitialAd: 是否自动展示插屏广告，默认 false

// pages/xxx/xxx.js
Page(injectPage({
  showInterstitialAd: true
})({
  // 业务代码
  onLoad() {

  }
}))

injectComponent - 向Component注入基础代码

• 适用于使用Component构造页面的场景
• 注入之后实现页面自动统计、自动展示插屏广告以及激励视频广告的调用支持
• 参数：
  • showInterstitialAd: 是否自动展示插屏广告，默认 false

// pages/xxx/xxx.js
Component(injectComponent({
  showInterstitialAd: true
})({
  // 业务代码
  methods: {
    onLoad() {

    }
  }
}))

hijackApp - 劫持全局App方法，注入基础代码

• 在不方便使用injectApp时使用（如解包后代码复杂，难以修改App调用）
• 此方法会修改全局App方法，存在未知风险，使用时请进行完整测试
• 不可与injectApp同时使用
• 支持与injectApp相同的配置参数

// app.js
hijackApp({
  gatewayUrl: 'https://your-gateway.com', // 可选
})

hijackAllPage - 劫持全局Page方法，注入基础代码

• 在不方便使用injectPage/injectComponent时使用（如解包后代码复杂，难以修改Page/Component调用）
• 此方法会同时修改全局Page和Component方法，影响所有页面，存在未知风险，使用时请进行完整测试
• 参数同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 myHttpClient = new HttpClient({
  baseURL: 'https://api.example.com',
  timeout: 5000,
});

myHttpClient.request('/path', 'GET', { key: 'value' }, { responseType: 'text' })
  .then(data => console.log(data))

adManager - 广告管理器

• 确保广告数据加载完成，支持同步/异步的写法

// 同步的写法
async function onLoad() {
  await adManager.waitAdData()
  // 此处代码将在广告数据加载完成后执行
  await adManager.createAndShowInterstitialAd()
}

// 异步的写法
function onLoad () {
  adManager.onDataReady(() => {
    // 此处代码将在广告数据加载完成后执行
    adManager.createAndShowInterstitialAd()
  })
}

• 广告数据

// 格式化之后的广告数据对象，如 { interstitial: "adunit-xxx", rewarded: "adunit-yyy" }
const ads = adManager.ads

// 友情链接顶部广告数据
const top = adManager.top

// 友情链接数据
const link = adManager.link

• 创建并展示插屏广告

function onLoad() {
  adManager.createAndShowInterstitialAd()
}

• 创建并展示激励视频广告
  • 传入当前页面的上下文 this，可选传入 pageId，返回用户是否已看完广告
  • 由于微信的底层限制，需要先在调用的页面上进行 injectPage 注入，且该方法必须放在用户的点击事件里调用

// 同步的写法
Page({
  async handleClick() {
    const isEnded = await adManager.createAndShowRewardedVideoAd(this)
    // 或者手动传入 pageId
    // const isEnded = await adManager.createAndShowRewardedVideoAd(this, 'custom-page-id')
  }
})

// 异步的写法
Page({
  handleClick() {
    adManager.createAndShowRewardedVideoAd(this).then((isEnded) => {
      if (isEnded) {
        // 用户已看完广告，发放奖励
      }
    })
  }
})

supabase - Supabase 数据库操作

• 链式调用风格，返回 { data, error, count } 结构
• 所有请求自动等待登录完成，无需手动 await waitLogin()

// 查询
const { data, error } = await supabase
  .from('table_name')
  .select('id, name, created_at')
  .eq('status', 1)
  .order('created_at', { ascending: false })
  .limit(10)
  .offset(0)

// 查询单条（必须有且仅有一行，否则返回 error）
const { data, error } = await supabase
  .from('table_name')
  .select()
  .eq('id', 123)
  .single()

// 查询单条（查无数据时返回 null，不报错）
const { data, error } = await supabase
  .from('table_name')
  .select()
  .eq('id', 123)
  .maybeSingle()

// 插入
const { data, error } = await supabase
  .from('table_name')
  .insert({ name: '张三', age: 18 })

// 批量插入
const { data, error } = await supabase
  .from('table_name')
  .insert([{ name: '张三' }, { name: '李四' }])

// 更新
const { data, error } = await supabase
  .from('table_name')
  .update({ name: '新名称' })
  .eq('id', 123)

// upsert（存在则更新，不存在则插入，需表有唯一约束）
const { data, error } = await supabase
  .from('table_name')
  .upsert({ user_id: uid, date: today, value: 100 })

// 删除
const { data, error } = await supabase
  .from('table_name')
  .delete()
  .eq('id', 123)

// 范围分页（count 为总行数，适合做分页器）
const { data, error, count } = await supabase
  .from('table_name')
  .select()
  .range(0, 19)

• 支持的过滤方法：

| 方法 | 说明 | 示例 | |------|------|------| | .eq(col, val) | 等于 | .eq('status', 1) | | .neq(col, val) | 不等于 | .neq('status', 0) | | .gt(col, val) | 大于 | .gt('age', 18) | | .gte(col, val) | 大于等于 | .gte('age', 18) | | .lt(col, val) | 小于 | .lt('age', 60) | | .lte(col, val) | 小于等于 | .lte('age', 60) | | .like(col, pattern) | 模糊匹配（区分大小写） | .like('name', '%张%') | | .ilike(col, pattern) | 模糊匹配（不区分大小写） | .ilike('name', '%zhang%') | | .is(col, val) | IS NULL / IS TRUE 判断 | .is('deleted_at', null) | | .not(col, op, val) | 对任意条件取反 | .not('status', 'eq', 0) | | .or(filters) | OR 条件组合 | .or('status.eq.1,status.eq.2') | | .contains(col, val) | 数组/JSON 列包含某值 | .contains('tags', ['js']) | | .inFilter(col, vals) | 值包含于指定数组 | .inFilter('id', [1, 2, 3]) | | .order(col, options) | 排序 | .order('created_at', { ascending: false }) | | .limit(n) | 限制条数 | .limit(20) | | .offset(n) | 偏移量 | .offset(40) | | .range(from, to) | 范围分页，返回值含 count 总数 | .range(0, 19) | | .single() | 返回单条，无数据报错 | .single() | | .maybeSingle() | 返回单条，无数据返回 null | .maybeSingle() |