CityPicker 城市选择器完全指南Android 省市区三级联动 10 分钟集成教程【免费下载链接】citypickercitypicker城市选择器详细的省市区地址信息支持仿iOS滚轮实现仿京东样式一级或者三级列表展示方式。项目地址: https://gitcode.com/gh_mirrors/ci/citypicker做 App 迟早会碰到地址选择收货地址、门店定位、区域筛选……CityPicker 就是为这件事而生的 Android 城市选择器库——它把全国省市区数据和 iOS 风滚轮、仿京东弹窗、城市列表等常用样式全部封装好了接上依赖就能弹出使用不用自己准备数据源。它适合需要快速落地省市区三级联动功能的 Android 开发者尤其是想少写界面代码、少维护城市数据的同学。下面按「先跑通、再定制」的顺序讲跟着做十来分钟就能看到效果。功能亮点为什么选 CityPicker先说结论这个库的差异化不在只有一个选择器而在于一个依赖里塞了四种交互形态一套数据四种 UI仿 iOS 滚轮、仿京东样式、单级城市列表、省市区三级列表业务要哪种挑哪种切换成本几乎为零。数据自带全国县以上行政区划数据内置在citypickerview/src/main/assets/china_city_data.json约 190KB省掉抓数据、洗数据的环节。接入极轻滚轮样式不需要在布局里放任何控件纯代码init → setConfig → showCityPicker三步弹出。可定制点多标题、默认定位、滚轮可见条数、循环滚动、港澳台开关、自定义 item 布局全部走 Builder 配置不用动源码。支持自定义数据源公司有自家城市接口的可以直接换成自己的三级数据。集成步骤从加依赖到拿到回调以最常用的 iOS 滚轮样式为例四步走完。第 1 步添加 gradle 依赖在 Project 级别的build.gradle中补上 jitpack 仓库再在 app 的build.gradle里引入库allprojects { repositories { maven { url https://jitpack.io } } }dependencies { implementation com.github.crazyandcoder:citypicker:6.0.2 }同步一下依赖到位。第 2 步初始化滚轮选择器不用改布局CityPickerView是弹出式控件不需要写进 XMLCityPickerView cityPickerView new CityPickerView(); cityPickerView.init(this); // 建议在 onCreate 里尽早调用第 3 步配置样式并弹出配置项全部通过 Builder 链式给出这里给一个最小可用配置CityConfig cityConfig new CityConfig.Builder() .title(选择城市) .province(江苏) .city(常州) .district(新北区) .setCityWheelType(CityConfig.WheelType.PRO_CITY_DIS) // 三级联动 .build(); cityPickerView.setConfig(cityConfig); cityPickerView.showCityPicker();其中setCityWheelType决定滚轮级数PRO只显示省份PRO_CITY省市两级PRO_CITY_DIS完整三级。第 4 步写选择回调cityPickerView.setOnCityItemClickListener(new OnCityItemClickListener() { Override public void onSelected(ProvinceBean province, CityBean city, DistrictBean district) { // 级数不够时对应参数为 null先判空再拼地址 StringBuilder sb new StringBuilder(); if (province ! null) sb.append(province.getName()).append( ).append(province.getId()); if (city ! null) sb.append( ).append(city.getName()).append( ).append(city.getId()); if (district ! null) sb.append( ).append(district.getName()).append( ).append(district.getId()); } Override public void onCancel() { // 用户点击取消 } });到这里滚轮样式已经能跑通。其他三种样式是同一套思路只是入口类不同想换其他 3 种样式仿京东样式用JDCityPickerJDCityConfig同样init → setConfig → showCityPickerShowType支持省市两级和完整三级。单级城市列表启动CityListSelectActivity结果通过onActivityResult回传startActivityForResult(new Intent(this, CityListSelectActivity.class), CityListSelectActivity.CITY_SELECT_RESULT_FRAG); // onActivityResult 中从 extras 取 cityinfoCityInfoBean 类型省市区三级列表从ProvinceActivity进回传码用ProvinceActivity.RESULT_DATAextras 里分别取province、city、area三个字段。这些 Activity 库的 Manifest 已经声明好了直接启动即可无需手动注册。进阶用法与定制默认定位与自定义数据源跑通之后真正体现省市区联动体验的是两个点默认定位和自定义数据。默认定位。province() / city() / district()传的是名称而不是 id弹出时滚轮会直接停在对应位置配合定位 SDK 做上次定位自动回显很顺手。注意名称要和数据源完全一致传错名字会静默落到默认位置。滚轮手感。visibleItemsCount()调可见条数默认 5provinceCyclic() / cityCyclic() / districtCyclic()控制每一列能否循环滚动setShowGAT()开关港澳台数据lineColor() / lineHeigh()调中间选区线——都是 Builder 里一行解决。自定义 item 布局。想让滚轮里加图标、双行文本setCustomItemLayout(布局id)加setCustomItemTextViewId(文本id)两行配置即可样式参考示例里的item_city.xml。换成自己的数据。如果内置的行政区划不符合业务比如只要自营配送城市走CustomCityPickerCustomConfig数据用CustomCityData(id, name)构建父子关系用setList()挂上去再CustomConfig.Builder().setCityData(省份列表)传入。结构上仍是省 → 市 → 区三层和内置数据同构迁移成本很低。源码级定制。以上都满足不了时可以 clone 仓库到本地把citypickerview模块作为本地依赖导入后直接改git clone https://gitcode.com/gh_mirrors/ci/citypicker性能方面不用额外操心数据是随包内置的静态 JSON库在init时完成解析不需要自己维护后台预加载逻辑只要避免在滚动过程中反复重建CityConfig就没问题。常见问题FAQQ1加完依赖同步失败提示找不到 com.github.crazyandcoder:citypicker九成是漏了第 1 步的 jitpack 仓库或者版本号和仓库对不上。确认allprojects.repositories里有maven { url https://jitpack.io }版本号以仓库 README 标注的最新版为准6.0.2 是文中验证过的可用版本然后 Clean 一次再 Sync。Q2为什么onSelected里 city 或 district 是 null不是 bug是级数不够。滚轮只开了两级PRO_CITY时 district 恒为 null只开一级时后两者都是 null。列表样式更要注意它走的是 Intent 结果回传根本不经过OnCityItemClickListener回调别在列表样式里等回调。Q3设置了默认省市区弹出来却停在别的位置检查名称是否与数据源逐字一致。内置数据里省级带省/市/自治区后缀如北京市而示例代码里滚轮默认值写的是江苏这类简称能命中是因为滚轮数据做了对应处理——最稳妥的做法是从实际弹出的列表里确认名字再照着填。Q4release 混淆后闪退怎么办滚轮和 Bean 类有反射/序列化痕迹全量混淆容易翻车。仓库里留了混淆规则参考citypickerview/proguard-rules.pro出问题先按 README 中提到的混淆方案补 keep 规则再重新打包验证。延伸阅读与生态想边看边改最直接的入口是仓库自带的 demo 工程五种用法各占一个 Activity滚轮app/src/main/java/com/ihidea/as/citypicker/activity/CitypickerWheelActivity.java京东风app/src/main/java/com/ihidea/as/citypicker/activity/CitypickerJDActivity.java列表 / 三级列表 / 自定义数据同目录下的CitypickerListActivity、CitypickerThreeListActivity、CityPickerCustomeDataActivity四种样式的核心实现都在citypickerview/src/main/java/com/lljjcoder/style/下按citypickerview/cityjd/citylist/citythreelist分包加citycustome共五个子包读源码时按包名直达。搜索同类实现时可以用「Android 省市区三级联动」「城市选择器集成教程」「iOS 滚轮地址选择」这类关键词能找到不少基于本库或同思路的二次封装做国际化或多级级联比如品牌 → 系列 → 型号时自定义数据源那套CustomCityData结构也完全可以复用。具体的属性全表、混淆细节和历史版本变更记录仓库 README 里都有动手前花两分钟翻一遍能少踩不少坑。【免费下载链接】citypickercitypicker城市选择器详细的省市区地址信息支持仿iOS滚轮实现仿京东样式一级或者三级列表展示方式。项目地址: https://gitcode.com/gh_mirrors/ci/citypicker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考