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

# 五级联动地址选择器组件

## 组件简介

`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)
- ✨ 初始版本
- ✅ 实现五级联动选择功能
- ✅ 支持省市区县街道社区选择
- ✅ 提供完整的地址信息返回