uni-app 物流时间线组件 etherealwheat-track

uni-app 物流时间线组件 etherealwheat-track 详解

已关注

关注

重播分享赞

视频详情

前言

在电商、物流类小程序中，「物流轨迹」是一个非常常见的需求。用户下单后，需要查看包裹从发货到签收的每一步流转记录。

今天介绍一个轻量级的物流时间线节点组件 —— etherealwheat-track，组件以单个节点为单位，配合 v-for 渲染完整的物流轨迹，灵活且易于集成。

组件特性

节点化设计
：每个组件实例渲染一个时间线节点，通过 v-for 组合成完整轨迹
主节点图标
：支持 isMainNode 模式，根据物流状态自动匹配对应图标（已下单、已支付、已揽收、运输中、已签收）
高亮最新节点
：isNewest 属性让最新物流信息高亮显示
电话号码展示
：nodeData.phone 自动显示快递员联系电话
自定义颜色
：支持通过 props 自定义圆点、连接线、标题、描述文字的颜色
easycom 自动注册
：放入 components/ 目录即可直接使用，无需手动 import

属性速查表

属性	类型	默认值	说明
`isNewest`	Boolean	`false`	是否为最新节点（列表第 0 项），最新节点高亮显示
`isFirst`	Boolean	`false`	是否为第一个节点（列表最后一项），控制上方连接线
`isMainNode`	Boolean	`false`	是否为主节点，主节点展示状态图标
`nodeData`	Object	`{}`	节点数据对象
`activeColor`	String	`#000000`	活跃节点圆点颜色
`inactiveColor`	String	`#dcdcdc`	非活跃节点圆点颜色
`lineColor`	String	`#dcdcdc`	连接线颜色
`titleActiveColor`	String	`#222`	标题活跃颜色
`titleInactiveColor`	String	`#999`	标题非活跃颜色
`descActiveColor`	String	`#4b4b4b`	描述文字活跃颜色
`descInactiveColor`	String	`#999`	描述文字非活跃颜色

nodeData 数据结构

字段	类型	说明
`status`	String	节点描述文本（如"已到达杭州转运中心"）
`statusName`	String	节点标题（仅 `isMainNode` 为 true 时显示）
`time`	String	时间文本
`phone`	String	电话号码（可选，为空则不显示）

支持的状态图标

statusName	对应图标	说明
已下单	ic-order-commit	订单提交图标
已支付 / 待发货	ic-paied	支付完成图标
已揽收 / 已揽件	ic-pacakaging	包裹揽收图标
运输中 / 派送中	ic-sending	运输中图标
已签收 / 已完成	ic-delivering	签收完成图标

实战示例

示例1：基本物流时间线

最简单的用法，isMainNode 设为 false，展示圆点 + 描述 + 时间的基础时间线。

<template> <viewclass=”track-wrap”> <etherealwheat-track v-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-track v-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-track v-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-track v-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-track v-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-track v-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-track v-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-track v-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