在微信小程序开发中，地址选择是常见的需求场景，无论是电商应用的收货地址，还是出行服务的出发地选择。今天我将详细介绍如何在小程序中集成腾讯城市选择器组件，帮助你快速实现专业级的城市选择功能。

一、腾讯城市选择器组件介绍

腾讯城市选择器是腾讯官方提供的城市地址选择组件，具有以下特点：

• 数据精准：基于腾讯位置服务，数据覆盖全国省市区

• 性能优越：数据本地化，无需网络请求即可使用

• 体验一致：与微信原生体验保持一致

• 维护方便：官方持续更新维护

二、前期准备

1. 注册腾讯位置服务

在开始之前，你需要前往腾讯位置服务官网注册账号并创建应用，获取开发密钥（Key）。

2. 小程序后台配置

在小程序管理后台的「开发」-「开发管理」-「开发设置」中，添加request合法域名：

https://apis.map.qq.com

三、组件安装与引入

方法一：通过npm安装（推荐）

# 在项目根目录执行
npm install --save miniprogram-citypicker

在微信开发者工具中，点击「工具」-「构建npm」，完成构建后即可使用。

方法二：手动引入

1. 从GitHub下载组件源码

2. 将citypicker文件夹复制到项目目录中

四、基本使用

1. 引入组件

在页面的json配置文件中添加：

{
  "usingComponents": {
    "city-picker": "miniprogram-citypicker"
  }
}

2. 基础示例

WXML文件：

<view class="container">
  <!-- 显示选中的城市 -->
  <view class="selected-city" bindtap="showCityPicker">
    当前选择：{{selectedCity.province}} - {{selectedCity.city}} - {{selectedCity.district}}
  </view>
  
  <!-- 城市选择器组件 -->
  <city-picker 
    id="cityPicker"
    bindchange="onCityChange"
    theme="light"
    show-hot-city="{{true}}"
  />
</view>

JS文件：

Page({
  data: {
    selectedCity: {
      province: '北京市',
      city: '北京市',
      district: '朝阳区'
    }
  },
  
  // 显示城市选择器
  showCityPicker() {
    const cityPicker = this.selectComponent('#cityPicker')
    cityPicker.show()
  },
  
  // 城市选择变化回调
  onCityChange(e) {
    const { province, city, district } = e.detail
    this.setData({
      selectedCity: { province, city, district }
    })
    
    // 可以在这里处理选择后的逻辑，如保存到后台等
    console.log('选择的城市:', province, city, district)
  }
})

WXSS文件：

.container {
  padding: 20rpx;
}


.selected-city {
  padding: 30rpx;
  background-color: #f5f5f5;
  border-radius: 12rpx;
  text-align: center;
  margin-top: 40rpx;
  color: #333;
  font-size: 32rpx;
}

五、高级配置与自定义

1. 组件属性配置

<city-picker
  id="cityPicker"
  bindchange="onCityChange"
  bindcancel="onCityCancel"
  theme="dark"  <!-- light/dark 主题 -->
  show-hot-city="{{true}}"  <!-- 是否显示热门城市 -->
  hot-city-list="{{hotCities}}"  <!-- 自定义热门城市 -->
  default-city="{{defaultCity}}"  <!-- 默认选中城市 -->
  custom-header="{{false}}"  <!-- 是否自定义头部 -->
  show-header="{{true}}"  <!-- 是否显示头部 -->
  header-height="80"  <!-- 头部高度 -->
  animation="{{true}}"  <!-- 是否开启动画 -->
/>

2. 自定义热门城市

Page({
  data: {
    hotCities: [
      { province: '北京市', city: '北京市', district: '' },
      { province: '上海市', city: '上海市', district: '' },
      { province: '广东省', city: '广州市', district: '' },
      { province: '广东省', city: '深圳市', district: '' },
      { province: '浙江省', city: '杭州市', district: '' },
      { province: '四川省', city: '成都市', district: '' }
    ],
    defaultCity: {
      province: '广东省',
      city: '深圳市',
      district: '南山区'
    }
  }
})

3. 自定义样式

组件支持通过外部类来自定义样式：

