更新记录

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

安装

  1. 方式一:插件市场搜索 ly-city-picker,点击「使用 HBuilderX 导入插件」
  2. 方式二:手动将 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 生成。

隐私、权限声明

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

定位功能需要使用方 App 自行申请定位权限

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

内置常用国内城市列表(269 城,按拼音首字母分组),仅用于城市选择展示;定位功能需使用方自行配置高德 Key

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

无

暂无用户评论。