@xlt-group/xlt-region
Version:
210 lines (154 loc) • 5.76 kB
Markdown
# Region 行政区域选择器
简洁强大的中国行政区划选择器，可选择 “省/直辖市”、“市”、“区/县”、“乡/镇/街道” 4 级行政区域
行政区划数据源:来自插件`@gok/area-data`
## 功能特性
- 支持 “省/直辖市”、“市”、“区/县”、“乡/镇/街道” 4 级行政区域选择
- 除省级和市级以外，其它行政区域级别允许通过参数进行“打开/关闭”
- 支持数据双向绑定
- 支持设置默认值
## 后续计划
- [x] 打包实现三级行政区域选择器，不包含街道
- [ ] 城市选择器模式
- [ ] 支持自定义数据源
- [ ] 按拼音首字母分组排序的功能
## 安装插件
使用`npm/pnpm`把插件安装到项目中
```shell
# npm
npm install @xlt-group/xlt-region
# pnpm
pnpm add @xlt-group/xlt-region
```
在项目入口`main.js`中引入插件
```js
import Vue from 'vue'
import XltRegion from '@xlt-group/xlt-region' # 四级行政区域
import XltRegion from '@xlt-group/xlt-region/no-street' #三级行政区域
Vue.use(XltRegion)
```
自定义全局注册组件
```js
import Vue from 'vue'
import {XRegion} from '@xlt-group/xlt-region'
Vue.component('x-region', XRegion)
```
在页面/模块中使用
```vue
<template>
<x-region @on-change="regionChange"/>
</template>
<script>
export default {
methods: {
// 选择器值改变时触发
regionChange(data) {
console.log(data)
}
}
}
</script>
```
使用本地注册的组件
```vue
<template>
<x-region @on-change="regionChange"/>
</template>
<script>
import {XRegion} from '@xlt-group/xlt-region
export default {
components: {
XRegion
},
methods: {
// 选择器值改变时触发
regionChange(data) {
console.log(data)
}
}
}
</script>
```
使用数据双向绑定`v-model`
```vue
<script>
export default {
name: 'App',
data() {
return {
areaData: {},
}
},
watch: {
areaData(val) {
console.log(val, 35)
//{area:150522,city:1505,province:15,street:150522208}
}
}
}
</script>
<template>
<div id="app">
<city-region v-model="areaData"></city-region>
</div>
</template>
```
使用默认值
```vue
<script>
export default {
name: 'App',
data() {
return {
areaData: {
area: 150522,
city: 1505,
province: 15,
street: 150522208,
}
}
},
watch: {
areaData(val) {
console.log(val, 35)
}
},
}
</script>
<template>
<div id="app">
<city-region v-model="areaData"></city-region>
</div>
</template>
```
## 入参选项
| 参数 | 说明 | 类型 | 默认值 | 必填 | 示例 |
|-----------------|---------------------------------------------------------------------|---------|------|-------|-----------------------------------------|
| value/v-model | 初始化行政区划选中项目 province 省、直辖市及特别行政区编码,city 城市编码,area 区/县编码,street 乡镇编码 | object | {} | false | {province:'',city:'',area:'',street:''} |
| level | 需要展示的层级 level=3 展示区县 level=4 展示乡镇 | Number | 4 | false | 4 |
| separator | 区域文本间的分隔符 | String | / | false | / |
| mouseLeaveClose | 鼠标离开选择器是否关闭下拉菜单 | Boolean | true | false | true |
## 事件
| 事件名称 | 说明 | 返回数据 |
|-----------|--------------------------------------------------------------------|----------------------------------------------------------------------------------|
| on-change | 响应已选中的行政区划完整数据模型 | `{address:[15,1505,150522,150522208],select:[{n:'内蒙古自治区',i:15,p:0,y:'n'},....]}` |
## 测试报告
XltRegion
- [x] 默认当前选中行政区域tab为省份 (4ms)
- [x] 默认展示34个省份 (4ms)
- [x] 默认操作栏标题展示'选择省份/地区' (2ms)
- [x] 点击省份/地区的'暂不选择'，关闭弹窗，返回值为空 (5ms)
- [x] 选择'福建省'，当前级别自动切换至'市'级 (23ms)
- [x] 点击市的'暂不选择'，关闭弹窗，返回值为省级有值，市为空 (2ms)
- [x] 选择'福州市'，当前级别自动切换至'区/县' (15ms)
- [x] 点击区县的'暂不选择'，关闭弹窗，返回值为省，市，区县为空 (3ms)
- [x] 选择'鼓楼区'，当前级别自动切换至'街道/乡镇' (9ms)
- [x] 点击街道的'暂不选择'，关闭弹窗，返回值为省，市，区县，街道/乡镇为空 (3ms)
- [x] 选择'东街街道'，关闭弹窗，返回选中后的值 (4ms)
- [x] 再次打开选择器，默认选中'街道/乡镇','东街街道'高亮显示 (2ms)
- [x] 切换tab至'区/县'，'鼓楼区'选中高亮 (4ms)
- [x] 切换tab至'市'，'福州市'选中高亮 (3ms)
- [x] 切换tab至'省'，'福建省'选中高亮 (15ms)
- [x] 使用对象对v-model/value 设置默认值 (36ms)
- [x] 使用数组对v-model/value 设置默认值 (25ms)
- [x] 点击 X 图标，所有选中行政区域数据应该被清空 (8ms)