/* 页面样式文件 */
.custom-city-picker .city-picker-header {
  background-color: #007aff !important;
}


.custom-city-picker .city-picker-tab-item.active {
  color: #007aff !important;
}

<!-- WXML中使用 -->
<city-picker class="custom-city-picker" ... />

六、实际应用案例

案例1：电商收货地址选择

Page({
  data: {
    addressInfo: {
      name: '',
      phone: '',
      province: '',
      city: '',
      district: '',
      detail: ''
    }
  },
  
  // 选择城市
  selectCity() {
    this.selectComponent('#cityPicker').show()
  },
  
  onCityChange(e) {
    const { province, city, district } = e.detail
    this.setData({
      'addressInfo.province': province,
      'addressInfo.city': city,
      'addressInfo.district': district
    })
  },
  
  // 保存地址
  saveAddress() {
    const { addressInfo } = this.data
    // 验证数据完整性
    if (!addressInfo.province || !addressInfo.city || !addressInfo.district) {
      wx.showToast({
        title: '请选择完整的地址',
        icon: 'none'
      })
      return
    }
    
    // 调用API保存地址
    wx.request({
      url: 'https://your-api.com/address/save',
      method: 'POST',
      data: addressInfo,
      success: (res) => {
        wx.showToast({
          title: '保存成功'
        })
      }
    })
  }
})

案例2：出行服务出发地/目的地选择

Page({
  data: {
    tripInfo: {
      startCity: { province: '北京市', city: '北京市', district: '' },
      endCity: { province: '上海市', city: '上海市', district: '' },
      currentSelectType: 'start' // 'start' 或 'end'
    }
  },
  
  // 选择出发城市
  selectStartCity() {
    this.setData({ currentSelectType: 'start' })
    this.selectComponent('#cityPicker').show()
  },
  
  // 选择目的城市
  selectEndCity() {
    this.setData({ currentSelectType: 'end' })
    this.selectComponent('#cityPicker').show()
  },
  
  onCityChange(e) {
    const { province, city, district } = e.detail
    const { currentSelectType } = this.data
    
    const cityKey = currentSelectType === 'start' ? 'startCity' : 'endCity'
    
    this.setData({
      [`tripInfo.${cityKey}`]: { province, city, district }
    })
  }
})

七、常见问题与解决方案

1. 组件无法显示或样式错乱

• 问题：组件没有正确引入

• 解决方案：

• 检查npm是否构建成功

• 检查组件路径是否正确

• 确认JSON配置中组件声明正确

2. 数据不更新

• 问题：选择城市后页面数据没有更新

• 解决方案：

• 确认bindchange事件正确绑定

• 检查setData方法是否正确调用

• 查看控制台是否有错误信息

3. 性能优化

• 场景：页面中多个地方需要使用城市选择器

• 解决方案：使用单例模式，只初始化一个城市选择器实例

// 创建一个城市选择器管理类
class CityPickerManager {
  constructor() {
    this.instance = null
  }
  
  getInstance(page) {
    if (!this.instance) {
      this.instance = page.selectComponent('#cityPicker')
    }
    return this.instance
  }
  
  show() {
    if (this.instance) {
      this.instance.show()
    }
  }
}


// 在app.js中全局注册
App({
  cityPickerManager: new CityPickerManager()
})

八、最佳实践建议

1. 用户体验优化：

1. 提供清晰的选择提示

2. 记住用户上次选择

3. 配合定位功能，优先显示当前位置

2. 代码组织：

1. 将城市选择逻辑封装为独立模块

2. 使用behavior共享城市选择功能

3. 统一管理城市数据相关API

3. 性能考虑：

1. 避免在多个页面重复初始化组件

2. 合理使用组件生命周期

3. 大数据量时考虑分步加载

结语

腾讯城市选择器组件为微信小程序提供了稳定、高效的城市选择解决方案。通过本文的介绍，你应该已经掌握了从基础使用到高级定制的完整知识。在实际开发中，可以根据具体业务需求灵活配置组件，结合腾讯位置服务的其他功能（如逆地址解析、路线规划等），打造更完善的地址相关功能。

如果你在集成过程中遇到任何问题，建议查阅官方文档或在GitHub上查看组件的最新更新。