更新记录

1.0.0（2026-06-29） 下载此版本

• 首次发布
• 支持城市搜索、热门城市、字母索引、GPS 定位
• 支持微信小程序、H5、App（Android / iOS）
• 适配 iPhone 安全区滚动高度
• 提供 JS SDK、页面跳转、组件三种接入方式

平台兼容性

uni-app(4.04)

nny-choose-city 城市选择插件

uni-app Vue3 城市选择插件，支持搜索、热门城市、字母索引、GPS 定位，兼容 微信小程序 / H5 / App。

功能特性

• 全国城市数据，支持按名称搜索
• 热门城市快捷选择
• 右侧 A-Z 字母索引快速定位
• GPS 自动定位当前城市（小程序 / App 可配置腾讯地图 Key）
• H5 离线最近城市匹配（无需 Key，规避 CORS）
• 选择结果本地持久化
• iPhone 安全区 / 刘海屏滚动高度适配

平台支持

安装

方式一：插件市场（推荐）

1. 在 DCloud 插件市场 搜索 nny-choose-city
2. 点击「使用 HBuilderX 导入插件」
3. 导入时确认合并 pages_init.json 中的页面路由

方式二：手动复制

将 uni_modules/nny-choose-city 整个目录复制到你的 uni-app 项目 uni_modules 目录下，并在 pages.json 中手动注册页面（见下方「页面注册」）。

快速开始

1. 注册页面

导入插件时会自动提示合并 pages_init.json。若未自动合并，请在 pages.json 的 pages 数组中添加：

{
  "path": "uni_modules/nny-choose-city/pages/choose-city/choose-city",
  "style": {
    "navigationBarTitleText": "选择城市",
    "navigationBarBackgroundColor": "#FFFFFF",
    "disableScroll": true
  }
}

2. 初始化配置（main.js）

在 main.js 中配置腾讯地图 Key 和默认城市：

import { setPluginConfig } from '@/uni_modules/nny-choose-city/js_sdk/index.js'

setPluginConfig({
  mapKey: '你的腾讯地图Key',  // https://lbs.qq.com/ 申请
  defaultCity: {
    name: '北京',
    code: '110000',
    initial: 'B'
  }
})

3. 加载图标字体（App.vue）

微信小程序必须加载字体，否则图标不显示：

<script>
import { loadUniiconsFont } from '@/uni_modules/nny-choose-city/js_sdk/index.js'

export default {
  onLaunch() {
    loadUniiconsFont()
  }
}
</script>

<style>
@font-face {
  font-family: uniicons;
  src: url('/uni_modules/nny-choose-city/static/uniicons.ttf') format('truetype');
}
</style>

若仅使用 <nny-city-picker> 组件，组件 mounted 时也会尝试加载字体，但建议在 App.vue 全局加载一次。

4. manifest.json 权限配置

微信小程序 manifest.json → mp-weixin：

{
  "mp-weixin": {
    "permission": {
      "scope.userLocation": {
        "desc": "你的位置信息将用于定位当前城市"
      }
    },
    "requiredPrivateInfos": ["getLocation"]
  }
}

App 需开启定位模块，并配置腾讯地图 Key（app-plus → distribute → sdkConfigs → geolocation）。

使用方式

方式一：页面跳转（小程序 / App 推荐）

import {
  navigateToChooseCity,
  getSelectedCity,
  setSelectedCity
} from '@/uni_modules/nny-choose-city/js_sdk/index.js'

// 跳转选择页
navigateToChooseCity({
  (city) {
    console.log('选中城市', city)
    // { name: '上海', code: '310000', initial: 'S', hot: true }
  }
})

// 读取已选城市
const city = getSelectedCity()

也可使用 uni.navigateTo + eventChannel：

uni.navigateTo({
  url: '/uni_modules/nny-choose-city/pages/choose-city/choose-city',
  events: {
    selectCity(city) {
      console.log(city)
    }
  }
})

选择完成后页面会自动 navigateBack，同时触发全局事件 uni.$emit('citySelected', city)。

方式二：内嵌组件

<template>
  <nny-city-picker :auto-locate="true" @select="" />
</template>

<script>
export default {
  methods: {
    (city) {
      console.log(city)
    }
  }
}
</script>

nny-city-picker Props

Events

方式三：H5 全屏侧滑（推荐）

H5 单页 dev 模式下 uni.navigateTo 可能不可用，使用全屏容器组件：

<template>
  <view>
    <button @tap="showPicker = true">选择城市</button>
    <nny-city-picker-page
      :visible="showPicker"
      @close="showPicker = false"
      @select=""
    />
  </view>
</template>

<script>
import { setSelectedCity } from '@/uni_modules/nny-choose-city/js_sdk/index.js'

export default {
  data() {
    return { showPicker: false }
  },
  methods: {
    (city) {
      setSelectedCity(city)
      this.showPicker = false
    }
  }
}
</script>

JS SDK API

import {
  navigateToChooseCity,  // 跳转选择页
  setPluginConfig,       // 设置插件配置
  getPluginConfig,       // 获取插件配置
  loadUniiconsFont,      // 加载图标字体
  getSelectedCity,       // 获取已选城市
  setSelectedCity,       // 设置已选城市
  getHotCities,          // 获取热门城市列表
  cityList,              // 全部城市数据
  findCityByName,        // 按名称查找城市
  getLocationCity,       // 获取定位城市
  PAGE_PATH              // 内置页面路径常量
} from '@/uni_modules/nny-choose-city/js_sdk/index.js'

setPluginConfig 配置项

组件 easycom

插件符合 uni_modules easycom 规范（组件目录名与文件名需一致），安装后可直接使用：

• <nny-city-picker> — 城市选择核心组件
• <nny-city-picker-page> — H5 全屏侧滑容器

目录结构

uni_modules/nny-choose-city/
├── components/
│   ├── nny-city-picker/        # 核心选择组件
│   ├── nny-city-picker-page/   # H5 全屏容器
│   ├── nny-app-icon/           # 图标（内部）
│   └── uni-icons/              # 字体图标（内部）
├── js_sdk/
│   ├── index.js                # SDK 入口
│   ├── config.js               # 运行时配置
│   └── font.js                 # 字体加载
├── pages/
│   └── choose-city/            # 独立选择页
├── utils/                      # 城市数据与工具
├── static/
│   └── uniicons.ttf            # 图标字体
├── pages_init.json             # 页面自动注册
├── package.json
├── readme.md
└── changelog.md

常见问题

1. 小程序图标不显示

确保在 App.vue 中调用了 loadUniiconsFont()，并添加了 @font-face 样式。

2. 定位失败

• 检查是否配置了 mapKey（小程序 / App）
• 检查用户是否授权定位
• H5 需 HTTPS 或 localhost 环境

3. H5 无法跳转选择页

H5 dev 模式请使用 <nny-city-picker-page> 全屏组件，不要用 navigateTo。

4. 列表无法滚动 / 高度不对

选择页需设置 "disableScroll": true，由组件内部 scroll-view 控制滚动。iPhone 已做安全区适配。

发布到插件市场

1. 在 HBuilderX 中打开本项目
2. 右键 uni_modules/nny-choose-city/package.json
3. 选择「发布到插件市场」
4. 按提示填写插件信息并上传

许可证

MIT License，详见 license.md