更新记录
1.0.0(2026-11-18)
- 初始版本
- 支持省市区三级联动 / 省市两级模式
- 支持行政区划编码回显
- 返回行政区划编码与名称
- 弹层采用 page-container 容器:支持返回键/侧滑关闭弹层、遮罩点击关闭、防滚动穿透
- 支持单击条目选中(自动居中)与滑动滚轮两种选择方式
- 内置全国省市区完整数据
- 新增 data 属性,支持传入自定义数据源
- 全量可配置化:按钮文字、主题色、条目高度、可见行数、圆角、遮罩、动画时长、层级、下滑关闭均支持通过 props 配置
- 适配暗黑模式:面板/文字/分割线颜色通过 CSS 变量 +
@media (prefers-color-scheme)自动切换(Web/小程序需宿主开启 darkmode,App 端需 5.25+ 蒸汽模式);activeColor/textColor/confirmColor 默认改为空串自动适配,传值则固定颜色
平台兼容性
uni-app x(5.03)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | √ | × | √ |
ly-region-picker(省市区选择器)
uni-app x 省市区三级联动选择器组件,基于 picker-view + page-container 原生弹层容器实现,返回行政区划编码 + 名称,内置全国完整数据,支持自定义数据源、深浅色自适应与全量样式配置。
- 基础功能需 HBuilderX 5.02+(
page-container全平台最低版本要求)- App 端暗黑模式适配需 HBuilderX 5.25+(媒体查询蒸汽模式)
功能特性
- ✅ 省市区三级联动 / 省市两级(
mode切换) - ✅ 内置全国完整行政区划数据(31 省份 / 3429 节点),也可通过
data属性传入自定义数据 - ✅ 返回行政区划编码 + 名称(
{ codes, names }),value传入编码可回显选中项 - ✅ 基于
page-container:支持返回键/侧滑关闭弹层、点遮罩关闭、防滚动穿透 - ✅ 单击条目直接选中并居中,或滑动滚轮选择
- ✅ 暗黑模式自动适配(CSS 变量 +
prefers-color-scheme) - ✅ 全量可配置:按钮文字、主题色、条目高度、可见行数、圆角、遮罩、动画、层级等
平台兼容
| Android | iOS | HarmonyOS | Web |
|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ |
安装
- 方式一:插件市场搜索
ly-region-picker,点击「使用 HBuilderX 导入插件」 - 方式二:手动将
ly-region-picker文件夹复制到项目的uni_modules目录下
组件满足 easycom 规范,无需 import、无需 components 注册,模板中直接使用 <region-picker />。
快速上手
<template>
<view class="page">
<text class="cell" @click="pickerShow = true">{{ resultText == '' ? '请选择省市区' : resultText }}</text>
<region-picker
:show="pickerShow"
:value="codes"
title="选择所在地区"
@confirm="onConfirm"
@cancel="onCancel"
/>
</view>
</template>
<script setup lang="uts">
import { RegionResult } from '@/uni_modules/ly-region-picker/utssdk/data.uts'
// uni-app x 组合式 API:ref/computed 等无需 import
const pickerShow = ref(false)
const codes = ref<string[]>([])
const resultText = ref('')
const onConfirm = (e: RegionResult) => {
// e.codes: ['440000', '440300', '440305']
// e.names: ['广东省', '深圳市', '南山区']
resultText.value = e.names.join(' ')
codes.value = e.codes
}
const onCancel = () => {
pickerShow.value = false
}
</script>
<style>
.cell {
padding: 12px;
font-size: 15px;
}
</style>
组件与示例均采用组合式 API(
<script setup>)编写,兼容蒸汽模式工程。
关键点:show 由父组件控制(打开/关闭都是双向约定);确定后把 codes 传回 value,再次打开时自动回显上次选择。
省市两级模式
<region-picker
:show="show"
mode="city"
title="选择省市"
@confirm="onConfirm"
/>
mode="city" 时隐藏区县列,确认返回省、市两级数据。
完整配置示例
<region-picker
:show="show"
mode="region"
title="收货地址"
cancel-text="取消"
confirm-text="确认"
active-color="#ff5000"
confirm-color="#ff5000"
text-color="#666666"
:item-height="40"
:visible-count="7"
:round="true"
:overlay="true"
:z-index="1000"
:duration="300"
:close-on-slide-down="true"
@confirm="onConfirm"
@cancel="onCancel"
/>
API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| show | Boolean | false | 是否显示选择器 |
| mode | String | 'region' | 选择模式:region=省市区三级,city=省市两级 |
| title | String | '选择地区' | 弹层标题 |
| value | string[] | [] | 默认选中值(行政区划编码数组),打开时回显 |
| data | RegionNode[] | 内置全国数据 | 自定义数据源,结构与内置数据一致(见下方) |
| cancelText | String | '取消' | 取消按钮文字 |
| confirmText | String | '确定' | 确定按钮文字 |
| activeColor | String | ''(自动适配) | 选中项文字颜色,传空则跟随系统深浅色 |
| textColor | String | ''(自动适配) | 普通条目文字颜色,传空则跟随系统深浅色 |
| confirmColor | String | ''(自动适配) | 确定按钮颜色,传空则跟随系统深浅色 |
| itemHeight | Number | 44 | 条目高度(px),选中指示器随之自动匹配 |
| visibleCount | Number | 5 | 滚轮可见行数 |
| round | Boolean | true | 弹出层是否圆角 |
| overlay | Boolean | true | 是否显示遮罩 |
| overlayStyle | String | '' | 遮罩自定义样式(CSS 字符串) |
| zIndex | Number | 999 | 弹出层层级 |
| duration | Number | 250 | 进出动画时长(毫秒) |
| closeOnSlideDown | Boolean | false | 是否支持下滑关闭 |
事件
| 事件名 | 回调参数 | 说明 |
|---|---|---|
| confirm | RegionResult | 点击确定,返回 { codes, names } |
| cancel | 无 | 点击取消按钮、遮罩,或按返回键/侧滑关闭时触发 |
返回值示例:
{
"codes": ["440000", "440300", "440305"],
"names": ["广东省", "深圳市", "南山区"]
}
类型定义
/** 行政区划节点(utssdk/data.uts 导出) */
export type RegionNode = {
code: string // 6 位行政区划码
name: string // 行政区划名称
children: RegionNode[] // 下级节点,叶子为空数组
}
/** 确认选择结果 */
export type RegionResult = {
codes: string[] // 行政区划编码,region 模式 3 项,city 模式 2 项
names: string[] // 对应名称
}
自定义数据
通过 data 属性传入自定义数据,不传则使用内置全国省市区数据:
// RegionNode[] 结构:code 为 6 位行政区划码,叶子节点 children 为空数组
const myData: RegionNode[] = [
{
code: "440000", name: "广东省",
children: [
{
code: "440300", name: "深圳市",
children: [
{ code: "440305", name: "南山区", children: [] }
]
}
]
}
]
<region-picker :show="show" :data="myData" @confirm="onConfirm" />
典型场景:港澳台数据扩展、企业内部行政区划、仅保留部分省市等。value 编码回显与联动逻辑对自定义数据同样生效。
暗黑模式
组件内置深浅色自适应,未传颜色 props 时自动跟随系统主题:
- Web / 微信小程序:需宿主工程在
manifest.json中开启(缺了媒体查询不会生效):
{
"web": { "darkmode": true },
"mp-weixin": { "darkmode": true }
}
- App(Android/iOS/鸿蒙):HBuilderX 5.25+ 蒸汽模式下自动生效,系统切深色后弹层随之变化
- 若传入
activeColor/textColor/confirmColor,则以传入值为准(不再自动切换)
注意事项
show必须由父组件通过事件同步关闭(@cancel中置 false),组件不直接修改 props- 按返回键/侧滑会先关闭弹层并触发
cancel,不会退出页面;如需 iOS 左滑关弹层,宿主工程 pages.json 配置swipeBackAsBackPress: true(5.21+) - 内置数据不含港澳台(官方数据集无 6 位区划码),可通过
data属性自行扩展 itemHeight修改后指示器高度自动匹配,选中项仍会精确居中- 数据文件
utssdk/data.uts约 180KB,首次编译耗时略长属正常现象
FAQ
Q:确定后如何拿到选中的文字?
e.names.join(' ') 拼接即可;如需单独展示,codes/names 数组按省、市、区顺序一一对应。
Q:如何默认选中上次的值?
把上次确认返回的 codes 传给 value,打开时自动回显。
Q:只想选省市,不要区县?
设置 mode="city"。
Q:数据如何更新?
重新转换最新行政区划数据后整体替换 utssdk/data.uts 中的 regionData 常量即可,组件无需改动。
更新日志
详见 changelog.md

收藏人数:
购买普通授权版(
试用
赞赏(0)
下载 0
赞赏 0
下载 12773309
赞赏 1960
赞赏
京公网安备:11010802035340号