更新记录

1.0.0（2025-09-02） 下载此版本

111

平台兼容性

云端兼容性

uni-app(4.07)

uni-app x(4.07)

AreaPicker 地区选择器(不支持港澳台)

简介

AreaPicker 是一个基于 uni-app 的地区选择器组件，支持省市区三级联动或省市区乡镇四级联动选择，适用于需要选择中国行政区域的场景。

安装与引入

1. 文件准备

将以下文件添加到你的项目中：

• AreaPicker.vue - 主组件文件
• area.js - 地区数据文件（需要单独准备）

2. 基本使用

<template>
  <view>
    <AreaPicker 
      v-model="selectedArea" 
      @confirm="onAreaConfirm" 
    />
  </view>
</template>

<script>
import AreaPicker from '@/components/AreaPicker/AreaPicker.vue';

export default {
  components: {
    AreaPicker
  },
  data() {
    return {
      selectedArea: ''
    }
  },
  methods: {
    onAreaConfirm(data) {
      console.log('选中的地区信息:', data);
    }
  }
}
</script>

Props 参数

Events 事件

返回数据格式

confirm 事件返回的数据结构：

{
  province: Object,     // 省份信息
  city: Object,         // 城市信息
  county: Object,       // 区县信息
  town: Object,         // 乡镇信息（四级联动时存在）
  fullName: String,     // 完整地区名称，格式如 "广东省/广州市/天河区"
  code: String          // 最细一级的地区编码
}

自定义地区数据

可以通过 treeArr 属性传入自定义的地区数据，数据格式要求如下：

[
  {
    name: '省份名称',
    code: '省份编码',
    children: [
      {
        name: '城市名称',
        code: '城市编码',
        children: [
          {
            name: '区县名称',
            code: '区县编码',
            children: [  // 四级联动时需要
              {
                name: '乡镇名称',
                code: '乡镇编码'
              }
            ]
          }
        ]
      }
    ]
  }
]

使用示例

1. 基础用法

<template>
  <AreaPicker v-model="areaValue" @confirm="onConfirm" />
</template>

<script>
export default {
  data() {
    return {
      areaValue: ''
    }
  },
  methods: {
    onConfirm(data) {
      console.log('选择的地区:', data.fullName);
      console.log('地区编码:', data.code);
    }
  }
}
</script>

2. 三级联动（省市区）

<template>
  <AreaPicker 
    v-model="areaValue" 
    :level="3" 
    @confirm="onConfirm" 
  />
</template>

3. 设置默认值

<template>
  <AreaPicker 
    v-model="areaValue" 
    default-area-text="广东省/广州市/天河区" 
    @confirm="onConfirm" 
  />
</template>

4. 使用自定义地区数据

<template>
  <AreaPicker 
    v-model="areaValue" 
    :tree-arr="customAreaData" 
    @confirm="onConfirm" 
  />
</template>

<script>
export default {
  data() {
    return {
      areaValue: '',
      customAreaData: [
        // 自定义地区数据
      ]
    }
  }
}
</script>

样式定制

组件使用了 SCSS 样式预处理器，可以通过覆盖 CSS 变量或直接修改样式来自定义外观：

主要可定制的样式变量：

• .picker-input - 输入框样式
• .confirm-btn - 确认按钮样式
• .cancel-btn - 取消按钮样式
• .picker-item - 选择项样式

注意事项

1. 组件依赖 uni-popup 和 uni-easyinput 组件，请确保已在项目中正确引入
2. 地区数据文件 area.js 需要单独准备，确保数据格式正确
3. 使用 v-model 进行双向绑定时，需要组件支持 update:modelValue 事件
4. 四级联动时需要确保数据包含乡镇级信息
5. 组件默认宽度为 100%，可根据需要在外层包裹容器控制宽度