更新记录

1.1.0（2026-01-15） 下载此版本

初始化版本

平台兼容性

uni-app(3.7.0)

其他

城市选择插件 (City Picker) 说明文档

1. 版本及兼容性

• 针对版本：v1.0.0 (Vue 2 Options API 重构版)
• 支持平台：UniApp (H5, 微信小程序, App)
• 核心组件：采用 scroll-view 与锚点定位技术实现

2. 功能特性

• 自动定位：支持调用原生 uni.getLocation 自动获取当前所在城市。
• 热门城市：支持自定义配置顶部常用城市列表。
• 索引跳转：右侧 A-Z 字母索引条，点击可实现滚动条快速平滑跳转（锚点定位）。
• 搜索过滤：支持输入城市名或拼音实时检索，并自动定位至对应分组。
• 交互闭环：选中城市后支持确认模态框提醒，并自动返回上一页。

3. 使用方法

3.1 数据准备

插件依赖于外部城市数据文件。请确保在 @/utils/city-data.js 中定义了符合以下格式的 allCities 数据：

export const allCities = [
  {
    letter: 'A',
    list: [{ name: '阿坝' }, { name: '阿克苏' }]
  },
  // ... 其他字母分组
];

3.2 页面引入

将 index.vue 放置在您的项目页面目录中，通过常规 uni.navigateTo 即可唤起：

uni.navigateTo({
    url: '/pages/city-select/index'
});

3.3 结果接收

插件通过页面栈逻辑进行交互。当用户选择城市时，会弹出确认框，确认后通过 uni.navigateBack() 返回：

// 在插件 handleSelectCity 方法中处理选中逻辑
handleSelectCity(name) {
    uni.showModal({
        title: '确认选择',
        content: '您选择了：' + name,
        success: (res) => {
            if (res.confirm) {
                // 建议：此处可结合 uni.$emit('selectCity', name) 传值给上一个页面
                uni.navigateBack();
            }
        }
    });
}

4. 关键参数与修改指南

样式自定义 (CSS)

• 索引条位置：通过 .index-bar 修改 top 属性可调整侧边栏的垂直位置。
• 标签尺寸：修改 .tag-item 的 width 可调整热门城市的显示列数。

5. 注意事项

1. 位置权限：在小程序端使用时，需在 manifest.json 中配置 permission 字段以申请 scope.userLocation 权限。
2. 性能建议：城市列表通常较大，allCities 数据建议在页面卸载时进行销毁或采用分批渲染以优化低端机性能。