uni-multiple-select
Version:
uni-app 多选select组件、select搜索选择页组件；支持H5、微信、百度、支付宝、头条等小程序
668 lines (536 loc) • 26.1 kB
Markdown
# uni-app 多选select组件、select搜索选择页组件
## 多选select组件
### 介绍
1. 多选select组件目前只支持多选，单选请用单选select组件
2. 支持配置关键字段
3. 兼容多平台小程序、H5
### 平台差异说明
| H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 |
| ---- | ---------- | ------------ | ---------- | ---------- |
| √ | √ | √ | √ | √ |
### 使用方式
#### 安装
```bash
npm i uni-multiple-select
```
#### 引入
**uni-app的`easycom`在打包的时候是按需引入的，您可以放心引入的组件库，发布打包时会自动剔除您没有使用的组件**
在`pages.json`里面配置如下
```json
{
"easycom": {
"^lp-(.*)": "uni-multiple-select/components/lp-$1/index.vue"
},
"pages": [
//...
]
}
```
在`vue.config.js`里面配置如下
```js
module.exports = {
transpileDependencies: [
'uni-multiple-select', 'uview-ui'
]
}
```
#### 基本使用
```html
<lp-multiple-select
v-model="show"
:list="list"
/>
```
```js
data() {
return {
// 数据源
list: [{
label: "皮皮虾",
value: "1"
},{
label: "小龙虾",
value: "2",
disabled: true // 禁用
},{
label: "大龙虾",
value: "3"
},{
label: "石头蟹",
value: "4"
}]
};
}
```
#### 默认选中项（回显）
```html
<lp-multiple-select
v-model="show"
:list="list"
:default-value="defaultSelected"
/>
```
```js
data() {
return {
defaultSelected: ["1", "4"] // 默认选中项(value)
}
}
```
#### 配置label、value对应的key名称
```html
<lp-multiple-select
v-model="show"
:list="list"
:default-value="defaultSelected"
label-name="text"
value-name="id"
@confirm="confirm"
/>
```
#### 获取点击确认后的结果
```html
<lp-multiple-select
v-model="show"
:list="list"
@confirm="confirm"
/>
```
```js
methods: {
// 确认事件
confirm(selectedData, selectedDataIds) {
console.log(selectedData, selectedDataIds);
}
}
```
#### 完整示例
```html
<template>
<view class="content">
<view class="title">多选插件演示</view>
<view class="text-area">
<text class="label">当前选中项目：</text>
<text class="value" @tap="show = true">{{info || "请选择"}}</text>
</view>
<lp-multiple-select
class="test"
v-model="show"
:list="list"
height="50"
:default-value="defaultSelected"
label-name="text"
value-name="id"
title="今日晚餐"
@confirm="confirm"
>
<template v-slot:tips>
<view class="multiple-select__empty-tips">空空如也~~</view>
</template>
</lp-multiple-select>
</view>
</template>
<script>
export default {
data() {
return {
show: false, //是否显示 - 双向绑定
list: [], //数据源
defaultSelected: ["3", "5"], // 默认选中项
info: "",
};
},
onShow() {
//模拟异步数据
setTimeout(() => {
this.list = [
{
text: "皮皮虾",
id: "1"
},
{
text: "小龙虾",
id: "2",
disabled: true // 禁用
},
{
text: "大龙虾",
id: "3"
},
{
text: "石头蟹",
id: "4"
},
{
text: "兰花蟹",
id: "5"
},
{
text: "面包蟹",
id: "6"
},
{
text: "石斑鱼",
id: "7"
},
{
text: "鲫鱼",
id: "8"
},
{
text: "鲨鱼",
id: "9"
}
]
}, 2000);
},
methods: {
// 确定事件
confirm(selectedData, selectedDataIds) {
console.log(selectedData, selectedDataIds);
this.info = selectedData.map(el => el.text).join();
}
}
};
</script>
<style scoped>
.title {
font-size: 36rpx;
color: #2088f9;
margin-top: 20vh;
text-align: center;
}
.text-area {
width: 100%;
margin-top: 5vh;
display: flex;
justify-content: center;
font-size: 28rpx;
box-sizing: border-box;
padding: 20rpx;
}
.value {
color: #2088f9;
}
.multiple-select__empty-tips {
margin-top: 25%;
text-align: center;
font-size: 40rpx;
color: #e2e2e2;
}
</style>
```
### API
#### Props
| 属性 | 说明 | 类型 | 默认值 |
| :--------------------- | :----------------------------------------------------------- | :-------------------- | :----- |
| v-model | 双向绑定控制弹出层显示 | Boolean | false |
| list | 数据源 | Array | [] |
| max | 多选时最大选择数 | Number | 99 |
| cancel-text | 取消按钮文字 | String | 取消 |
| confirm-text | 确认按钮文字 | String | 确认 |
| title | 顶部中间的标题 | String | - |
| label-name | 指定 list 中作为展示的 key | String | label |
| value-name | 指定 list 中作为 value 的 key | String | value |
| height | 弹出层高度，单位vh | Number\|String | 30 |
| z-index | 弹出时的z-index值 | Number\|String | 10075 |
| mask-close-able | 是否允许点击蒙层关闭 | Boolean | true |
| all-show | 是否显示全选 | Boolean | true |
| default-value | 默认选中值 | Array[Number\|String] | [] |
| safe-area-inset-bottom | 是否开启[底部安全区适配](https://www.uviewui.com/components/safeAreaInset.html#关于uview某些组件safe-area-inset参数的说明) | Boolean | true |
#### Option Attributes
| 属性 | 说明 | 类型 | 默认值 |
| :------- | :------------- | :------ | :----- |
| disabled | 是否禁用该选项 | boolean | false |
#### Slot
| 属性 | 说明 | 默认值 |
| :--------- | :------------------- | :-------- |
| empty-tips | 自定义空数据时的提示 | 暂无数据~ |
#### Events
| 事件名 | 说明 | 回调参数 | 版本 |
| :------ | :----------------------------- | :----------------------------------- | :--- |
| confirm | 点击确定按钮，返回当前选择的值 | 目前的选中选项[Array]与主键值[Array] | - |
| cancel | 点击取消或者点击蒙层关闭时触发 | - | - |
## select搜索选择页组件
### 介绍
1. 接口可配置
2. 支持搜索、分页、多选、单选、返回结果、插槽自定义每一项布局、配置关键字段
3. 兼容多平台、H5
### 平台差异说明
| H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 |
| ---- | ---------- | ------------ | ---------- | ---------- |
| √ | √ | √ | √ | √ |
### 使用方式
#### 安装
```bash
npm install uni-multiple-select
```
#### 引入
本组件内部使用了uview的一些组件：[Navbar](https://www.uviewui.com/components/navbar.html)、[Search](https://www.uviewui.com/components/search.html)、[Checkbox](https://www.uviewui.com/components/checkbox.html)、[ loadMore](https://www.uviewui.com/components/loadMore.html)、[Empty](https://www.uviewui.com/components/empty.html)、[Button](https://www.uviewui.com/components/button.html)，在引入上会引入uview，但是请放心，**uni-app的`easycom`在打包的时候是按需引入的，您可以放心引入的组件库，发布打包时会自动剔除您没有使用的组件**
##### 1. 引入uView主JS库
在项目根目录中的`main.js`中，引入并使用uView的JS库，注意这两行要放在`import Vue`之后。
```js
// main.js
import uView from "uview-ui";
Vue.use(uView);
```
##### 2. 在引入uView的全局SCSS主题文件
在项目根目录的`uni.scss`中引入此文件。
```css
/* uni.scss */
@import 'uview-ui/theme.scss';
```
##### 3. 引入uView基础样式
注意！
在`App.vue`中**首行**的位置引入，注意给style标签加入lang="scss"属性
```css
<style lang="scss">
/* 注意要写在第一行，同时给style标签加入lang="scss"属性 */
@import "uview-ui/index.scss";
</style>
```
##### 4. 配置easycom组件模式
在`pages.json`里面配置如下
```json
{
"easycom": {
"^u-(.*)": "uview-ui/components/u-$1/u-$1.vue", // uview-ui
"^lp-(.*)": "uni-multiple-select/components/lp-$1/index.vue" // uni-multiple-select
},
"pages": [
//...
]
}
```
在`vue.config.js`里面配置如下
```js
module.exports = {
transpileDependencies: [
'uni-multiple-select', 'uview-ui'
]
}
```
#### 基本使用
##### 1.新建`.vue`，配置页面
```json
{
"easycom": {
"^u-(.*)": "uview-ui/components/u-$1/u-$1.vue",
"^lp-(.*)": "cnpm-uni-select-wx/components/lp-$1/index.vue"
},
"pages": [
{
"path": "pages/searchSelectPage/index",
"style": {
"enablePullDownRefresh": true, // 开启下拉刷新
"navigationStyle":"custom" // 取消默认的原生导航栏
}
},
]
}
```
##### 2.基础使用
```html
<lp-search-select
url="/resume/search.json"
:isPullDownRefresh.sync="isPullDownRefresh"
:isReachBottom.sync="isReachBottom"
@confirm="confirm"
/>
```
```js
<script>
export default {
components: {},
data() {
return {
isPullDownRefresh: false, // 触发了下拉
isReachBottom: false // 触发了上拉触底
}
},
methods: {
// 确认事件
confirm(selectedList, selectedIds) {
console.log(selectedList, selectedIds);
}
},
// 下拉刷新
onPullDownRefresh() {
this.isPullDownRefresh = true
},
// 上拉加载
onReachBottom() {
this.isReachBottom = true
}
}
</script>
```
#### 默认选中项（回显）
```html
```
#### 配置label、value对应的key名称
```html
<lp-search-select
url="/resume/search.json"
:isPullDownRefresh.sync="isPullDownRefresh"
:isReachBottom.sync="isReachBottom"
valueName="resId"
labelName="userName"
@confirm="confirm"
/>
```
#### 只搜索查看，没有底部按钮
```html
html<lp-search-select
url="/resume/search.json"
:isPullDownRefresh.sync="isPullDownRefresh"
:isReachBottom.sync="isReachBottom"
:showBottomBtnGroups="false"
/>
```
#### 完整示例
```html
<template>
<view class="page">
<lp-search-select
url="/resume/search.json"
:isPullDownRefresh.sync="isPullDownRefresh"
:isReachBottom.sync="isReachBottom"
:loadText="loadText"
valueName="resId"
labelName="userName"
mode="multiple"
:searchAttrs="searchAttrs"
:navBarAttrs="navBarAttrs"
@confirm="confirm"
>
<!-- 插槽，用来修改每一项布局 -->
<template v-slot:row="{ row }">
<view class="list-wrap">
<view class="item-line">
{{ row.userName }}
</view>
<view class="item-line">
{{ row.sexName }}
</view>
</view>
</template>
</lp-search-select>
</view>
</template>
<script>
export default {
data() {
return {
isPullDownRefresh: false, // 是否触发了下拉时间
isReachBottom: false, // 是否触发了上拉事件
loadText: {
loadmore: '点击或上拉加载更多',
loading: '正在加载',
nomore: '没有更多了'
},
searchAttrs: {
'input-align': 'center'
},
navBarAttrs: {
backText: "返回"
}
}
},
methods: {
confirm(selectedList, selectedIds) {
console.log(selectedList, selectedIds);
}
},
// 下拉刷新
onPullDownRefresh() {
this.isPullDownRefresh = true
},
// 上拉加载
onReachBottom() {
this.isReachBottom = true
}
}
</script>
<style lang="scss" scoped>
.page {
.list-wrap {
height: auto;
width: 100%;
border-bottom: 2rpx dashed #cccccc;
}
}
</style>
```
### API
#### Props
| 属性 | 说明 | 类型 | 默认值 | 可选值 |
| :---------------- | :----------------------------------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- | :--------------- |
| request | http request API，***必填*** | Function | uni.request | - |
| url | 双向绑定控制弹出层显示，***必填*** | String | - | - |
| isPullDownRefresh | 是否触发了下拉加载，***必填*** | Boolean | false | true |
| isReachBottom | 是否触发了触底事件，***必填*** | Boolean | false | true |
| loadText | 底部加载的文案 | Object | { <br /> loadmore: '轻轻上拉', <br /> loading: '努力加载中', <br /> nomore: '我是有底线的~'<br />} | - |
| label-name | 指定接口返回数据中作为展示的 key | String | label | - |
| value-name | 指定接口返回数据中作为 value 的 key | String | value | - |
| keyword | 顶部搜索关键字 | String | keyword | - |
| pageSize | 每页搜索数量；建议调大点，该字段会影响页面触底，进而影响`onReachBottom`的触发 | Number\|String | 20 | - |
| query | 其他默认查询参数 | Object | - | - |
| mode | 切换单选、多选，默认多选 | String | multiple | single、multiple |
| max | 多选时最大选择数 | String\|Number | 999 | - |
| isOnlySearch | 只搜索查看，没有底部按钮和checkBox | Boolean | true | false |
| cancel-text | 取消按钮文字，必填 | Boolean | false | |
| confirm-text | 确认按钮文字 | String | 确认 | |
| default-selected | 默认选中值 | **多选**：Array[Number\|String]<br />**单选**：Number\|String | [] | - |
| checkboxColor | checkbox 颜色 | String | #007aff | |
| qs-stringify | 是否使用qs模块序列化参数 | Boolean | false | true |
| navBarAttrs | 导航栏属性 | Object | 见下方navBarAttrs | |
| searchAttrs | 搜索组件属性 | Object | 见下方searchAttrs | |
#### Option Attributes
| 属性 | 说明 | 类型 | 默认值 |
| :------- | :------------- | :------ | :----- |
| disabled | 是否禁用该选项 | boolean | false |
#### navBarAttrs
| 属性 | 说明 | 类型 | 默认值 | 可选值 |
| ------------- | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
| height | 导航栏高度(不包括状态栏高度在内，内部自动加上)，注意这里的单位是**px** | String \| Number | 44 | - |
| backIconColor | 左边返回图标的颜色 | String | #606266 | - |
| backIconName | 左边返回图标的名称，只能为uView自带的图标，`1.5.5`起由arrow-left调整为nav-back | String | nav-back | [Icon](https://www.uviewui.com/components/icon.html) |
| backIconSize | 左边返回图标的大小，单位rpx | String \| Number | 30 | - |
| backText | 返回图标右边的辅助提示文字 | String | - | - |
| backTextStyle | 返回图标右边的辅助提示文字的样式，对象形式 | Object | { color: '#606266' } | - |
| zIndex | 固定在顶部时的`z-index`值 | String \| Number | 980 | - |
| isBack | 是否显示导航栏左边返回图标和辅助文字 | Boolean | true | false |
| background | 导航栏背景设置(APP和小程序上包括状态栏的颜色)，见上方说明 | Object | { backgroundImage: 'linear-gradient(45deg, rgb(28, 187, 180), rgb(141, 198, 63))' } | - |
| borderBottom | 导航栏底部是否显示下边框，如定义了较深的背景颜色，可取消此值 | Boolean | true | false |
| customBack | 自定义返回逻辑方法，如传入，点击返回按钮执行函数，否则正常返回上一页，注意模板中不需要写方法参数的括号 | Function | - | - |
#### searchAttrs
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| ---------------- | ------------------------------------------------------------ | ---------------- | ------------ | ---------------------------------------------------- |
| shape | 搜索框形状，round-圆形，square-方形 | String | round | square |
| bgColor | 搜索框背景颜色 | String | #f2f2f2 | - |
| borderColor | 边框颜色，配置了颜色，才会有边框 | String | - | - |
| placeholder | 占位文字内容 | String | 请输入关键字 | - |
| clearabled | 是否启用清除控件 | Boolean | true | false |
| focus | 是否自动获得焦点 | Boolean | false | true |
| showAction | 是否显示右侧控件(右侧的"搜索"按钮) | Boolean | true | false |
| actionText | 右侧控件文字 | String | 搜索 | - |
| actionStyle | 右侧控件的样式，对象形式 | Object | - | - |
| inputAlign | 输入框内容水平对齐方式 | String | left | center / right |
| height | 输入框高度，单位rpx | String \| Number | 64 | - |
| searchIconColor | 搜索图标的颜色，默认同输入框字体颜色 | String | - | - |
| color | 输入框字体颜色 | String | #606266 | - |
| placeholderColor | placeholder的颜色 | String | #909399 | - |
| margin | 组件与其他上下左右元素之间的距离，带单位的字符串形式，如"30rpx"、"30rpx 20rpx"等写法 | String | - | - |
| maxlength | 输入框最大能输入的长度，-1为不限制长度 | String \| Number | -1 | - |
| inputStyle | 自定义输入框样式，对象形式 | Object | - | - |
| searchIcon | 输入框左边的图标，可以为uView图标名称或图片路径 | String | search | [Icon](https://www.uviewui.com/components/icon.html) |
#### Slot
| 属性 | 说明 |
| :--- | :--------------- |
| row | 自定义每一项布局 |
#### Events
| 事件名 | 说明 | 回调参数 | 版本 |
| :------ | :----------------------------- | :----------------------------------------------------------- | :--- |
| confirm | 点击确定按钮，返回当前选择的值 | 多选：目前的选中选项[Array]与主键值[Array]<br />单选：目前的选中选项[Object] | - |
| cancel | 点击取消按钮 | - | - |