推荐使用插件市场成熟时间轴组件(如wo-timeline、sunui-timeline),支持Vue2/Vue3、H5及小程序;注意导出方式、主题配置、iOS布局兼容性;手写需规避DOM查询时机与滚动跳转陷阱;动态数据需格式化时间并处理时区与性能。

直接用现成的第三方组件最省事,自己手写容易在小程序里出兼容问题,尤其是 scroll-view 滚动监听、节点定位、ref 获取位置这些环节。
用插件市场组件快速落地(推荐)
插件市场已有多个成熟时间轴组件,比如 wo-timeline(id=22989)、sunui-timeline,都明确标注支持 Vue2/Vue3、H5 和微信小程序。
- 下载后按文档引入,通常只需注册组件 + 传入数组格式的数据,例如
timelineItems,每个对象含axisPoint、title、content字段 - 注意检查组件是否声明了
export default并正确导出,否则 H5 端可能报Unknown custom element - 若需暗黑模式或自定义颜色,优先查组件文档里的
theme或colorprop,别硬改样式类——有些组件用:deep()封装了内部结构,直接覆盖 class 会失效 - 小程序真机调试时,如果时间点错位,大概率是
position: absolute或transform在 iOS 微信里渲染异常,换成margin-left+flex布局更稳
自己写简易时间轴要注意的 DOM 定位陷阱
手写时最容易卡在“如何让当前项自动居中”或“点击某条跳转到对应位置”,核心依赖 uni.createSelectorQuery() 获取节点位置,但这个 API 在不同平台行为不一致。
- 微信小程序中,
boundingClientRect()必须配合exec()异步执行,且不能在onLoad阶段立刻调用——此时 DOM 可能未渲染完成,返回null - H5 端可用
querySelector+getBoundingClientRect(),但要注意scroll-view内部元素的offsetTop不可靠,必须用相对容器的scrollTop计算滚动偏移 - 避免用
scroll-into-view属性直接跳转:它在 App 端支持不全,在某些安卓机型上会失效,建议用scroll-view的scroll-top手动设值 - 时间点圆标(
.point-inner)若用border-radius: 50%,在低端安卓机上可能出现像素级锯齿,换成背景图或 SVG 更稳妥
物流/会议类时间轴要处理动态数据映射
真实业务中时间轴数据往往来自接口(如快递鸟 API),字段命名和时间格式不统一,不能直接丢给组件用。
- 快递鸟返回的
Traces数组里,时间字段是AcceptTime字符串(如"2026-10-29 14:22:05"),需用new Date().toLocaleString()或dayjs格式化为中文可读形式,否则axisPoint显示成 ISO 格式很突兀 - 会议预约类时间轴常需高亮“当前时间段”,得比对
startTime/endTime和系统当前时间,注意时区——new Date()默认本地时区,服务端时间若为 UTC,必须先new Date(dateStr + 'Z')转换 - 大量数据(如 >50 条)直接渲染会导致首屏卡顿,务必加
v-if="index 或用虚拟滚动方案,别指望scroll-view自带优化 - 小程序里禁止使用
document.getElementById,所有节点查询必须走uni.createSelectorQuery(),否则开发工具不报错但真机白屏
真正难的不是画一条线加几个点,而是让时间轴在各种屏幕宽度、不同渲染引擎、滚动中断又恢复的场景下,始终对齐、不跳闪、不卡顿。多数坑都藏在平台差异和异步时机里,别迷信“一套代码多端跑”。











