更新记录

1.0.0（2025-08-22） 下载此版本

上传省市区三级联动组件

平台兼容性

uni-app(4.45)

uni-app x(4.43)

城市选择器组件 (CityPicker)

组件说明

城市选择器组件，用于选择省份、城市和区县。组件采用固定定位，确保在正确的层级显示。 组件已改为使用本地模拟数据，方便开源使用，无需依赖外部接口。

✨ 更新说明

• ✅ 已改为本地数据: 不再依赖外部接口，使用本地模拟数据
• ✅ 开源友好: 可以直接使用，无需配置接口
• ✅ 数据完整: 包含多个省份的完整省市区数据
• ✅ 易于扩展: 可以轻松添加更多省份和城市数据

使用方法

1. 引入组件

import CityPicker from '@/components/city-picker/city-picker.vue'

export default {
  components: {
    CityPicker
  }
}

2. 在模板中使用

<template>
  <!-- 城市选择器组件 -->
  <city-picker
    :visible="showCitySelector"
    :defaultCityCode="selectedCity"
    :defaultCityName="selectedCityName"
    @confirm="onCityConfirm">
  </city-picker>

  <!-- 城市选择器遮罩层 -->
  <view v-if="showCitySelector" class="city-selector-mask" @click="closeCitySelector"></view>
</template>

Props 属性

Events 事件

本地数据说明

组件使用本地模拟数据，数据文件位于 data/mock-city-data.js：

包含省份: 北京、天津、上海、重庆、河北、山西、广东、江苏等

数据格式: 标准的省市区三级联动数据结构：

// 本地数据结构
{
  code: 200,
  message: "success",
  data: {
    districts: [
      {
        name: "中华人民共和国",
        adcode: "100000",
        districts: [
          {
            name: "北京市",        // 省份名称
            adcode: "110000",      // 省份代码
            districts: [
              {
                name: "北京市",    // 城市名称
                adcode: "110100",  // 城市代码
                districts: [       // 区县数组
                  {
                    name: "东城区",     // 区县名称
                    adcode: "110101"   // 区县代码
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

// 确认选择时返回的数据格式
{
  districtCode: "110101",           // 区县代码
  districtName: "东城区",           // 区县名称
  cityCode: "110100",               // 城市代码
  cityName: "北京市",               // 城市名称
  provinceCode: "110000",           // 省份代码
  provinceName: "北京市",           // 省份名称
  fullAddress: "北京市-北京市-东城区" // 完整地址
}

扩展数据

如需添加更多省份和城市，请编辑 data/mock-city-data.js 文件，按照相同的数据结构添加即可。

样式特点

1. 固定定位: 使用 position: fixed 确保组件在正确位置显示
2. 层级管理: 设置 z-index: 1001 确保在其他元素之上
3. 响应式布局: 左侧省份列表固定宽度，右侧城市列表自适应
4. 滚动支持: 省份和城市列表都支持滚动查看
5. 加载状态: 显示数据加载状态，提升用户体验

功能特性

1. 本地数据: 使用本地模拟数据，无需网络请求
2. 三级联动: 支持省份、城市、区县三级选择
3. 数据缓存: 数据加载后缓存，避免重复加载
4. 错误处理: 完善的错误处理和用户提示
5. 加载状态: 模拟加载状态，提升用户体验
6. 默认选中: 支持设置默认选中的区县
7. 开源友好: 无需配置接口，开箱即用

注意事项

1. 需要配合遮罩层使用，点击遮罩层关闭选择器
2. 组件会自动处理默认选中状态
3. 数据文件 data/mock-city-data.js 需要正确导入
4. 组件内部会重置选择状态，避免状态混乱
5. 可以根据需要扩展更多省份和城市数据

测试页面

项目中包含测试页面 pages/test-city-picker/test-city-picker.vue，可以用来测试组件功能。