更新记录

1.0.0（2025-10-06） 下载此版本

  • 首次发布：国内右侧字母索引、国际按区域分组
  • 支持搜索，点城市即确认并回填 v-model
  • .pc 外层类名触发 PC 尺寸（变量自动减半）

平台兼容性

uni-app(4.0)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ √ √ - - - - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 快应用-华为 快应用-联盟
√ √ √ √ √ √ √ √ √ √ √

uni-city-explorer

城市选择器（浏览索引版）：国内右侧字母索引，国际按区域分组。支持在外层加 .pc 时自动应用 PC 尺寸（内部尺寸变量整体减半）。
依赖：uni_modules/uni-popup
兼容：H5 / App / 各家小程序

安装

将本插件文件夹拷贝到你的项目：


/uni_modules/uni-city-explorer

确保安装（或拷贝）：


/uni_modules/uni-popup

快速开始

1）全局注册（main.js）

import Vue from 'vue'
import CityExplorer from '@/uni_modules/uni-city-explorer'
Vue.use(CityExplorer)

也可按需引入：

import { LocationCascader } from '@/uni_modules/uni-city-explorer'
export default { components: { LocationCascader } }

2）页面示例

<template>
  <view>
    <button @click="openPicker">选择城市</button>
    <view v-if="loc">已选：{{ loc.label }}</view>

    <location-cascader
      ref="picker"
      v-model="loc"                 <!-- {scope,country,province,city,label} -->
      :default-scope="'domestic'"
      :show-scope-tabs="true"
      :show-search="true"
      @confirm="onConfirm"
    />
  </view>
</template>

<script>
export default {
  data(){ return { loc: null } },
  methods:{
    openPicker(){ this.$refs.picker.open(this.loc) },
    onConfirm(val){ console.log('confirm:', val) }
  }
}
</script>

3）PC/移动双尺寸

  • 默认按移动端尺寸；当外层有 .pc 类名时，所有关键尺寸变量自动 减半。

    • H5 直接给 body 加：
    <body class="pc">...</body>
    • App/小程序没有 body，可在页面最外层包一层：
    <view class="pc">
  <location-cascader />
</view>

API

Props

名称 类型 默认 说明
title String "选择地区" 弹窗标题
default-scope String 'domestic' 入口页签：'domestic' 国内 / 'international' 国际（含港澳台）
show-scope-tabs Boolean true 显示“国内/国际”切换
show-search Boolean true 显示搜索框
value Object null v-model 绑定值，对象结构见下

v-model 值结构（payload）

{
  scope: 'domestic' | 'international',
  country: { code, name } | null,
  province: { code, name } | null,
  city: { code, name, country?, province? },  // 必选
  label: '国内 / 上海' // 便于展示的拼接文案
}

事件

  • @confirm(payload)：点击“确定”触发
  • @change(payload)：值变化时触发
  • @input(payload)：配合 v-model

方法

  • open(initialValue?)：打开弹窗（可传 { city } 做回显）
  • close()：关闭弹窗

数据来源与替换

组件内置 MockAPI + setTimeout 模拟异步加载（国内按字母分组、国际按区域分组、搜索）。 接入真实接口时，将组件内的 MockAPI.* 改为 uni.request 即可。字段不一致可在接口回调处做适配映射。

目录结构（建议）

uni_modules/
  uni-city-explorer/
    package.json
    readme.md
    LICENSE
    index.js
    components/
      location-cascader/
        LocationCascader.vue

changelog.md 可选：发布到插件市场时建议保留版本记录；仅本地使用可省略。

许可

MIT

隐私、权限声明

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

无

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

无

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

无

许可协议

MIT协议
评论列表 撰写评论 向官方投诉

暂无用户评论。