更新记录

1.0.0（2026-10-28）

• 首次发布
• 支持省市区三级联动选择
• 底部弹窗，带遮罩动画
• 支持默认选中回显
• 支持 visible.sync、change、confirm、close 事件

平台兼容性

uni-app(4.33)

其他

xin-city-select 省市区三级联动选择器

一款基于 pca-code.json 数据的省市区三级联动底部弹窗选择组件，样式参考主流电商地址选择器（含搜索、热门城市、字母索引）。

特性

• 底部弹窗 + 遮罩，带平滑动画
• 顶部搜索框，支持省份/城市/区县模糊搜索
• 热门城市快捷入口（4 列网格）
• 省份按拼音首字母分组，右侧 A-Z 字母索引导航
• 已选地区以 chip 标签展示，可点击回退重选
• 支持三种选择深度：仅省 / 省-市 / 省-市-区
• 支持默认选中值回显
• 基于 uni_modules 规范，Vue2 / Vue3 均可使用（app-vue、H5、各家小程序）

安装

将 uni_modules/xin-city-select 整个目录拷贝到你的 uni-app 项目根目录下的 uni_modules 中，即可通过 easycom 自动引入（无需 import 与注册）：

<xin-city-select :visible="show" @update:visible="show = $event" @confirm="onConfirm"></xin-city-select>

也可以显式引入：

import XinCitySelect from '@/uni_modules/xin-city-select/components/xin-city-select/xin-city-select.vue'

export default {
    components: { XinCitySelect }
}

快速使用

<template>
    <view class="page">
        <button @click="show = true">选择地区</button>
        <text v-if="resultText">已选：{{ resultText }}</text>

        <xin-city-select
            :visible="show"
            :level="3"
            :defaultValue="defaultValue"
            @update:visible="show = $event"
            @confirm="onConfirm"
            @close="onClose"
        ></xin-city-select>
    </view>
</template>

<script>
    export default {
        data() {
            return {
                show: false,
                resultText: '',
                defaultValue: [
                    { name: '湖北省', code: '420000' },
                    { name: '黄冈市', code: '421100' },
                    { name: '蕲春县', code: '421126' }
                ]
            }
        },
        methods: {
            onConfirm(e) {
                this.resultText = e.text
                console.log('选择结果', e)
            },
            onClose() {
                console.log('弹窗关闭')
            }
        }
    }
</script>

属性

事件

defaultValue 结构

[
    { name: '湖北省', code: '420000' },
    { name: '黄冈市', code: '421100' },
    { name: '蕲春县', code: '421126' }
]

confirm 回调结构

{
    province: { name: '湖北省', code: '420000' },
    city: { name: '黄冈市', code: '421100' },
    district: { name: '蕲春县', code: '421126' },
    value: ['420000', '421100', '421126'],
    text: '湖北省 黄冈市 蕲春县'
}

hotCities 结构

[
    { name: '北京', province: '北京', city: '北京市' },
    { name: '上海', province: '上海', city: '上海市' }
]

使用示例

仅选省份

<xin-city-select
    :visible="show"
    :level="1"
    @update:visible="show = $event"
    @confirm="onConfirm"
></xin-city-select>

省-市两级

<xin-city-select
    :visible="show"
    :level="2"
    @update:visible="show = $event"
    @confirm="onConfirm"
></xin-city-select>

省-市-区三级（默认）

<xin-city-select
    :visible="show"
    :level="3"
    @update:visible="show = $event"
    @confirm="onConfirm"
></xin-city-select>

说明

• 组件内置 pca-code.json 数据，无需额外请求。
• 搜索时输入任意关键词会同时匹配省、市、区三级，点击结果自动定位到对应层级。
• 热门城市点击后自动选中对应省份并进入城市选择。
• 右侧字母索引支持点击和滑动，快速定位到对应省份分组。
• 选择完当前 level 的最后一级后自动关闭弹窗并触发 confirm。
• 通过 defaultValue 传入已选值，打开时会自动回显并定位到对应层级。
• Vue3 项目中请使用 :visible="show" @update:visible="show = $event" 替代 .sync 修饰符。