夜雨聆风uni-app 物流时间线组件 etherealwheat-track 详解
已关注
关注
重播 分享 赞
前言
在电商、物流类小程序中，「物流轨迹」是一个非常常见的需求。用户下单后，需要查看包裹从发货到签收的每一步流转记录。
今天介绍一个轻量级的物流时间线节点组件 —— etherealwheat-track，组件以单个节点为单位，配合 v-for 渲染完整的物流轨迹，灵活且易于集成。
组件特性
- 节点化设计
：每个组件实例渲染一个时间线节点，通过 v-for组合成完整轨迹 - 主节点图标
：支持 isMainNode模式，根据物流状态自动匹配对应图标（已下单、已支付、已揽收、运输中、已签收） - 高亮最新节点
： isNewest属性让最新物流信息高亮显示 - 电话号码展示
： nodeData.phone自动显示快递员联系电话 - 自定义颜色
：支持通过 props 自定义圆点、连接线、标题、描述文字的颜色 - easycom 自动注册
：放入 components/目录即可直接使用，无需手动 import
属性速查表
isNewest | false | ||
isFirst | false | ||
isMainNode | false | ||
nodeData | {} | ||
activeColor | #000000 | ||
inactiveColor | #dcdcdc | ||
lineColor | #dcdcdc | ||
titleActiveColor | #222 | ||
titleInactiveColor | #999 | ||
descActiveColor | #4b4b4b | ||
descInactiveColor | #999 |
nodeData 数据结构
status | ||
statusName | isMainNode 为 true 时显示） | |
time | ||
phone |
支持的状态图标
实战示例
示例1：基本物流时间线
最简单的用法，isMainNode 设为 false，展示圆点 + 描述 + 时间的基础时间线。
<template><viewclass=”track-wrap”><etherealwheat-trackv-for=”(item, index) in trackList”:key=”index”:is-newest=”index === 0”:is-first=”index === trackList.length - 1”:is-main-node=”false”:node-data=”item”/></view></template><script>export default {data() {return {trackList: [{ status: '包裹已被签收', time: '2025-06-19 14:30:00', phone: '', statusName: '' },{ status: '快递员正在派件中', time: '2025-06-19 08:15:00', phone: '', statusName: '' },{ status: '已到达【杭州转运中心】', time: '2025-06-18 22:00:00', phone: '', statusName: '' },{ status: '已到达【上海转运中心】', time: '2025-06-18 16:30:00', phone: '', statusName: '' },{ status: '快递员已上门取件', time: '2025-06-18 10:00:00', phone: '', statusName: '' },{ status: '商家已发货', time: '2025-06-18 09:00:00', phone: '', statusName: '' }]}}}</script>
要点：
is-newest="index === 0"—— 列表第 0 项为最新节点，高亮显示 is-first="index === trackList.length - 1"—— 列表最后一项为最顶部节点，不显示上方连接线 phone字段非空时，会在描述文本下方以红色展示电话号码
示例2：主节点与图标
将 isMainNode 设为 true，左侧会展示与物流状态对应的图标，同时显示 statusName 标题。
<template><!-- 全部主节点模式 --><etherealwheat-trackv-for=”(item, index) in mainNodeList”:key=”index”:is-newest=”index === 0”:is-first=”index === mainNodeList.length - 1”:is-main-node=”true”:node-data=”item”/></template><script>export default {data() {return {mainNodeList: [{ status: '包裹已被签收', time: '2025-06-19 14:30', phone: '', statusName: '已签收' },{ status: '由派送员张三配送', time: '2025-06-19 08:15', phone: '13800138000', statusName: '运输中' },{ status: '已到达【杭州转运中心】', time: '2025-06-18 22:00', phone: '', statusName: '运输中' },{ status: '快递员已上门取件', time: '2025-06-18 10:00', phone: '', statusName: '已揽收' },{ status: '订单支付成功', time: '2025-06-18 09:30', phone: '', statusName: '已支付' },{ status: '订单已提交', time: '2025-06-18 09:00', phone: '', statusName: '已下单' }]}}}</script>
也可以混合使用：仅最新节点展示图标，其余节点展示圆点。
<etherealwheat-trackv-for=”(item, index) in mixedList”:key=”index”:is-newest=”index === 0”:is-first=”index === mixedList.length - 1”:is-main-node=”index === 0”:node-data=”item”/>
示例3：完整物流详情页
模拟真实项目中的物流详情页，包含头部商品信息和时间线。
<template><viewclass=”page”><!-- 头部商品信息 --><viewclass=”hd-info”><viewclass=”img-box”><imageclass=”goods-img”:src=”pageData.thumb”mode=”aspectFill” /><viewclass=”img-tip”>共计{{ pageData.num }}件</view></view><viewclass=”info”><viewclass=”status”>物流状态：<text>{{ pageData.statusDesc }}</text></view><viewclass=”company”>快递公司：{{ pageData.expName }}</view><viewclass=”order-num”>快递单号：{{ pageData.expressNo }}<viewclass=”copy” @click=”copyNum”>复制</view></view></view></view><!-- 时间线 --><viewclass=”list-wrap”><etherealwheat-trackv-for=”(item, index) in expressList”:key=”index”:is-newest=”index === 0”:is-first=”index === expressList.length - 1”:is-main-node=”false”:node-data=”item”/></view></view></template>
这是组件在实际项目中最典型的用法，与盲盒项目中 mall-express.vue 和 bag-express.vue 的实现一致。
示例4：订单流程时间线
利用主节点模式展示订单的各个阶段，适合订单详情页。
<template><etherealwheat-trackv-for=”(item, index) in orderList”:key=”index”:is-newest=”index === 0”:is-first=”index === orderList.length - 1”:is-main-node=”true”:node-data=”item”/></template><script>export default {data() {return {// 已完成的完整订单orderList: [{ status: '包裹已签收', time: '2025-06-19 14:30', phone: '', statusName: '已签收' },{ status: '快递员正在配送中', time: '2025-06-19 08:00', phone: '13800138000', statusName: '运输中' },{ status: '快递员已揽收', time: '2025-06-18 10:00', phone: '', statusName: '已揽收' },{ status: '订单已支付', time: '2025-06-18 09:30', phone: '', statusName: '已支付' },{ status: '订单已提交', time: '2025-06-18 09:00', phone: '', statusName: '已下单' }]}}}</script>
效果说明：
最新节点（index === 0）高亮显示彩色图标 其余节点显示灰色图标 每个阶段都有独立的 statusName标题
示例5：自定义样式
通过颜色相关的 props 自定义组件外观，适配不同的 UI 风格。
<!-- 蓝色主题 --><etherealwheat-trackv-for=”(item, index) in trackList”:key=”index”:is-newest=”index === 0”:is-first=”index === trackList.length - 1”:is-main-node=”false”:node-data=”item”active-color=”#409eff”title-active-color=”#409eff”desc-active-color=”#66b1ff”/><!-- 绿色主题 --><etherealwheat-trackv-for=”(item, index) in trackList”:key=”index”:is-newest=”index === 0”:is-first=”index === trackList.length - 1”:is-main-node=”true”:node-data=”item”active-color=”#67c23a”title-active-color=”#67c23a”desc-active-color=”#85ce61”line-color=”#e1f3d8”/><!-- 红色主题（适合异常状态） --><etherealwheat-trackv-for=”(item, index) in trackList”:key=”index”:is-newest=”index === 0”:is-first=”index === trackList.length - 1”:is-main-node=”false”:node-data=”item”active-color=”#f56c6c”title-active-color=”#f56c6c”desc-active-color=”#f89898”line-color=”#fde2e2”/>
可自定义的颜色属性：
active-color—— 活跃节点圆点颜色 inactive-color—— 非活跃节点圆点颜色 line-color—— 连接线颜色 title-active-color—— 标题高亮颜色 title-inactive-color—— 标题灰色颜色 desc-active-color—— 描述文字高亮颜色 desc-inactive-color—— 描述文字灰色颜色
使用要点
1. v-for 中的关键属性绑定
在使用 v-for 遍历物流列表时，有三个属性需要根据索引动态计算：
:is-newest=”index === 0” <!-- 第 0 项为最新 -->:is-first=”index === list.length - 1” <!-- 最后一项为最顶 -->:is-main-node=”false” <!-- 根据需要设置 -->
2. 数据排序
物流数据应按照时间倒序排列（最新的在前面），这样：
index === 0自然对应最新节点 index === length - 1自然对应最早的节点
3. uni-app easycom 自动注册
组件放在 components/etherealwheat-track/ 目录下，uni-app 的 easycom 会自动注册，在页面中直接使用 <etherealwheat-track> 标签即可，无需手动 import。
4. isMainNode 的图标映射
当 isMainNode 为 true 时，组件会根据 nodeData.statusName 自动匹配图标：
已下单 → ic-order-commit.png已支付/待发货 → ic-paied.png已揽收/已揽件 → ic-pacakaging.png运输中/派送中 → ic-sending.png已签收/已完成 → ic-delivering.png
最新的节点（isNewest=true）使用彩色图标，其余使用灰色图标（文件名带 -G 后缀）。
总结
etherealwheat-track 是一个专注于物流时间线展示的轻量组件，核心特点：
以节点为单位， v-for组合，灵活可控支持普通圆点和状态图标两种模式 丰富的颜色自定义 props 内置 5 种物流状态图标 uni-app easycom 即放即用
适用于电商物流详情、订单流程展示、审批时间线等场景。
本文所有示例代码均来自 TestUniapp 项目，完整示例可前往 Gitee 仓库查看：https://gitee.com/hszcxl/TestUniapp/tree/etherealwheat-track
