更新记录
1.0.0(2026-11-18)
- 初始版本
- 全屏弹层城市选择器(page-container 容器:支持返回键/侧滑关闭弹层、防滚动穿透)
- 内置 269 个常用国内城市,按拼音首字母分组(22 组),支持 data 属性传入自定义数据
- 支持按城市名/分组字母搜索
- 热门城市(含「全国」)可配置
- 本地历史记录(uni storage 持久化,条数可配置,可关闭)
- 定位回填当前位置:uni.getLocation 取坐标 + 高德逆地理编码解析城市名(需使用方配置 amapKey);使用 wgs84 坐标(系统定位均可返回,gcj02 需三方定位 SDK),自动定位失败时延迟重试一次(覆盖首次打开权限弹窗未确认的场景),直辖市回退取省份名
- 右侧字母索引条:触摸滑动快选,scroll-into-view 锚点定位
- 当前选中城市高亮标记(currentCity)
- 选中高亮色 activeColor 可配置,默认跟随深浅色主题
- 适配暗黑模式:背景/文字/胶囊/分割线颜色通过 CSS 变量 +
@media (prefers-color-scheme)自动切换(Web/小程序需宿主开启 darkmode,App 端需 5.25+ 蒸汽模式)
平台兼容性
uni-app x(5.03)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | √ |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | √ | × | √ |
ly-city-picker(城市选择器)
uni-app x 全屏城市选择器组件,基于 page-container 原生弹层容器实现。内置常用国内城市(按拼音首字母分组),支持搜索、热门城市、历史记录、定位回填、字母索引快选,支持自定义城市数据、主题色与深浅色自适应。
- 基础功能需 HBuilderX 5.02+(
page-container全平台最低版本要求)- App 端暗黑模式适配需 HBuilderX 5.25+(媒体查询蒸汽模式)
- 定位功能需宿主 App 已申请定位权限,并配置高德 Web 服务 Key(amapKey)才能解析城市名
功能特性
- ✅ 全屏弹层:基于
page-container,支持返回键/侧滑关闭、防滚动穿透 - ✅ 内置 269 个常用国内城市(22 个字母分组),也可通过
data属性传入自定义数据 - ✅ 搜索:按城市名模糊匹配,或按分组字母精确匹配
- ✅ 热门城市可配置(空字符串代表「全国」)
- ✅ 历史记录:本地持久化(uni storage),条数可配置,可整体关闭
- ✅ 定位回填:
uni.getLocation+ 高德逆地理编码,自动定位当前城市(需配置amapKey) - ✅ 右侧字母索引条:触摸滑动快选(实测布局定位,精确到分组)
- ✅ 当前选中城市高亮标记(
currentCity) - ✅ 暗黑模式自动适配(CSS 变量 +
prefers-color-scheme)
平台兼容
| Android | iOS | HarmonyOS | Web |
|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ |
安装
- 方式一:插件市场搜索
ly-city-picker,点击「使用 HBuilderX 导入插件」 - 方式二:手动将
ly-city-picker文件夹复制到项目的uni_modules目录下
组件满足 easycom 规范,无需 import、无需 components 注册,模板中直接使用 <city-picker />。
快速上手
<template>
<view class="page">
<text class="cell" @click="pickerShow = true">
{{ cityText == '' ? '请选择城市' : cityText }}
</text>
<city-picker
:show="pickerShow"
:current-city="cityText"
@select=""
@close="pickerShow = false"
/>
</view>
</template>
<script setup lang="uts">
// uni-app x 组合式 API:ref/computed 等无需 import
const pickerShow = ref(false)
const cityText = ref('')
const = (city: string) => {
// 空字符串代表「全国」
cityText.value = city == '' ? '全国' : city
pickerShow.value = false
}
</script>
启用定位回填
在 高德开放平台 申请 Web 服务 Key,通过 amapKey 传入即可。打开弹层时自动静默定位并回填「当前位置」,用户也可手动点击重新定位。
<city-picker
:show="pickerShow"
:current-city="cityText"
amap-key="你的高德Web服务Key"
@select=""
@close="pickerShow = false"
/>
不配置
amapKey时「当前位置」展示为「未定位」,手动点击会提示配置 Key,其余功能不受影响。
定位平台说明
- uni-app x 采用摇树机制自动集成定位模块,无需在 manifest 中手动勾选定位模块
- 组件使用
type: 'wgs84'坐标:系统定位(浏览器/Android/iOS 系统定位)均可直接返回;gcj02在 Web/Android/iOS 端需要额外配置三方定位 SDK(provider)才能支持。wgs84 与 gcj02 存在数百米偏移,但不影响城市级逆地理解析 - Web 端:需在 HTTPS(或 localhost)环境下运行,浏览器会弹出定位授权;高德 REST API 支持跨域请求
- App 端:首次定位会触发系统定位权限申请,需用户同意
- 高德 Key 要求:申请「Web 服务」类型的 Key;若在控制台开启了 IP/域名白名单,需将实际调用环境加入白名单
- 直辖市(北京/上海/重庆等)高德返回的
city为空数组,组件自动回退取province
API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| show | boolean | false | 是否显示 |
| currentCity | string | '' | 当前已选城市名,用于高亮标记 |
| data | CityGroup[] | 内置数据 | 自定义城市数据,按字母分组 |
| hotCities | string[] | 20 个热门城市 | 热门城市列表,空字符串代表「全国」 |
| enableHistory | boolean | true | 是否启用本地历史记录 |
| historyMax | number | 8 | 历史记录最大条数 |
| storageKey | string | 'lyCityPickerHistory' | 历史记录存储 key |
| enableLocation | boolean | true | 是否启用定位功能 |
| amapKey | string | '' | 高德 Web 服务 Key(逆地理编码解析城市名) |
| activeColor | string | '' | 选中高亮色,空串跟随系统深浅色 |
| zIndex | number | 999 | 弹出层层级 |
| duration | number | 250 | 进出动画时长(毫秒) |
| closeOnSlideDown | boolean | true | 是否支持下滑关闭 |
事件
| 事件 | 参数 | 说明 |
|---|---|---|
| select | city: string | 选择城市时触发,空字符串代表「全国」 |
| close | - | 关闭弹层时触发,请在此处将 show 置为 false |
自定义数据格式
// uni_modules/ly-city-picker/utssdk/data.uts
export type CityGroup = {
letter: string // 分组字母(A-Z)
list: string[] // 该分组下的城市名列表
}
export const cityData: CityGroup[] = [
{ letter: 'A', list: ['阿坝', '阿克苏', ...] },
...
]
传入 data 时需保证分组按字母升序排列,索引条锚点依赖 letter 生成。

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