ks-app-employment-service/components/area-cascade-picker/README.md

五级联动地址选择器组件

组件简介

area-cascade-picker 是一个支持省市区县街道社区的五级联动地址选择组件，适用于需要选择详细地址的场景。

功能特点

• ✅ 五级联动选择（省/市/区/街道/社区）
• ✅ 自动级联更新
• ✅ 支持取消和确认操作
• ✅ 底部弹出式交互
• ✅ 支持自定义标题
• ✅ 返回完整的地址信息和各级代码

使用方法

1. 引入组件

<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. 打开选择器

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 回调参数

{
    address: "新疆维吾尔自治区/喀什地区/喀什市/学府街道/学府社区居委会",
    province: {
        code: "650000",
        name: "新疆维吾尔自治区"
    },
    city: {
        code: "653100",
        name: "喀什地区"
    },
    district: {
        code: "653101",
        name: "喀什市"
    },
    street: {
        code: "65310101",
        name: "学府街道"
    },
    community: {
        code: "6531010101",
        name: "学府社区居委会"
    }
}

close()

关闭地址选择器

areaPicker.value?.close()

数据格式

组件使用树形结构的地址数据，格式如下：

[
    {
        code: '650000',           // 行政区划代码
        name: '新疆维吾尔自治区',  // 名称
        children: [               // 下级行政区
            {
                code: '653100',
                name: '喀什地区',
                children: [
                    {
                        code: '653101',
                        name: '喀什市',
                        children: [
                            {
                                code: '65310101',
                                name: '学府街道',
                                children: [
                                    {
                                        code: '6531010101',
                                        name: '学府社区居委会'
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

完整示例

企业注册地址选择

<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：

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)

• ✨ 初始版本
• ✅ 实现五级联动选择功能
• ✅ 支持省市区县街道社区选择
• ✅ 提供完整的地址信息返回