253 lines
5.4 KiB
Markdown
253 lines
5.4 KiB
Markdown
## 安装/更新
|
||
|
||
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) => {
|
||
|
||
})
|
||
}
|
||
})
|
||
```
|