更新记录

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
✓ ✓ ✓ ✓

安装

  1. 方式一:插件市场搜索 ly-region-picker,点击「使用 HBuilderX 导入插件」
  2. 方式二:手动将 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,则以传入值为准(不再自动切换)

注意事项

  1. show 必须由父组件通过事件同步关闭(@cancel 中置 false),组件不直接修改 props
  2. 按返回键/侧滑会先关闭弹层并触发 cancel,不会退出页面;如需 iOS 左滑关弹层,宿主工程 pages.json 配置 swipeBackAsBackPress: true(5.21+)
  3. 内置数据不含港澳台(官方数据集无 6 位区划码),可通过 data 属性自行扩展
  4. itemHeight 修改后指示器高度自动匹配,选中项仍会精确居中
  5. 数据文件 utssdk/data.uts 约 180KB,首次编译耗时略长属正常现象

FAQ

Q:确定后如何拿到选中的文字? e.names.join(' ') 拼接即可;如需单独展示,codes/names 数组按省、市、区顺序一一对应。

Q:如何默认选中上次的值? 把上次确认返回的 codes 传给 value,打开时自动回显。

Q:只想选省市,不要区县? 设置 mode="city"。

Q:数据如何更新? 重新转换最新行政区划数据后整体替换 utssdk/data.uts 中的 regionData 常量即可,组件无需改动。

更新日志

详见 changelog.md

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

内置数据为国家统计局县及县以上行政区划代码,仅用于地址选择展示

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。