更新记录

v0.0.2（2026-02-04） 下载此版本

更新城市数据源

v0.0.1（2026-02-03） 下载此版本

无

平台兼容性

uni-app(5.0)

uni-app x(5.0)

uni-app 城市地区选择组件

一款兼容 uni-app 所有平台（H5、微信小程序、支付宝小程序、百度小程序、字节跳动小程序、QQ小程序、App）的城市地区选择组件。

特性

• ✅ 兼容 uni-app 所有平台
• ✅ 支持省、市、区三级选择
• ✅ 支持自定义选择层级（1-3级）
• ✅ 支持自定义数据源
• ✅ 支持自定义样式（slot）
• ✅ 支持双向绑定（v-model）
• ✅ 支持默认值设置
• ✅ 支持多种事件监听
• ✅ 支持方法调用
• ✅ 流畅的动画效果
• ✅ 内置全国省市区数据

目录结构

components/
  └── city-picker/
      ├── city-picker.vue    # 组件主文件
      └── city-data.js       # 省市区数据
pages/
  └── index/
      └── index.vue          # 测试案例页面

安装使用

1. 复制组件

将 components/city-picker 文件夹复制到你的 uni-app 项目的 components 目录下。

2. 引入组件

<template>
  <city-picker v-model="cityCode" @confirm="onConfirm" />
</template>

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

export default {
  components: { CityPicker },
  data() {
    return {
      cityCode: ''
    }
  },
  methods: {
    onConfirm(result) {
      console.log(result)
    }
  }
}
</script>

属性说明

事件说明

方法说明

使用示例

基础用法

<template>
  <city-picker v-model="city" placeholder="请选择省市区" />
</template>

自定义配置

<city-picker
  v-model="city"
  title="请选择您的地址"
  confirmText="完成"
  cancelText="关闭"
  placeholder="点击选择地址"
/>

选择层级控制

<!-- 仅选省份 -->
<city-picker v-model="province" :level="1" placeholder="请选择省份" />

<!-- 省市选择 -->
<city-picker v-model="city" :level="2" placeholder="请选择省市" />

<!-- 省市区选择（默认） -->
<city-picker v-model="district" :level="3" placeholder="请选择省市区" />

设置默认值

<template>
  <city-picker v-model="city" ref="picker" />
</template>

<script>
export default {
  mounted() {
    // 设置默认值：北京市-北京市-朝阳区
    this.$refs.picker.setValue('110000,110100,110105')
  }
}
</script>

自定义触发样式

<city-picker v-model="city">
  <view class="custom-trigger">
    <text>{{ city ? '已选择' : '点击选择' }}</text>
    <text>📍</text>
  </view>
</city-picker>

事件监听

<city-picker
  v-model="city"
  @open="onOpen"
  @confirm="onConfirm"
  @cancel="onCancel"
  @select=""
  @change="onChange"
/>

方法调用

<template>
  <city-picker ref="picker" v-model="city" />
  <button @click="openPicker">打开</button>
  <button @click="getValue">获取值</button>
  <button @click="clearPicker">清空</button>
</template>

<script>
export default {
  methods: {
    openPicker() {
      this.$refs.picker.openPicker()
    },
    getValue() {
      const result = this.$refs.picker.getValue()
      console.log(result)
    },
    clearPicker() {
      this.$refs.picker.clear()
    }
  }
}
</script>

自定义数据源

<template>
  <city-picker v-model="value" :dataSource="customData" />
</template>

<script>
export default {
  data() {
    return {
      customData: [
        {
          code: 'A001',
          name: '华东区',
          children: [
            {
              code: 'A001-1',
              name: '上海分部',
              children: [
                { code: 'A001-1-1', name: '浦东办事处' },
                { code: 'A001-1-2', name: '浦西办事处' }
              ]
            }
          ]
        }
      ]
    }
  }
}
</script>

数据结构

确认返回的数据格式

{
  province: {
    code: '110000',
    name: '北京市'
  },
  city: {
    code: '110100',
    name: '北京市'
  },
  district: {
    code: '110101',
    name: '东城区'
  },
  value: '110000,110100,110101',
  text: '北京市 / 北京市 / 东城区'
}

平台兼容性

注意事项

1. 组件使用了 rpx 单位，确保在 App.vue 中设置了正确的页面样式
2. 数据格式必须符合 { code, name, children } 的结构
3. 如果需要完整的中国省市区数据，可以扩展 city-data.js 文件

更新日志

v1.0.0

• 初始版本发布
• 支持省市区三级选择
• 支持自定义层级、数据源、样式
• 兼容 uni-app 所有平台

License

MIT