更新记录

1.1.0（2026-02-26） 下载此版本

处理无法显示的问题

1.0.0（2026-02-26） 下载此版本

省市区三级联动地址选择器组件

组件描述

这是一个基于 Vue3 + uni-app 开发的省市区三级联动地址选择器组件，提供优雅的底部弹窗式地址选择体验。组件自动处理各级行政区域的数据联动，并智能应对直辖市、无下级区域等特殊情况。

核心功能

1. 三级联动选择

• 省 → 市 → 区 三级数据联动
• 点击省级自动加载对应市级列表
• 点击市级自动加载对应区级列表
• 实时显示已选中的项目（✓ 标记）

2. 智能数据处理

• 自动处理直辖市：北京、天津、上海、重庆直接跳过市级选择
• 自动处理无下级区域：当某级无数据时，自动停留在当前层级
• 数据完整性保障：智能补全缺失的数据层级

3. 记忆功能

• 记住上次选择：再次打开时自动显示已选中的省市区
• 支持默认值传入：可通过 defaultAddress 属性预设选中项
• 自动定位选项卡：根据已选数据自动切换到对应层级

4. 流畅的交互体验

• 底部弹窗设计：从屏幕底部滑出，符合移动端操作习惯
• 固定高度：70vh 固定高度，避免滚动回弹
• 选项卡切换：点击顶部标签可自由切换省/市/区
• 实时反馈：选择项即时显示，确认后返回完整数据

5. 完善的数据返回

确认后返回完整的地址对象，包含：

• 省份信息（名称、编码）
• 城市信息（名称、编码）
• 区域信息（名称、编码）
• 完整地址字符串（如：广东省广州市天河区）

使用场景

• 电商收货地址：用户填写收货地址时选择省市区
• 个人信息编辑：编辑用户资料中的所在地信息
• 地区筛选：按地区筛选商品、店铺等
• 表单填写：各类需要选择地区的业务表单

平台兼容性

uni-app(3.6.17)

省市区地址选择器组件使用说明

快速开始

1. 引入组件

<template>
  <view>
    <!-- 触发按钮 -->
    <button @click="showAddressPicker">选择地址</button>

    <!-- 地址选择器组件 -->
    <AddressPicker 
      ref="addressPickerRef"
      @confirm="handleAddressConfirm"
      @cancel="handleAddressCancel"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'
import AddressPicker from '@/components/AddressPicker.vue'

const addressPickerRef = ref()

// 打开弹窗
function showAddressPicker() {
  addressPickerRef.value?.showPopup()
}

// 确认选择
function handleAddressConfirm(address) {
  console.log('选择的地址：', address)
  // address包含：省、市、区信息和完整地址字符串
}

// 取消选择
function handleAddressCancel() {
  console.log('已取消')
}
</script>

API说明

属性 Props

事件 Events

方法 Methods

返回数据格式

{
  province: { name: "广东省", code: "440000" },
  city: { name: "广州市", code: "440100" },
  area: { name: "天河区", code: "440106" },
  fullAddress: "广东省广州市天河区"
}

带默认值的用法

<template>
  <AddressPicker 
    ref="addressPickerRef"
    :default-address="userAddress"
    @confirm="handleAddressConfirm"
  />
</template>

<script setup>
// 默认地址数据格式
const userAddress = {
  province: { name: "广东省", code: "440000" },
  city: { name: "广州市", code: "440100" },
  area: { name: "天河区", code: "440106" }
}
</script>

环境要求

• HBuilderX 3.0+
• 需要安装 uni-popup 组件

就这么简单，开箱即用！