Android 时间选择器终极定制指南一步步用 PickerView 打造顺手的日期时间控件【免费下载链接】Android-PickerViewThis is a picker view for android , support linkage effect, timepicker and optionspicker.时间选择器、省市区三级联动项目地址: https://gitcode.com/gh_mirrors/an/Android-PickerView做 Android 开发几乎每个 App 都躲不开时间选择器预约、下单、打卡、日历排期……系统自带的 DatePicker 样式呆板、格式固定很难融入产品自己的设计风格。而 Android-PickerView 就是一款仿 iOS 滚轮效果的开源选择器库内置时间选择器与选项选择器支持农历、三级联动、自定义布局、深色主题等能力在国产开源库中一直拥有很高的口碑。本篇文章会从一个真实业务需求出发带你一步步把它调教成入职即用的时间选择组件。一、从一个差一点就够用的需求说起假设你正在做一款预约类 App用户需要选择哪天几点来时间格式希望是「年月日 时分」秒根本用不上只能选未来 30 天不能选过去界面要跟 App 的主色调一致最好还有夜间模式老板还想在部分页面加上农历显示。如果用系统自带控件这几个需求几乎每个都要自己写自定义 View工作量不小。而 Android-PickerView 的TimePickerBuilder几乎把上述能力都做成了链式配置改一行代码就能看到变化。这就是我们接下来要讲的核心。二、Android-PickerView 核心能力速览先花 30 秒搞清楚这个库能做什么后面用起来才有方向感能力说明对应配置时间选择年月日时分秒六列自由组合显隐setType(boolean[6])选项选择一、二、三级选项可联动可不联动setPicker()/setNPicker()范围限制限制可选起始/终止日期setRangDate(start, end)默认值设置默认选中时间setDate(Calendar)农历干支纪年、闰月、农历日期setLunarCalendar(true)自定义布局完全替换顶部栏与外观setLayoutRes()CustomListener深色模式标题栏、滚轮、按钮全量换色setBgColor()/setTitleBgColor()Dialog 模式以底部弹窗形式展示isDialog(true) 该库分为pickerview选择器封装与wheelview滚轮基础控件两层日常开发直接用前者即可想深度改造再去动后者。三、快速可用让时间选择器 3 步跑起来第 1 步引入依赖。在模块的build.gradle中加入dependencies { implementation com.contrarywind:Android-PickerView:4.1.9 }如果想研究源码或直接引入 module 二次改造也可以把仓库 clone 下来git clone https://gitcode.com/gh_mirrors/an/Android-PickerView第 2 步用最短代码构建选择器。TimePickerBuilder构造器要求传入 Context 和选中回调其余全部可省略// 最小可用版构建一个完整的时间选择器 TimePickerView timePicker new TimePickerBuilder(this, new OnTimeSelectListener() { Override public void onTimeSelect(Date date, View v) { // date 就是用户最终选中的时间 Log.d(Picker, new SimpleDateFormat(yyyy-MM-dd HH:mm, Locale.CHINA).format(date)); } }).build();第 3 步在按钮点击时弹出它btnPick.setOnClickListener(v - timePicker.show(v));✅ 完成。三步下来一个仿 iOS 的六列滚轮时间选择器就能用了默认精确到秒。但先别急着上线——接下来才是让它好用的关键。四、精细配置把时间选择器调成产品想要的样子4.1 只显示需要的单位setTypesetType接收一个长度为6的布尔数组依次对应「年、月、日、时、分、秒」true显示、false隐藏// 场景 A只选年月日适合生日、入住日期 new TimePickerBuilder(this, listener) .setType(new boolean[]{true, true, true, false, false, false}) .build(); // 场景 B只选时分适合营业时间、闹钟提醒 new TimePickerBuilder(this, listener) .setType(new boolean[]{false, false, false, true, true, false}) .build();⚠️ 数组长度不是 6 会直接抛IllegalArgumentException写配置时记得数清楚。4.2 改标签文字setLabel 与 isCenterLabel默认每列会显示年/月/日/时/分/秒标签。想要英文缩写、去掉标签或者让标签只出现在选中行都可以new TimePickerBuilder(this, listener) .setLabel(Y, M, D, h, m, s) // 自定义单位标签 .isCenterLabel(false) // true仅选中项带标签false每项都带 .build();4.3 限定可选范围setRangDate 与月份从 0 开始的坑setRangDate接收两个Calendar对象。这里有一个新手必踩的坑Calendar 的月份是 0~11所以1 月要写012 月要写11。Calendar selected Calendar.getInstance(); // 默认选中今天 Calendar start Calendar.getInstance(); start.set(2024, Calendar.JANUARY, 1); // 起始2024-01-01 Calendar end Calendar.getInstance(); end.set(2026, Calendar.DECEMBER, 31); // 结束2026-12-31 new TimePickerBuilder(this, listener) .setType(new boolean[]{true, true, true, false, false, false}) .setDate(selected) // 默认选中值 .setRangDate(start, end) // 限定可选范围 .build();设置范围后滚轮在边界年份会自动收缩可选的月、日例如只能选到 12 月 31 日不会出现越界的假选项。 如果不设置范围默认允许 1900~2100 年起始时间不能晚于结束时间否则会抛异常提示你检查参数。4.4 样式微调把配色和字号统一到你的设计稿下面这组配置基本覆盖了日常美化需求颜色建议直接使用你 App 的主题色值new TimePickerBuilder(this, listener) .setContentTextSize(18) // 滚轮文字大小 .setDividerColor(0xFF24AD9D) // 分割线颜色 .setTextColorCenter(0xFF24AD9D) // 选中项文字颜色 .setTextColorOut(0xFF999999) // 非选中项文字颜色 .setLineSpacingMultiplier(1.6f) // 行间距倍数取值 1.0~4.0 .setItemVisibleCount(5) // 可见条目数传偶数会自动 1 .isAlphaGradient(true) // 上下边缘透明度渐变 .build();其中setItemVisibleCount(5)能让滚轮显示 5 行默认 3 行视觉上更接近 iOS 的 PickerViewisAlphaGradient(true)会让远离中心的行逐渐变淡层次感立刻出来。五、进阶玩法自定义布局、农历与夜间模式5.1 用自定义布局换一套脸setLayoutRes允许你完全替换选择器的顶部栏和交互控件。官方 Demo 里的pickerview_custom_time.xml就是一个典型用一张向下箭头图片代替取消按钮右侧放一个完成文字按钮整体更轻量。使用方式分两步先写布局 XML再在customLayout回调里绑定控件事件new TimePickerBuilder(this, new OnTimeSelectListener() { Override public void onTimeSelect(Date date, View v) { tvResult.setText(formatDate(date)); } }) .setLayoutRes(R.layout.pickerview_custom_time, new CustomListener() { Override public void customLayout(View v) { TextView tvFinish v.findViewById(R.id.tv_finish); ImageView ivCancel v.findViewById(R.id.iv_cancel); tvFinish.setOnClickListener(v1 - { pvCustom.returnData(); // 触发 onTimeSelect 回调 pvCustom.dismiss(); // 关闭选择器 }); ivCancel.setOnClickListener(v1 - pvCustom.dismiss()); } }) .setType(new boolean[]{false, false, false, true, true, true}) // 只要时分秒 .setTextXOffset(0, 0, 0, 40, 0, -40) // 逐列微调文字横向位置 .setDividerColor(0xFF24AD9D) .build();⚠️ 关键提醒自定义布局里必须保留 id 为timepicker或optionspicker的容器及其六个子 WheelViewyear/month/day/hour/min/second否则初始化会因找不到控件而空指针。建议在 Demo 布局基础上改不要从零写。5.2 一键开启农历需要做日历类、节气类产品setLunarCalendar(true)会把滚轮内容切换为干支纪年、农历月份与日期如丁酉年 九月廿七并且自带闰月逻辑new TimePickerBuilder(this, new OnTimeSelectListener() { Override public void onTimeSelect(Date date, View v) { // 回调返回的依然是公历 Date方便继续存库 Toast.makeText(this, formatDate(date), Toast.LENGTH_SHORT).show(); } }) .setLunarCalendar(true) // 开启农历模式 .setType(new boolean[]{true, true, true, false, false, false}) .build(); 农历支持范围是 1900~2100 年项目内utils/ChinaDate.java和utils/LunarCalendar.java就是干这个活的想扩展范围可以在这里改。5.3 深色主题一行组配色把标题栏、滚轮背景换成深色再配白色文字夜间模式就完成了new TimePickerBuilder(this, listener) .setTitleBgColor(0xFF333333) // 标题栏背景 .setBgColor(0xFF111111) // 滚轮背景 .setTitleColor(Color.WHITE) // 标题文字 .setSubmitColor(Color.WHITE) // 确定按钮 .setCancelColor(Color.WHITE) // 取消按钮 .setTextColorCenter(Color.WHITE) .build();另外isDialog(true)可以把选择器变成底部弹窗配合Dialog还能调整动画与遮罩透明度很多 App 的从底部滑出效果就是这么来的。六、不止时间顺带搞定省市区三级联动OptionsPickerView与时间选择器同源同构适合地址、分类等选项选择。先准备数据再setPicker绑定OptionsPickerView pvOptions new OptionsPickerBuilder(this, new OnOptionsSelectListener() { Override public void onOptionsSelect(int options1, int options2, int options3, View v) { // 三个参数分别是各级选中下标 String tx provinces.get(options1).getPickerViewText() cities.get(options1).get(options2); tvAddress.setText(tx); } }) .setTitleText(选择城市) .build(); pvOptions.setPicker(provinces, cities); // 二级联动 pvOptions.show();如果数据是自建 Bean只需实现IPickerViewData接口并重写getPickerViewText()选择器就会自动取该方法返回值来显示文字。官方 Demo 里的JsonDataActivity展示了如何解析province.json组装省市区数据是标准的接入范本七、高频问题与避坑清单问题原因与解法选择器起止年份不对Calendar月份从 0 开始1 月请写 0、12 月请写 11自定义布局后崩溃空指针缺少 id 为timepicker/optionspicker的容器或子 WheelViewsetType传数组报错数组长度必须为 6按「年月日时分秒」顺序排列设置范围后崩溃起始时间晚于结束时间会抛IllegalArgumentException年份范围异常时间选择器默认支持 1900~2100 年边界外的日期需自行扩展源码弹出后样式与 App 不符使用setOutSideColor控制外部遮罩颜色setDividerType可换分割线样式八、体验与性能优化建议数据就绪后再弹出省市区这类数据若来自网络或本地 JSON务必等数据加载完再show()否则容易崩溃——Demo 里就特意在注释中强调了这一点。复用实例而非重复构建把TimePickerView保存为成员变量多次弹出只show()避免反复构建带来的卡顿。注意回调时机onTimeSelect是点确定后触发如果需要滚动过程中实时预览用setTimeSelectChangeListener时间或setOptionsSelectChangeListener选项监听选中变化。文字过长自适应滚轮自带文字缩放逻辑超长 item 会自动缩小字号不用担心广东佛山顺德这类长文本溢出。九、下一步行动清单读完这篇文章建议按下面的顺序动手实践一遍用TimePickerBuilder跑通最小可用的时间选择器用setTypesetLabelsetRangDate完成预约时间场景用setLayoutRes替换顶部栏统一到产品设计稿尝试setLunarCalendar(true)与深色主题各来一版对照app/src/main/java/com/bigkoo/pickerviewdemo/MainActivity.java里的六个示例选择器逐一看懂每种配置的用途阅读pickerview/src/main/java/com/bigkoo/pickerview/view/WheelTime.java理解范围联动与农历的实现思路。想深入探索的话Demo 源码、两个自定义布局 XMLapp/src/main/res/layout/目录以及wheelview底层滚轮控件都是很好的进阶教材。把上面的清单走完你手里的时间选择器就不再是拿来即用的黑盒而是可以随时为业务改造成型的得力组件。如果在实践过程中遇到问题欢迎在仓库评论区或社区交流群里分享你的踩坑经历——好用的开源库需要大家一起来打磨。【免费下载链接】Android-PickerViewThis is a picker view for android , support linkage effect, timepicker and optionspicker.时间选择器、省市区三级联动项目地址: https://gitcode.com/gh_mirrors/an/Android-PickerView创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考