template-demo/node_modules/@jdmini/api/README.md

## 安装/更新

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

```bash
npm install --save @jdmini/api@latest
```

> ```bash
> npm install --save @jdmini/components@latest
> ```

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

## 使用

```js
import {
  onLoginReady,
  waitLogin,

  injectApp,
  injectPage,
  injectComponent,
  hijackApp,
  hijackAllPage,

  gatewayHttpClient,
  baseHttpClient,
  apiHttpClient,
  HttpClient,

  adManager,
} from '@jdmini/api'
```

### `waitLogin`/`onLoginReady` - 确保登录完成

- 同步的写法

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

- 异步的写法

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

### `injectApp` - 向App注入基础代码

- 注入之后实现自动登录、广告初始化等功能

```js
// app.js
App(injectApp()({
  // 业务代码
  onLaunch() {
    
  }
}))
```

### `injectPage` - 向Page注入基础代码

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

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

  }
}))
```

### `injectComponent` - 向Component注入基础代码

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

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

    }
  }
}))
```

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

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

```js
// app.js
hijackApp()
```

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

- 在不方便使用injectPage/injectComponent时使用（如解包后代码复杂，难以修改Page/Component调用）
- 此方法会修改全局Page方法，并影响所有的页面，存在未知风险，使用时请进行完整测试
- 参数同injectPage/injectComponent方法，不可与这些方法同时使用

```js
// app.js
hijackAllPage({
  showInterstitialAd: true
})
```

### `gatewayHttpClient` - 网关API调用封装

- 同步的写法

```js
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并抛出异常
  }
}
```

- 所有方法均支持异步的写法

```js
function onLoad() {
  gatewayHttpClient.request('/xxx')
    .then(data => {
      console.log(data)
    })
    .catch(err => {})
}
```

### `baseHttpClient`/`apiHttpClient` - 为老版本兼容保留，不推荐使用

### `HttpClient` - API底层类，用于封装自定义请求

- 示例：封装一个百度的请求客户端，并调用百度搜索

```js
const baiduHttpClient = new HttpClient({
  baseURL: 'https://www.baidu.com',
  timeout: 5000,
});

baiduHttpClient.request('/s', 'GET', { wd: '测试' }, { responseType: 'text' })
  .then(data => console.log(data))
```

### `adManager` - 广告管理器

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

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

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

- 广告数据

```js
// 格式化之后的广告数据对象，如{banner: "adunit-f7709f349de05edc", custom: "adunit-34c76b0c3e4a6ed0", ...}
const ads = adManager.ads

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

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

- 创建并展示插屏广告

```js
function onLoad() {
  adManager.createAndShowInterstitialAd()
}
```

- 创建并展示激励视频广告
  - 传入当前页面的上下文this，返回用户是否已看完广告
  - 由于微信的底层限制，需要先在调用的页面上进行injectPage注入，且该方法必须放在用户的点击事件里调用
  - 使用示例可参考[jdwx-demo](https://code.miniappapi.com/wx/jdwx-demo)

```js
// 同步的写法
page({
  async handleClick() {
    const isEnded = await adManager.createAndShowRewardedVideoAd(this)
  }
})

// 异步的写法
page({
  handleClick() {
    adManager.createAndShowRewardedVideoAd(this).then((isEnded) => {
      
    })
  }
})
```