EpicSoul/README_AreaPicker.md

省市区选择组件使用说明

概述

AreaPicker.vue 是一个功能完整的省市区三级联动选择组件，支持自定义样式插槽，可以灵活地集成到各种页面中。

功能特性

• ✅ 省市区三级联动选择
• ✅ 支持默认值设置
• ✅ 支持插槽自定义显示样式
• ✅ 完整的事件回调
• ✅ 灵活的数据请求方式
• ✅ 错误处理和容错机制

Props

参数	类型	默认值	说明
placeholder	String	'请选择'	占位符文本
defaultValue	Object	null	默认选中值，格式：{ provinceId, cityId, areaId }
disabled	Boolean	false	是否禁用

Events

事件名	参数	说明
change	data	选择改变时触发，返回选中的省市区信息

change 事件返回数据格式

{
  provinceId: '110000',    // 省份ID
  cityId: '110100',        // 城市ID
  areaId: '110101',        // 区域ID
  fullText: '北京市北京市东城区'  // 完整地址文本
}

Methods

方法名	参数	返回值	说明
getValue	-	Object	获取当前选中的值
reset	-	-	重置选择

插槽使用

组件提供了默认插槽，允许完全自定义显示样式。插槽提供以下数据：

插槽参数	类型	说明
selectedText	String	当前选中的完整文本
placeholder	String	占位符文本
provinceData	Array	省份数据列表
cityData	Array	城市数据列表
areaData	Array	区域数据列表
multiIndex	Array	当前选中的索引数组
currentSelection	Object	当前选中的详细信息

currentSelection 对象结构

{
  province: { id: '110000', name: '北京市' },
  city: { id: '110100', name: '北京市' },
  area: { id: '110101', name: '东城区' },
  fullText: '北京市北京市东城区'
}

使用示例

基本使用

<template>
  <view>
    <!-- 使用默认样式 -->
    <AreaPicker
      ref="areaPicker"
      placeholder="请选择省市区"
      :defaultValue="{ provinceId: '110000', cityId: '110100', areaId: '110101' }"
      @change="onAreaChange"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onAreaChange(data) {
      console.log('选中的地区：', data)
    }
  }
}
</script>

自定义样式（插槽）

<template>
  <view>
    <!-- 自定义样式1：简单自定义 -->
    <AreaPicker
      placeholder="请选择省市区"
      @change="onAreaChange"
    >
      <template v-slot="{ selectedText, placeholder }">
        <view class="custom-display">
          <text class="icon">📍</text>
          <text class="text">{{ selectedText || placeholder }}</text>
          <text class="arrow">▼</text>
        </view>
      </template>
    </AreaPicker>
    
    <!-- 自定义样式2：显示详细信息 -->
    <AreaPicker
      placeholder="请选择省市区"
      @change="onAreaChange"
    >
      <template v-slot="{ selectedText, placeholder, currentSelection }">
        <view class="detail-display">
          <view v-if="currentSelection.province" class="detail-info">
            <text>省：{{ currentSelection.province.name }}</text>
            <text>市：{{ currentSelection.city.name }}</text>
            <text>区：{{ currentSelection.area.name }}</text>
          </view>
          <text v-else class="placeholder">{{ placeholder }}</text>
        </view>
      </template>
    </AreaPicker>
  </view>
</template>

<script>
export default {
  methods: {
    onAreaChange(data) {
      console.log('选中的地区：', data)
    }
  }
}
</script>

<style>
.custom-display {
  display: flex;
  align-items: center;
  padding: 12px 16px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 25px;
  color: white;
}

.icon {
  margin-right: 10px;
}

.text {
  flex: 1;
}

.arrow {
  margin-left: 10px;
}

.detail-display {
  padding: 15px;
  background-color: #f8f9fa;
  border: 2px dashed #dee2e6;
  border-radius: 8px;
}

.detail-info {
  display: flex;
  flex-direction: column;
  gap: 5px;
}

.placeholder {
  color: #adb5bd;
  font-style: italic;
}
</style>

在 header 组件中使用

<template>
  <view>
    <header 
      :isSearch="true"
      :isAreaPicker="true"
      areaPlaceholder="请选择省市区"
      :defaultAreaValue="{ provinceId: '110000', cityId: '110100', areaId: '110101' }"
      @areaChange="onAreaChange"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onAreaChange(data) {
      console.log('选中的地区：', data)
    }
  }
}
</script>

数据接口要求

组件需要后端提供省市区数据接口，接口返回格式如下：

// 省份数据
[
  { id: '110000', name: '北京市' },
  { id: '120000', name: '天津市' },
  // ...
]

// 城市数据（根据省份ID获取）
[
  { id: '110100', name: '北京市', pid: '110000' },
  // ...
]

// 区域数据（根据城市ID获取）
[
  { id: '110101', name: '东城区', pid: '110100' },
  { id: '110102', name: '西城区', pid: '110100' },
  // ...
]

注意事项

1. 组件会自动处理数据请求的多种方式（父组件 Post 方法、全局 Post 方法、uni.request）
2. 建议在使用前确保数据接口正常可用
3. 插槽内容会完全替换默认的显示样式
4. 可以通过 ref 调用组件的 getValue() 和 reset() 方法
5. 组件支持设置默认值，会自动回显对应的省市区信息

完整示例

查看 AreaPickerSlotExample.vue 文件获取完整的使用示例，包含多种自定义样式的演示。