251 lines
6.5 KiB
Markdown
251 lines
6.5 KiB
Markdown
# 五级联动地址选择器组件
|
||
|
||
## 组件简介
|
||
|
||
`area-cascade-picker` 是一个支持省市区县街道社区的五级联动地址选择组件，适用于需要选择详细地址的场景。
|
||
|
||
## 功能特点
|
||
|
||
- ✅ 五级联动选择（省/市/区/街道/社区）
|
||
- ✅ 自动级联更新
|
||
- ✅ 支持取消和确认操作
|
||
- ✅ 底部弹出式交互
|
||
- ✅ 支持自定义标题
|
||
- ✅ 返回完整的地址信息和各级代码
|
||
|
||
## 使用方法
|
||
|
||
### 1. 引入组件
|
||
|
||
```vue
|
||
<template>
|
||
<view>
|
||
<button @click="openPicker">选择地址</button>
|
||
<area-cascade-picker ref="areaPicker"></area-cascade-picker>
|
||
</view>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
import AreaCascadePicker from '@/components/area-cascade-picker/area-cascade-picker.vue'
|
||
|
||
const areaPicker = ref(null)
|
||
</script>
|
||
```
|
||
|
||
### 2. 打开选择器
|
||
|
||
```javascript
|
||
const openPicker = () => {
|
||
areaPicker.value?.open({
|
||
title: '选择地址',
|
||
maskClick: true,
|
||
success: (addressData) => {
|
||
console.log('选择的地址：', addressData)
|
||
// 处理选择结果
|
||
},
|
||
cancel: () => {
|
||
console.log('取消选择')
|
||
},
|
||
change: (addressData) => {
|
||
console.log('地址变化：', addressData)
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
## API 说明
|
||
|
||
### open(config)
|
||
|
||
打开地址选择器
|
||
|
||
#### 参数 config
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| title | String | 否 | '选择地址' | 选择器标题 |
|
||
| maskClick | Boolean | 否 | false | 是否允许点击遮罩关闭 |
|
||
| success | Function | 否 | - | 确认选择的回调函数 |
|
||
| cancel | Function | 否 | - | 取消选择的回调函数 |
|
||
| change | Function | 否 | - | 选择变化的回调函数 |
|
||
| defaultValue | Object | 否 | null | 默认选中的地址（暂未实现） |
|
||
|
||
#### success 回调参数
|
||
|
||
```javascript
|
||
{
|
||
address: "新疆维吾尔自治区/喀什地区/喀什市/学府街道/学府社区居委会",
|
||
province: {
|
||
code: "650000",
|
||
name: "新疆维吾尔自治区"
|
||
},
|
||
city: {
|
||
code: "653100",
|
||
name: "喀什地区"
|
||
},
|
||
district: {
|
||
code: "653101",
|
||
name: "喀什市"
|
||
},
|
||
street: {
|
||
code: "65310101",
|
||
name: "学府街道"
|
||
},
|
||
community: {
|
||
code: "6531010101",
|
||
name: "学府社区居委会"
|
||
}
|
||
}
|
||
```
|
||
|
||
### close()
|
||
|
||
关闭地址选择器
|
||
|
||
```javascript
|
||
areaPicker.value?.close()
|
||
```
|
||
|
||
## 数据格式
|
||
|
||
组件使用树形结构的地址数据，格式如下：
|
||
|
||
```javascript
|
||
[
|
||
{
|
||
code: '650000', // 行政区划代码
|
||
name: '新疆维吾尔自治区', // 名称
|
||
children: [ // 下级行政区
|
||
{
|
||
code: '653100',
|
||
name: '喀什地区',
|
||
children: [
|
||
{
|
||
code: '653101',
|
||
name: '喀什市',
|
||
children: [
|
||
{
|
||
code: '65310101',
|
||
name: '学府街道',
|
||
children: [
|
||
{
|
||
code: '6531010101',
|
||
name: '学府社区居委会'
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
```
|
||
|
||
## 完整示例
|
||
|
||
### 企业注册地址选择
|
||
|
||
```vue
|
||
<template>
|
||
<view class="form-item" @click="selectLocation">
|
||
<text class="label">企业注册地点</text>
|
||
<view class="input-content">
|
||
<text :class="{ placeholder: !formData.address }">
|
||
{{ formData.address || '请选择注册地点' }}
|
||
</text>
|
||
<uni-icons type="arrowright" size="16"></uni-icons>
|
||
</view>
|
||
</view>
|
||
|
||
<area-cascade-picker ref="areaPicker"></area-cascade-picker>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref, reactive } from 'vue'
|
||
import AreaCascadePicker from '@/components/area-cascade-picker/area-cascade-picker.vue'
|
||
|
||
const areaPicker = ref(null)
|
||
const formData = reactive({
|
||
address: '',
|
||
provinceCode: '',
|
||
provinceName: '',
|
||
cityCode: '',
|
||
cityName: '',
|
||
districtCode: '',
|
||
districtName: '',
|
||
streetCode: '',
|
||
streetName: '',
|
||
communityCode: '',
|
||
communityName: ''
|
||
})
|
||
|
||
const selectLocation = () => {
|
||
areaPicker.value?.open({
|
||
title: '选择企业注册地点',
|
||
maskClick: true,
|
||
success: (addressData) => {
|
||
// 保存完整地址
|
||
formData.address = addressData.address
|
||
|
||
// 保存各级信息
|
||
formData.provinceCode = addressData.province?.code
|
||
formData.provinceName = addressData.province?.name
|
||
formData.cityCode = addressData.city?.code
|
||
formData.cityName = addressData.city?.name
|
||
formData.districtCode = addressData.district?.code
|
||
formData.districtName = addressData.district?.name
|
||
formData.streetCode = addressData.street?.code
|
||
formData.streetName = addressData.street?.name
|
||
formData.communityCode = addressData.community?.code
|
||
formData.communityName = addressData.community?.name
|
||
|
||
console.log('已选择地址：', formData)
|
||
}
|
||
})
|
||
}
|
||
</script>
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **数据来源**：当前使用本地模拟数据，生产环境建议接入后端API
|
||
2. **数据更新**：如需接入后端API，修改 `loadAreaData` 方法即可
|
||
3. **性能优化**：地址数据量大时，建议使用懒加载
|
||
4. **兼容性**：支持 H5、微信小程序等多端
|
||
|
||
## 接入后端API
|
||
|
||
在组件的 `loadAreaData` 方法中取消注释并配置API：
|
||
|
||
```javascript
|
||
async loadAreaData() {
|
||
try {
|
||
const resp = await uni.request({
|
||
url: '/app/common/area/cascade',
|
||
method: 'GET'
|
||
});
|
||
if (resp.statusCode === 200 && resp.data && resp.data.data) {
|
||
this.areaData = resp.data.data;
|
||
return;
|
||
}
|
||
} catch (error) {
|
||
console.error('加载地区数据失败:', error);
|
||
}
|
||
|
||
// 失败时使用模拟数据
|
||
this.areaData = this.getMockData();
|
||
}
|
||
```
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2025-10-21)
|
||
- ✨ 初始版本
|
||
- ✅ 实现五级联动选择功能
|
||
- ✅ 支持省市区县街道社区选择
|
||
- ✅ 提供完整的地址信息返回
|
||
|