# 小程序模板

**Repository Path**: xiaochen999/mini-program-template

## Basic Information

- **Project Name**: 小程序模板
- **Description**: 一套开箱即用的微信小程序原生开发模板
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2024-04-16
- **Last Updated**: 2025-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小程序模板

## 介绍

一套开箱即用的微信小程序原生开发模板

-   语言： Javascript
-   ui： Vant Weapp

## 快速上手

1. 安装依赖

```shell
npm install
```

2. 构建 npm

```
微信开发者工具 -> 工具 -> 构建 npm
```

## 混入 Mixins

-   介绍
    用于解决多页面重复 js 逻辑，如：分页加载，上传文件
-   代码演示

    1. 在 `app.js` 中导入 Mixins `index.js` 文件

    ```js
    // app.js
    // 导入混入模块
    require("./mixins/index.js");
    App({
        onLaunch() {},
        globalData: {},
    });
    ```

    2. 在需要 Mixins 的页面中引入即可使用

    ```js
    // pages/index/index.js
    Page({
        // 引入分页加载 mixins
        mixins: [require("../../mixins/paging")],
        data: {},
    });
    ```

## 自定义组件

已实现组件： [导航栏](#NavBar)、[文件上传](#Uploader)、[轮播图](#Banner)、[获取手机号验证码](#SendCode)、[分页列表](#PagingList)、[协议](#Agreement)。

<a id="NavBar" name="NavBar"></a>

### NavBar 导航栏

#### 介绍

基于 `van-nav-bar` 二次封装，简化使用方法。

#### 引入

在 `app.json` 或 `index.json` 中引入组件。

```json
  "usingComponents": {
    "nav-bar": "/components/nav-bar/nav-bar"
  }
```

#### 代码演示

##### 基础用法

页面中导入即可使用 。

```html
<nav-bar title="首页" has-back="{{false}}" />
```

#### Api

-   Props
    | 参数 | 说明 | 类型 | 默认值 |
    | - | - | - | - |
    | title | 上传文件列表 | string | |
    | has-back | 是否显示返回按钮 | boolean | true |
    | border | 是否显示下边框 | boolean | false |
    | color | 标题文字颜色 | string | "#000" |
    | background | 背景颜色 | string | "#fff" |
-   Events
    | 事件名 | 说明 | 回调参数 |
    | - | - | - |
    | before-back | 返回上一页前触发 | |
-   Function
    通过 selectComponent 可以获取到 NavBar 实例并调用实例方法。
    可搭配混入 `navbar.js` 使用。
    | 方法名 | 参数 | 返回值 | 说明 |
    | - | - | - | - |
    | getHeight | | 导航栏高度 | 获取导航栏高度(异步) |
-   外部样式类
    | 类名 | 说明 |
    | - | - |
    | custom-class | 根节点样式类 |

<a id="Uploader" name="Uploader"></a>

### Uploader 文件上传

#### 介绍

基于 `van-uploader` 二次封装，简化使用方法。

#### 引入

在 `app.json` 或 `index.json` 中引入组件。

```json
  "usingComponents": {
    "uploader": "/components/uploader/uploader"
  }
```

#### 代码演示

##### 基础用法

需在上传文件后 `success-uploaded` 跟删除文件后 `after-delete` 更新 `fileList` 。

```html
<uploader
    file-list="{{fileList}}"
    max-count="3"
    bind:success-uploaded="successUploaded"
    bind:after-delete="afterDelete"
/>
```

```js
Page({
    data: {
        fileList: [],
    },
    successUploaded(e) {
        const { fileList, url } = e.detail;
        this.setData({ fileList });
    },
    afterDelete(e) {
        const fileList = e.detail;
        this.setData({ fileList });
    },
});
```

#### Api

-   Props
    | 参数 | 说明 | 类型 | 默认值 |
    | - | - | - | - |
    | file-list | 上传文件列表 | array | [ ] |
    | max-count | 文件上传数量限制 | number | 1 |
    | max-size | 文件大小限制，单位为 `Mb` | number | 5 |
    | size-type | 所选的图片的尺寸, 当 accept 为 image 或 media 类型时设置所选图片的尺寸可选值为 original compressed | array | ["compressed"] |
    | preview-size | 预览图和上传区域的尺寸 | string | "160rpx" |
-   Events
    | 事件名 | 说明 | 回调参数 |
    | - | - | - |
    | success-uploaded | 每个文件成功上传后触发 | `event.detail.fileList`：成功上传后的文件列表，`event.detail.url`：服务器返回的图片路径 |
    | after-delete | 删除上传成功的图片触发 | `event.detail.fileList`：删除后的文件列表 |

<a name="Banner" id="Banner"></a>

### Banner 轮播图

#### 介绍

该组件一般用于导航轮播，广告展示等场景，使用方便。

#### 引入

在 `app.json` 或 `index.json` 中引入组件。

```json
  "usingComponents": {
    "banner": "/components/banner/banner"
  }
```

#### 代码演示

##### 基础用法

通过 `list` 参数传入轮播图列表值，该值为一个数组。

```html
<banner list="{{list}}" bind:change="onChange" bind:click="onClick" />
```

```js
Page({
    data: {
        list: [],
    },
    onChange(e) {
        const index = e.detail;
    },
    onClick(e) {
        const index = e.detail;
    },
});
```

#### Api

-   Props
    | 参数 | 说明 | 类型 | 默认值 |
    | - | - | - | - |
    | list | 轮播图列表 | Banner | [ ] |
    | height | 高度 | string | "312rpx" |
    | radius | 圆角尺寸 | string | "20rpx" |
    | fit | 图片填充模式 | string | "cover" |
    | circular | 是否采用衔接滑动 | boolean | true |
    | autoplay | 是否自动切换 | boolean | true |
    | interval | 自动切换时间间隔 | number | 5000 |
    | indicator | 是否开启指示器 | boolean | false |
    | preview | 是否开启图片预览 | boolean | false |
-   Banner 数据结构
    | 键名 | 说明 | 类型 |
    | - | - | - |
    | id | 图片唯一标识 | string \| number |
    | url | 图片路径 | string |
-   Events
    | 事件名 | 说明 | 回调参数 |
    | - | - | - |
    | change | 轮播图变化时触发 | `event.detail`：最新轮播图索引 |
    | click | 点击轮播图时触发 | `event.detail`：被点击的轮播图索引 |
-   外部样式类
    | 类名 | 说明 |
    | - | - |
    | custom-class | 根节点样式类 |
    | indicator-view-class | 指示器容器样式类 |
    | indicator-class | 指示器样式类 |

<a id="SendCode" name="SendCode"></a>

### SendCode 获取手机号验证码

#### 介绍

该组件用于获取手机号验证码，支持倒计时、校验手机号、加载中功能。

#### 引入

在 `app.json` 或 `index.json` 中引入组件。

```json
  "usingComponents": {
    "send-code": "/components/send-code/send-code"
  }
```

#### 代码演示

##### 基础用法

在 `click` 事件中请求验证码数据，请求成功则调用 `success` 回调函数，请求失败则调用 `fail` 回调函数。

```html
<send-code validate-code="{{code}}" phone="{{phone}}" bind:click="onClick" />
```

```js
Page({
  data: {
    code: "",
    phone: "",
  },
  onClick(e) {
    const { success, fail } = e.detail;
    this.getCode().then(success).catch(fail);
  },
  getCode() {
        return new Promise((resolve, reject) => {
            ...
        });
    },
});
```

#### Api

-   Props
    | 参数 | 说明 | 类型 | 默认值 |
    | - | - | - | - |
    | validate-code | 验证码 | string | |
    | phone | 手机号 | string | |
    | border | 是否显示输入框内边框 | boolean | true |
    | time | 倒计时，单位为 `s` | number | 60 |
-   Events
    | 事件名 | 说明 | 回调参数 |
    | - | - | - |
    | click | 点击发送按钮时触发 | `event.detail.success`：请求成功回调函数，`event.detail.fail`：请求失败回调函数 |

<a id="PagingList" name="PagingList"></a>

### PagingList 分页列表

#### 介绍

该组件用于列表分页加载，支持下拉刷新、触底加载、骨架屏、缺省图片、文字提示功能。

#### 引入

在 `app.json` 或 `index.json` 中引入组件。

```json
  "usingComponents": {
    "paging-list": "/components/paging-list/paging-list"
  },
  "disableScroll": true
```

#### 代码演示

##### 基础用法

该组件需要在调用组件实例方法 `init` 加载数据之前传入接口函数 `apiFun`，并监听 `list-change` 事件，更新 `list`。

> 注意： 该组件基于 `scroll-view` 实现，需要传入固定高度才能正常显示，禁止页面滚动，体验更好。

```html
<paging-list
    id="paging"
    list="{{list}}"
    apiFun="{{apiFun}}"
    height="calc(100vh - env(safe-area-inset-bottom))"
    bind:list-change="onListChange"
>
    <!-- 列表内容 -->
    <view wx:for="{{list}}" wx:key="index" class="card">{{index}}</view>
</paging-list>
```

```js
Page({
    data: {
        list: [],
        apiFun: null
    },
    onLoad(e) {
        this.setData({ apiFun: this.getData });
        this.selectComponent("#paging").init();
    },
    onListChange(e) {
        this.setData({ list: e.detail });
    },
    // 模拟接口
    async getData(params) {
        return await get...(params)
    },
});
```

可搭配混入 `paging-list.js` 使用，需要在 `onLoad` 中设置 `apiFun`

```js
Page({
    mixins:[require('@/mixins/paging-list.js')],
    onLoad(e){
        this.setData({ apiFun: getData })
    },
    // 模拟接口
    async getData(params) {
        return await get...(params)
    },
})
```

#### Api

-   Props
    | 参数 | 说明 | 类型 | 默认值 |
    | - | - | - | - |
    | list | 列表 | array | |
    | apiFun | 接口函数 | function | |
    | height | 滚动区域高度 | string | "auto" |
    | scrollbar | 是否显示滚动条 | boolean | false |
    | skeleton | 骨架屏数量 | number | 4 |
    | row | 骨架屏段落占位行数 | number | 4 |
    | title | 骨架屏是否显示标题占位图 | boolean | true |
    | image | 是否显示无数据缺省图片 | boolean | true |
    | tip | 是否显示无更多数据文字提示 | boolean | true |
-   Events
    | 事件名 | 说明 | 回调参数 |
    | - | - | - |
    | list-change | 列表更改时触发 | `event.detail`：更改后的 `list` |
    | finished | 列表无更多数据时触发 | |
-   Function
    通过 selectComponent 可以获取到 PagingList 实例并调用实例方法。
    | 方法名 | 参数 | 返回值 | 说明 |
    | - | - | - | - |
    | init | | | 初始化列表 |
    | refresh | | | 下拉刷新 |

-   外部样式类
    | 类名 | 说明 |
    | - | - |
    | custom-class | 根节点样式类 |
    | skeleton-class | 骨架屏样式类 |
    | nomore-class | 文字提示样式类 |

<a id="Agreement" name="Agreement"></a>

### Agreement 协议

#### 介绍

该组件用于同意协议，查看协议。

#### 引入

在 `app.json` 或 `index.json` 中引入组件。

```json
  "usingComponents": {
    "agreement": "/components/agreement/agreement"
  }
```

#### 代码演示

##### 基础用法

通过 `value` 绑定是否勾选协议。

```html
<agreement model:value="{{agree}}" />
```

```js
Page({
    data: {
        agree: false,
    },
});
```

#### Api

-   Props
    | 参数 | 说明 | 类型 | 默认值 |
    | - | - | - | - |
    | value | 是否勾选协议 | boolean | false |
    | texts | 协议 | array | ["用户协议"] |
-   Events
    | 事件名 | 说明 | 回调参数 |
    | - | - | - |
    | change | 当绑定值变化时触发 | `event.detail`：当前绑定值 |
    | click | 点击协议时触发 | `event.detail`：被点击协议的索引 |
-   外部样式类
    | 类名 | 说明 |
    | - | - |
    | custom-class | 根节点样式类 |