简介基于WheelView的自定义日期选择器是一套面向Android开发者的控件实现资源适合需要优化表单录入、日期选择体验的中级开发者。包内包含完整Eclipse工程与APK66个文件涵盖Java源码、class字节码、XML布局、PNG切图等其中13个Java文件实现年月日滚轮逻辑、数据适配与事件联动7个XML文件定义布局和样式APK可直接安装预览效果整体压缩包仅132KB便于快速导入学习。已有1701人学习下载。这套资源不仅演示了WheelView的引入、Adapter数据填充、滚动事件同步等核心机制还提供了样式定制与扩展接口的设计思路可帮助开发者理解Android自定义控件从布局、绘制到交互的完整链路并迁移到时间选择、多语言等更多场景。 最开始想做这个基于 wheelView 的自定义日期选择器完全是被系统的 DatePickerDialog 逼的。那个原生控件的布局在横竖屏切换时候会重排在平板上的拉伸效果惨不忍睹而且想改个文字颜色、加一个“不限时间”的选项都要去翻 framework 层的样式改动成本高到离谱。后来在项目中接到一个“用户需要选择年份范围跨度 60 年、并且要跟服务端下发的放假日期做联动”的需求我决定直接自己动手做一个滚轮式日期选择器核心就是 wheelView。这一篇就把整个设计和实现过程完整复盘一遍从 wheelView 的核心原理到日期数据联动再到我踩过的几个坑一次性说清楚。1. 选定 wheelView 之前先想清楚日期选择器的边界很多人在做自定义日期选择器时第一步就冲进代码里写布局结果做出来的东西要么只能在 Demo 里转要么一接业务就卡壳。其实选型之前最该做的是把需求边界划清楚。我当时的项目场景是这样的一个订单筛选页用户要选“开始日期”和“结束日期”年份范围从当前年份往前推 60 年往后推 10 年同时日期一旦选中下方列表要立刻按这个日期范围重新拉数据另外还需要一个“不限”的快捷选项。整个交互发生在底部弹出的面板里要求单手可操作。把这个需求拆开看核心就三点滚轮滚动要顺滑、年月日三个滚轮要联动、滚动结束之后要能立刻拿到准确的日期并触发回调。wheelView 在这个场景里的优势非常明显。它本质上是一个可以循环滚动、带惯性滑动、并且滚动结束后会吸附回整格的列表控件。用户手指滑动、松开、滚轮自己转几圈然后停下这种交互天然适合日期选择。对比其他方案原生的 DatePickerDialog 在某些定制需求下改造成本高引入第三方时间选择库又太重自己用 RecyclerView 做横向排列列表交互不够直观用户不买账。最后定了三个 wheelView一个管年一个管月一个管日固定显示高度为 5 个 item 的窗口中间高亮线选中项整体嵌在 BottomSheetDialog 里。提示组件选型不是越强大越好是要看它跟你的业务交互模型对不对得上。wheelView 解决的是“滚轮式单选”这件事日期选择器只是它的一个应用场景。2. 核心原理拆解滚轮惯性、吸附与可见区域绘制wheelView 的源码很多版本都有人写过但不管哪个版本核心就三个机制滚动计算、吸附定位、绘制裁剪。搞清楚这三个机制后面做定制才有底气。2.1 滚动计算从手指位移到列表偏移手指按下的时候记录起始坐标滑动过程中计算位移量把位移量累加到一个 totalScrollY 上。手指松开之后根据最后一段时间的滑动速度计算一个衰减系数让 totalScrollY 继续按照递减的速率变化这就模拟出了惯性。这里有一个容易被忽略的细节wheelView 滚动时不可能一次只滚动一个 item它滚动的是一个连续的像素值界面上的表现是 item 在滚轮区域内上下滑动。换句话说数据项本身并不跟着手指走而是通过改变绘制时的偏移量 Y 来绘制每一帧画面。class WheelView(context: Context, attrs: AttributeSet?) : View(context, attrs) { private var totalScrollY 0 private var lastScrollY 0 private var isDragging false override fun onTouchEvent(event: MotionEvent): Boolean { when (event.actionMasked) { MotionEvent.ACTION_DOWN - { isDragging true parent.requestDisallowInterceptTouchEvent(true) lastScrollY event.y.toInt() } MotionEvent.ACTION_MOVE - { val delta lastScrollY - event.y.toInt() totalScrollY delta lastScrollY event.y.toInt() invalidate() } MotionEvent.ACTION_UP - { isDragging false handleSettling() } } return true } }这一段只是最朴素的位移累加。真正做项目时还得考虑一个事手指滑动的方向跟滚轮视觉滚动的方向是否一致。绝大多数 wheelView 的实现里手指上滑代表内容往上走选中项看起来是往下走也就是滚轮内容跟手指方向相反。这个一开始没统一好后面用户会觉得“这个东西很别扭”。2.2 吸附定位停下来的时候必须正好对齐到某一项如果不做吸附滚动停止时 highLine 很可能压在两条 item 之间的缝隙上选中项就变成一个“半截子”的中间值这显然是不可接受的。吸附的实现思路是把 totalScrollY 对 itemHeight 取模算出需要补偿的偏移量然后发动画把补偿量补掉。private fun handleSettling() { val currentItem ((totalScrollY itemHeight / 2) / itemHeight).toInt() val targetY currentItem * itemHeight val smoothDistance targetY - totalScrollY if (smoothDistance ! 0) { val animator ValueAnimator.ofInt(totalScrollY, targetY) animator.duration 180 animator.addUpdateListener { totalScrollY it.animatedValue as Int invalidate() } animator.start() } onWheelSelected?.invoke(currentItem) }吸附动画不宜做太长180 毫秒左右手感正好。太短了像被硬拽回去太长了用户会明显觉得“顿了一下”。如果项之间高度比较大比如 itemHeight 到 48dp 以上动画时间可以适当再加 20 到 30 毫秒不然大跨度滚动时的吸附过程看起来会有点突兀。这里还得提一个跟数据绑定有关的点在吸附回调里要通知外部当前选中项的 index 变化。但注意回调时机必须是“吸附完成”而不是“手指松开”否则用户滑动过程中还没停稳回调就已经被触发了好几次极易造成数据重复刷新。2.3 绘制裁剪只画滚轮窗口里的可见内容wheelView 的绘制区域被限定在控件高度内但数据集合很大比如年份有 70 个不可能全部画出来。常规做法是计算当前偏移量找到在可见区域内的 item 范围只画这一部分。override fun onDraw(canvas: Canvas) { super.onDraw(canvas) val startIndex (totalScrollY / itemHeight).toInt() - 2 val endIndex startIndex ITEM_COUNT_VISIBLE 2 for (i in startIndex..endIndex) { if (i 0 || i itemList.size) continue val y i * itemHeight - totalScrollY itemHeight / 2 drawItem(canvas, itemList[i], y) } }绘制时每个 item 的透明度、字号、颜色要根据它离中心线的距离做渐变越靠近中心线的越实、越大越远越虚、越小。这直接决定了滚轮有没有“立体感”。很多 wheelView 效果看起来很平就是这一步偷懒了所有 item 用一种字号一种透明度画到底。离中心线的距离 | 字号缩放 | 透明度 0正中间 | 1.1倍 | 1.0 1个item距离 | 1.0倍 | 0.7 2个item距离 | 0.85倍 | 0.4 超出3个item | 不绘制 | -3. 从 WheelView 到日期选择器数据适配与年月日联动wheelView 本身只是基础组件真正让它变成日期选择器的是数据适配和联动逻辑。这部分写不好滚轮再顺滑都是白搭。3.1 三个滚轮的数据组织我一般不用“年月日在一个滚轮里”的方案那样列表长度是年数 × 12 × 天数数据量巨大滚动性能也不好。主流做法是三个 wheelView 各管各的布局上横排。年份滚轮的数据是年份数组直接按顺序排。月份滚轮的数据是“1月”到“12月”。日期滚轮数据最特殊因为天数跟月份、闰年都有关系必须等月份变了之后实时算。private fun initYearWheel() { val years mutableListOfString() for (year in currentYear - 60..currentYear 10) { years.add($year年) } yearWheel.setData(years) }这里有一个容易踩的坑数据项类型最好是 String 或者是你自己封装的实体类不要把 Int 裸着传进去。因为实际业务里“2025年”跟“2025”展示完全不一样而且你可能还要在年份后面附加其他状态标记比如“售罄”或者“已截止”只有实体类才能承载这些附加信息。3.2 天数联动关键在 getDaysInMonth 这个函数日期滚轮的数据必须根据“当前选中年份 当前选中月份”动态生成。每次月份滚轮停止滚动就要立刻计算目标月份有多少天然后重新设置日滚轮的数据并且检查当前选中日是否超出了新月份的天数上限超了就自动修正到月末。fun getDaysInMonth(year: Int, month: Int): Int { return when (month) { 1, 3, 5, 7, 8, 10, 12 - 31 4, 6, 9, 11 - 30 2 - if (isLeapYear(year)) 29 else 28 else - 0 } } fun isLeapYear(year: Int): Boolean { return (year % 4 0 year % 100 ! 0) || (year % 400 0) }这里给新手提个醒闰年的判断条件三条缺一不可。year % 4 0 year % 100 ! 0处理普通年份year % 400 0处理世纪年份。比如 2000 年是闰年但 1900 年不是。日期组件如果在这上面出 bug会被测试同学在回归用例里钉死。联动回调放到 wheelView 的选中回调里这一点我在 2.2 节提过。实际项目里我是在月份滚轮的onWheelSelected里调用refreshDayWheel()同时把日滚轮的选中项重置为当前值或者 1。3.3 初始位置与安全范围初始化时不能想当然从第一个 item 开始。比如“开始日期”要求不能早于今天那年份滚轮的默认位置就应该是“当前年份”月份滚轮是“当前月份”日滚轮是“今天的日期”而不是各自滚轮的 index 0。还有一个我在实际需求里碰到的情况用户选完了开始日期结束日期面板打开时结束日期的可选范围被限制成“不能早于开始日期”。这个不能只靠联动你还要在 UI 上给用户反馈——把不可选的区域展示成灰色半透明并且点击确定时做二次校验。别指望用户会自己注意到滚轮里哪一项不能选。4. 使用体验磨细节回弹、防抖、深浅色适配很多开源 wheelView 的 Demo 功能都能跑通但上真机以后总感觉手感差一点。差别集中在细节我把平时总结出的几个关键优化点列出来。4.1 滚动停止之后的任务防抖日期选择器一旦滚完往往要对列表重新发起网络请求。如果用户在年月日三个滚轮之间来回切每次吸附结束都触发一次请求几秒钟内就可能发出七八个请求后端压力大前端也会有数据时序错乱的风险。解决办法是在 wheelView 的回调里做防抖滚动结束后的回调不立刻执行而是 postDelay 300 毫秒如果 300 毫秒内又有新的滚动事件就把上一个任务取消。private val debounceRunnable Runnable { dateSelectListener?.invoke(getSelectedDate()) } fun onWheelScrollEnd() { handler.removeCallbacks(debounceRunnable) handler.postDelayed(debounceRunnable, 300) }注意防抖的时间不能太长超过 500 毫秒用户会明显感觉到“点了确定之后没反应”。300 毫秒是我在多数 Android 设备上试过的折中值。4.2 超出边界时的弹性回弹日期滚轮跟普通无限循环的 wheelView 有一个重要区别它不能循环滚动。年份范围定了 60 年前到 10 年后滚到边界之后必须停住否则用户一下子就滑到空白区域了。实现回弹可以在滚动计算的边界判断里做当 totalScrollY 超出最大值或最小值范围时不直接截断而是把超出的部分乘一个阻力系数视觉上产生“拉橡皮筋”效果松手后动画回弹到边界位置。private fun constrainScrollY() { val minY 0 val maxY (itemList.size - 1) * itemHeight if (totalScrollY minY) { val over minY - totalScrollY totalScrollY minY - (over * 0.25f).toInt() } else if (totalScrollY maxY) { val over totalScrollY - maxY totalScrollY maxY (over * 0.25f).toInt() } }这层逻辑只作用于手指滑动过程中。松手吸附时直接判断当前应该吸附到哪一个合法 index然后把 totalScrollY 动画到合法位置就行。这样一来用户既能看到边界的存在又不会一直被卡死在边界上。4.3 深色模式与主题适配日期选择器如果只在浅色模式下好看接入深色模式就翻车那这个组件就不能算完成。我在项目里把所有颜色值都从资源文件读取通过?attr或者isNightMode判断来动态切换。具体到 wheelView 的绘制上影响到的主要是三个颜色选中项文字颜色、未选中项文字颜色、中间高亮线的颜色。不要写死成黑色或灰色否则切到深色主题之后要么文字看不清要么高亮线像一道白色伤疤。我的做法是在自定义 View 里加一个applyTheme()方法对外暴露setSelectedTextColor和setUnselectedTextColor然后在onDraw里读取当前主题状态计算绘制颜色。4.4 无数据与短列表场景一般做日期选择器默认数据量很大不太会碰到“列表不足一屏”的情况。但我把 wheelView 复用到“选择性别”这种只有两个选项的业务时发现短列表的表现很重要如果只有两个或三个 item滚轮的绘制区域上下应该留出空白让选中的 item 可以居中显示。如果处理不好用户往下滑一格后面没有数据了整个滚轮看起来就会突然空白一大片。常见处理思路是先算出总共的数据高度如果小于控件高度就把控件高度改小或者把 item 绘制区域居中偏移保证视觉上始终有两个可滑动的位置。5. 我在实际集成中踩过的坑以及绕坑建议这一节完全没有按文档顺序写是按我真实项目的踩坑时间线来的如果你也在集成基于 wheelView 的自定义日期选择器大概率会遇到其中几个。5.1 坑一ScrollView 嵌套导致滚轮被父容器抢走事件第一次把 wheelView 放进 BottomSheetDialog 里的时候上下滑动日期滚轮时整个弹窗也跟着上下滚动甚至偶尔出现滚轮没反应、弹窗在滚的情况。查了半天问题出在父容器拦截了子 View 的触摸事件。解决方案是在 wheelView 的ACTION_DOWN里调用parent.requestDisallowInterceptTouchEvent(true)已经在 2.1 节代码里体现。这一步一定要加而且要在ACTION_DOWN里就调用等ACTION_MOVE再调就晚了父容器已经完成了拦截判断。5.2 坑二字体渲染导致的 item 高度计算偏差wheelView 的 itemHeight 决定滚轮绘制密度和吸附精度。一开始我直接用 dp 转 px 定死一个值结果在部分国产 ROM 上数字显示得很拥挤甚至出现上下两个 item 文字重叠。后来改成动态计算初始化时测量一下 item 文本的 Paint 高度再在这个基础上加 padding最终决定 itemHeight。凡是涉及文字尺寸的场景都不要用固定值paint.fontMetrics提供的 top 和 bottom 才是真实的行高。private fun calculateItemHeight(): Int { val fm textPaint.fontMetrics val textHeight (fm.bottom - fm.top).toInt() return textHeight dp2px(context, 16f) }5.3 坑三Locale 变化导致月份显示异常月份滚轮我以前直接monthArray[monthIndex]取中文月份的数组看起来没问题。但后来应用做了多语言适配在英文环境下月份还是显示“一月二月”就很尴尬。这个问题倒不是 wheelView 的锅是数据源没有做本地化。我后来把月份数据改成通过SimpleDateFormat(MMMM, Locale.getDefault())动态生成这样切换系统语言之后月份滚轮会自动跟着变。5.4 坑四极端日期选择偶发错乱上线后收到过一个用户反馈说“选择 2025 年 2 月 30 日”可以选出来。看了一下是日滚轮在月份变化时没有做“日号超限修正”导致用户先选了 1 月 31 日再切到 2 月时日期滚轮显示的最后一个数字还是 31。修复方案我之前在 3.2 节提过月份联动刷新日滚轮数据时要判断当前选中日是否大于新月份的最大天数大于就重置到最大天数。这段逻辑不能只写在初始化里滚轮联动回调里必须有。5.5 坑五性能问题——惯性动画频繁 invalidate 导致掉帧惯性滚动的最后阶段ValueAnimator 每帧都会触发invalidate()。如果 onDraw 里做了太多对象创建比如每一次绘制都new一个 Paint 或者字符串就会在低端机上出现掉帧。我在 onDraw 里做的优化有三个预创建画笔和颜色、避免循环里做字符串拼接、居中绘制文本时统一用一个 RectF 复用对象。实测在骁龙 680 这种低端设备上滚轮滚动帧率也能保持稳定。6. 按这个思路扩展wheelView 还能做哪些事日期选择器只是 wheelView 的一个典型场景。做完这个组件之后我在项目里把 wheelView 复用到好几个地方城市选择器、金额滚轮选择商品价格区间、身高体重滚轮甚至还有一个“常用表情快捷反馈”功能也是用 wheelView 做的。只要你的业务里存在“一维选项列表 需要可视化滚动”的交互都可以先想到它。复用的关键是抽象接口要干净。我的做法是给 wheelView 只留两个必须暴露的能力setData(ListT)和setOnSelectedListener(index - Unit)其他诸如 item 布局、样式等通过自定义 adapter 或者 lambda 传入。这样 wheelView 本身不关心数据长什么样也不关心选中后业务要干什么职责单一接新业务很快。最后分享一个实际项目里很有用的小技巧如果你的日期选择器需要支持“不限时间”这种特殊选项不要硬塞到年份滚轮里建议在月份滚轮上面单独加一个选中状态开关选中“不限”时让三个滚轮整体置灰不可点。这样既不用破坏滚轮的数据结构交互上也一目了然。这个方案看起来简单但比很多产品经理拍脑袋设计的“再往左滑出现不限”要稳得多。本文还有配套的精品资源点击获取