BizExpressTrack 物流轨迹

物流轨迹卡片：头部快递公司（emoji/单字符图标 + 名称 + 编码）、运单号（等宽字体 + 一键复制，成功变对勾 1.5s）、可选刷新按钮；纵向时间线按 direction 排序（默认 desc 最新在前），最新节点 primary 大圆点带呼吸动画，signed 时转 success 色并挂终态徽标；节点展示时间 / 状态着色 tag / 轨迹描述 / 所在地；show-duration 显示节点间隔耗时。内置 loading 骨架屏、error 失败重试、空态兜底。订单详情、售后进度、发货通知场景。

基础用法

🚚顺丰速运SF

运单号SF1360000123456

2026-10-18 09:12派送中

【苏州市】您的快件正在派送中，快递员：王师傅 138****6688

江苏 苏州

2026-10-18 05:40已到达

快件已到达【苏州工业园转运中心】

江苏 苏州

2026-10-17 21:08运输中

快件已从【上海转运中心】发出，下一站【苏州工业园转运中心】

上海

2026-10-17 14:22运输中

快件已到达【上海转运中心】

上海

2026-10-16 18:35已揽收

【上海市浦东新区】顺丰快递员已揽件

上海 浦东

默认最新轨迹在前；点击复制图标复制运单号，点击节点触发 node-click。

传入公司、运单号与轨迹记录，默认最新在前；点击运单号旁图标复制，点击节点触发 node-click。

<script setup lang="ts">
/** 场景：基础——公司 + 运单号 + desc 时间线 */
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressCompany, BizExpressRecord } from 'vue3-ep-biz-lib'

const company: BizExpressCompany = { name: '顺丰速运', code: 'SF', icon: '🚚' }

const records: BizExpressRecord[] = [
  { time: '2026-10-18 09:12', status: '派送中', context: '【苏州市】您的快件正在派送中，快递员：王师傅 138****6688', location: '江苏 苏州' },
  { time: '2026-10-18 05:40', status: '已到达', context: '快件已到达【苏州工业园转运中心】', location: '江苏 苏州' },
  { time: '2026-10-17 21:08', status: '运输中', context: '快件已从【上海转运中心】发出，下一站【苏州工业园转运中心】', location: '上海' },
  { time: '2026-10-17 14:22', status: '运输中', context: '快件已到达【上海转运中心】', location: '上海' },
  { time: '2026-10-16 18:35', status: '已揽收', context: '【上海市浦东新区】顺丰快递员已揽件', location: '上海 浦东' },
]
</script>

<template>
  <div style="max-width: 460px">
    <BizExpressTrack :company="company" tracking-no="SF1360000123456" :records="records" />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      默认最新轨迹在前；点击复制图标复制运单号，点击节点触发 node-click。
    </p>
  </div>
</template>

显示代码

排序方向

📦中通快递ZTO

运单号ZT7852001133445

2026-10-18 10:05派送中

【杭州市】快件正在派送中，请保持电话畅通

2026-10-18 04:18已到达

快件已到达【杭州滨江网点】

2026-10-17 19:42运输中

快件已从【杭州转运中心】发出

2026-10-17 08:20已揽收

【宁波市鄞州区】中通快递员已揽件

📦中通快递ZTO

运单号ZT7852001133445

2026-10-17 08:20已揽收

【宁波市鄞州区】中通快递员已揽件

2026-10-17 19:42运输中

快件已从【杭州转运中心】发出

2026-10-18 04:18已到达

快件已到达【杭州滨江网点】

2026-10-18 10:05派送中

【杭州市】快件正在派送中，请保持电话畅通

左：direction="desc"（默认，最新在前）；右：direction="asc"（最早在前，从头看物流进展）。

direction 控制展示顺序：desc（默认）最新在前，asc 最早在前，适合从头看物流进展。

<script setup lang="ts">
/** 场景：排序方向——desc 与 asc 对比 */
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressCompany, BizExpressRecord } from 'vue3-ep-biz-lib'

const company: BizExpressCompany = { name: '中通快递', code: 'ZTO', icon: '📦' }

const records: BizExpressRecord[] = [
  { time: '2026-10-18 10:05', status: '派送中', context: '【杭州市】快件正在派送中，请保持电话畅通' },
  { time: '2026-10-18 04:18', status: '已到达', context: '快件已到达【杭州滨江网点】' },
  { time: '2026-10-17 19:42', status: '运输中', context: '快件已从【杭州转运中心】发出' },
  { time: '2026-10-17 08:20', status: '已揽收', context: '【宁波市鄞州区】中通快递员已揽件' },
]
</script>

<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap">
    <BizExpressTrack
      style="flex: 1; min-width: 320px"
      :company="company"
      tracking-no="ZT7852001133445"
      :records="records"
      direction="desc"
    />
    <BizExpressTrack
      style="flex: 1; min-width: 320px"
      :company="company"
      tracking-no="ZT7852001133445"
      :records="records"
      direction="asc"
    />
  </div>
  <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
    左：direction="desc"（默认，最新在前）；右：direction="asc"（最早在前，从头看物流进展）。
  </p>
</template>

显示代码

签收终态

signed：

最新节点 success 色 + 呼吸动画停止 + 终态徽标

🚛京东物流JD

运单号JD002677183945

2026-10-18 14:36已签收 本人签收

【南京市】已由本人签收，感谢使用京东物流，期待再次为您服务

江苏 南京

2026-10-18 09:02派送中

【南京市】京东快递员李强 139****0021 正在为您派送

2026-10-18 02:26运输中

快件已到达【南京雨花台分拣中心】

2026-10-17 16:40已揽收

【上海市青浦区】京东快递员已揽收

signed 置真后最新节点转 success 色并停用呼吸动画，展示 terminal-text 终态徽标（可自定义文案）。

<script setup lang="ts">
/** 场景：签收终态——success 圆点 + 终态徽标 */
import { ref } from 'vue'
import { ElSwitch } from 'element-plus'
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressRecord } from 'vue3-ep-biz-lib'

const signed = ref(true)

const records: BizExpressRecord[] = [
  { time: '2026-10-18 14:36', status: '已签收', context: '【南京市】已由本人签收，感谢使用京东物流，期待再次为您服务', location: '江苏 南京' },
  { time: '2026-10-18 09:02', status: '派送中', context: '【南京市】京东快递员李强 139****0021 正在为您派送' },
  { time: '2026-10-18 02:26', status: '运输中', context: '快件已到达【南京雨花台分拣中心】' },
  { time: '2026-10-17 16:40', status: '已揽收', context: '【上海市青浦区】京东快递员已揽收' },
]
</script>

<template>
  <div style="max-width: 460px">
    <div style="margin-bottom: 10px; display: flex; align-items: center; gap: 8px">
      <span style="font-size: 13px">signed：</span>
      <ElSwitch v-model="signed" />
      <span style="font-size: 12px; color: var(--el-text-color-secondary)">
        {{ signed ? '最新节点 success 色 + 呼吸动画停止 + 终态徽标' : '最新节点 primary 色 + 呼吸动画' }}
      </span>
    </div>
    <BizExpressTrack
      :company="{ name: '京东物流', code: 'JD', icon: '🚛' }"
      tracking-no="JD002677183945"
      :records="records"
      :signed="signed"
      terminal-text="本人签收"
    />
  </div>
</template>

显示代码

加载中

✈️圆通速递YTO

运单号YT7583120946671

当前状态：loading（3 行骨架屏）

status="loading" 渲染 3 行骨架屏；示例模拟查询 1.2s 后填充轨迹。

<script setup lang="ts">
/** 场景：加载中——骨架屏，模拟查询 1.2s 后填充轨迹 */
import { onUnmounted, ref } from 'vue'
import { ElButton } from 'element-plus'
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressRecord } from 'vue3-ep-biz-lib'

const status = ref<'loading' | 'success'>('loading')
const records = ref<BizExpressRecord[]>([])

let timer: ReturnType<typeof setTimeout> | null = null

const mockRecords: BizExpressRecord[] = [
  { time: '2026-10-19 08:15', status: '派送中', context: '【武汉市】您的快件正在派送中，快递员：赵坤 187****3352' },
  { time: '2026-10-18 23:40', status: '运输中', context: '快件已从【武汉转运中心】发出' },
  { time: '2026-10-18 11:26', status: '运输中', context: '快件已到达【武汉转运中心】' },
  { time: '2026-10-17 20:08', status: '已揽收', context: '【长沙市岳麓区】圆通快递员已揽件' },
]

const query = (): void => {
  status.value = 'loading'
  records.value = []
  if (timer !== null) clearTimeout(timer)
  timer = setTimeout(() => {
    records.value = mockRecords
    status.value = 'success'
  }, 1200)
}

query()

onUnmounted(() => {
  if (timer !== null) clearTimeout(timer)
})
</script>

<template>
  <div style="max-width: 460px">
    <ElButton size="small" style="margin-bottom: 10px" @click="query">重新查询</ElButton>
    <BizExpressTrack
      :company="{ name: '圆通速递', code: 'YTO', icon: '✈️' }"
      tracking-no="YT7583120946671"
      :records="records"
      :status="status"
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      当前状态：{{ status === 'loading' ? 'loading（3 行骨架屏）' : 'success（正常渲染）' }}
    </p>
  </div>
</template>

显示代码

查询失败

🚨韵达快递YD

运单号YD4102887530092

物流轨迹查询失败，请稍后重试

refresh 触发次数：0；当前状态：error

status="error" 渲染失败占位块，重试按钮与刷新按钮均触发 refresh 事件，由业务方重新拉取数据。

<script setup lang="ts">
/** 场景：查询失败——失败占位 + 重试回显 */
import { onUnmounted, ref } from 'vue'
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressRecord } from 'vue3-ep-biz-lib'

const status = ref<'error' | 'loading' | 'success'>('error')
const records = ref<BizExpressRecord[]>([])
const retryCount = ref(0)

let timer: ReturnType<typeof setTimeout> | null = null

const mockRecords: BizExpressRecord[] = [
  { time: '2026-10-19 16:48', status: '运输中', context: '【成都市】快件已从【成都双流转运中心】发出' },
  { time: '2026-10-19 06:32', status: '已揽收', context: '【成都市武侯区】韵达快递员已揽件' },
]

/** 失败占位的重试按钮与头部刷新按钮均触发 refresh 事件 */
const onRefresh = (): void => {
  retryCount.value += 1
  status.value = 'loading'
  if (timer !== null) clearTimeout(timer)
  timer = setTimeout(() => {
    records.value = mockRecords
    status.value = 'success'
  }, 1000)
}

onUnmounted(() => {
  if (timer !== null) clearTimeout(timer)
})
</script>

<template>
  <div style="max-width: 460px">
    <BizExpressTrack
      :company="{ name: '韵达快递', code: 'YD', icon: '🚨' }"
      tracking-no="YD4102887530092"
      :records="records"
      :status="status"
      refreshable
      @refresh="onRefresh"
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      refresh 触发次数：{{ retryCount }}；当前状态：{{ status }}
    </p>
  </div>
</template>

显示代码

间隔耗时

🐰极兔速递JT

运单号JT0093184277563

2026-10-19 11:20派送中

【北京市】快件正在派送中

间隔 1小时22分钟

2026-10-19 09:58已到达

快件已到达【北京通州网点】

间隔 11小时53分钟

2026-10-18 22:05运输中

快件已从【北京转运中心】发出

间隔 1天8小时

2026-10-17 13:44已揽收

【天津市滨海新区】极兔快递员已揽件

首末节点总耗时（getTotalDuration）：（无法解析）

show-duration 在 desc 模式下显示与上一节点的耗时（≥1 天「X天X小时」、≥1 小时「X小时X分钟」、≥1 分钟「X分钟」）；getTotalDuration() 返回首末节点总耗时。

<script setup lang="ts">
/** 场景：间隔耗时——节点间隔 + 首末总耗时 */
import { onMounted, ref } from 'vue'
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressRecord, BizExpressTrackInstance } from 'vue3-ep-biz-lib'

const trackRef = ref<BizExpressTrackInstance>()

const total = ref('')

/** 带 ts 的记录：耗时按 ts 计算，缺省解析 time */
const records: BizExpressRecord[] = [
  { time: '2026-10-19 11:20', ts: '2026-10-19T11:20:00', status: '派送中', context: '【北京市】快件正在派送中' },
  { time: '2026-10-19 09:58', ts: '2026-10-19T09:58:00', status: '已到达', context: '快件已到达【北京通州网点】' },
  { time: '2026-10-18 22:05', ts: '2026-10-18T22:05:00', status: '运输中', context: '快件已从【北京转运中心】发出' },
  { time: '2026-10-17 13:44', ts: '2026-10-17T13:44:00', status: '已揽收', context: '【天津市滨海新区】极兔快递员已揽件' },
]

onMounted(() => {
  total.value = trackRef.value?.getTotalDuration() ?? ''
})
</script>

<template>
  <div style="max-width: 460px">
    <BizExpressTrack
      ref="trackRef"
      :company="{ name: '极兔速递', code: 'JT', icon: '🐰' }"
      tracking-no="JT0093184277563"
      :records="records"
      show-duration
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      首末节点总耗时（getTotalDuration）：{{ total === '' ? '（无法解析）' : total }}
    </p>
  </div>
</template>

显示代码

紧凑模式

📮申通快递STO

运单号ST7741920865538

2026-10-19 18:22派送中

【深圳市】快件正在派送中，快递员：陈浩 136****9907

2026-10-19 10:14已到达

快件已到达【深圳南山网点】

2026-10-18 21:36运输中

快件已从【广州转运中心】发出

2026-10-18 09:02已揽收

【广州市天河区】申通快递员已揽件

compact 收紧留白且不渲染所在地行，适合侧栏 / 抽屉等窄容器。

compact 收紧留白并隐藏所在地行，适合侧栏、抽屉等窄容器。

<script setup lang="ts">
/** 场景：紧凑模式——窄容器隐藏所在地 */
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressRecord } from 'vue3-ep-biz-lib'

const records: BizExpressRecord[] = [
  { time: '2026-10-19 18:22', status: '派送中', context: '【深圳市】快件正在派送中，快递员：陈浩 136****9907', location: '广东 深圳' },
  { time: '2026-10-19 10:14', status: '已到达', context: '快件已到达【深圳南山网点】', location: '广东 深圳' },
  { time: '2026-10-18 21:36', status: '运输中', context: '快件已从【广州转运中心】发出', location: '广东 广州' },
  { time: '2026-10-18 09:02', status: '已揽收', context: '【广州市天河区】申通快递员已揽件', location: '广东 广州' },
]
</script>

<template>
  <div style="max-width: 340px">
    <BizExpressTrack
      :company="{ name: '申通快递', code: 'STO', icon: '📮' }"
      tracking-no="ST7741920865538"
      :records="records"
      compact
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      compact 收紧留白且不渲染所在地行，适合侧栏 / 抽屉等窄容器。
    </p>
  </div>
</template>

显示代码

自定义节点

德邦快递 · 大件快递自定义头部

DB9055217743086（点击刷新）

2026-10-19 20:12【西安市】快件正在派送中，快递员：刘洋 159****4432最新

2026-10-19 07:45快件已到达【西安未央分拨中心】

2026-10-18 15:30【郑州市金水区】德邦快递员已揽件

#header 作用域：company / trackingNo / refresh；#node 作用域：record / index / first。

#node 插槽接管节点内容（作用域 record / index / first），#header 可同时接管头部。

<script setup lang="ts">
/** 场景：自定义节点——#header + #node 插槽接管渲染 */
import { ElIcon, ElTag } from 'element-plus'
import { Box, Van } from '@element-plus/icons-vue'
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressRecord } from 'vue3-ep-biz-lib'

const records: BizExpressRecord[] = [
  { time: '2026-10-19 20:12', status: '派送中', context: '【西安市】快件正在派送中，快递员：刘洋 159****4432' },
  { time: '2026-10-19 07:45', status: '运输中', context: '快件已到达【西安未央分拨中心】' },
  { time: '2026-10-18 15:30', status: '已揽收', context: '【郑州市金水区】德邦快递员已揽件' },
]
</script>

<template>
  <div style="max-width: 460px">
    <BizExpressTrack tracking-no="DB9055217743086" :records="records" refreshable>
      <template #header="{ trackingNo, refresh }">
        <div style="display: flex; align-items: center; gap: 8px">
          <ElIcon style="color: var(--el-color-primary)"><Van /></ElIcon>
          <span style="font-weight: 600">德邦快递 · 大件快递</span>
          <ElTag size="small" type="info" effect="plain">自定义头部</ElTag>
        </div>
        <a
          href="javascript:;"
          style="font-size: 12px; color: var(--el-color-primary)"
          @click="refresh"
        >
          {{ trackingNo }}（点击刷新）
        </a>
      </template>

      <template #node="{ record, first }">
        <div :style="{ display: 'flex', alignItems: 'center', gap: '8px', fontWeight: first ? 600 : 400 }">
          <ElIcon :size="14" style="color: var(--el-color-primary)"><Box /></ElIcon>
          <span style="font-family: ui-monospace, Consolas, monospace; font-size: 12px; color: var(--el-text-color-secondary)">
            {{ record.time }}
          </span>
          <span style="flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap">
            {{ record.context }}
          </span>
          <ElTag v-if="first" size="small" type="primary" effect="light">最新</ElTag>
        </div>
      </template>
    </BizExpressTrack>
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      #header 作用域：company / trackingNo / refresh；#node 作用域：record / index / first。
    </p>
  </div>
</template>

显示代码

事件

📮中国邮政EMS

运单号EMS9987123044567

2026-10-19 21:03运输中

【重庆市】快件已从【重庆转运中心】发出

2026-10-19 08:50已揽收

【成都市锦江区】邮政快递员已揽件

事件回显（最近 6 条）：

• （暂无，点击复制 / 刷新 / 节点试试）

copy / refresh / node-click 事件回显；refresh 模拟重新拉取轨迹。

<script setup lang="ts">
/** 场景：事件——copy / refresh / node-click 回显 */
import { onUnmounted, ref } from 'vue'
import { BizExpressTrack } from 'vue3-ep-biz-lib'
import type { BizExpressRecord } from 'vue3-ep-biz-lib'

interface LogItem {
  id: number
  text: string
}

const logs = ref<LogItem[]>([])
const loading = ref(false)
let logId = 0
let timer: ReturnType<typeof setTimeout> | null = null

const pushLog = (text: string): void => {
  logId += 1
  logs.value = [{ id: logId, text: `#${logId} ${text}` }, ...logs.value].slice(0, 6)
}

const records = ref<BizExpressRecord[]>([
  { time: '2026-10-19 21:03', status: '运输中', context: '【重庆市】快件已从【重庆转运中心】发出' },
  { time: '2026-10-19 08:50', status: '已揽收', context: '【成都市锦江区】邮政快递员已揽件' },
])

const onCopy = (trackingNo: string): void => {
  pushLog(`copy：已复制运单号 ${trackingNo}`)
}

const onRefresh = (): void => {
  pushLog('refresh：触发轨迹刷新')
  loading.value = true
  if (timer !== null) clearTimeout(timer)
  timer = setTimeout(() => {
    loading.value = false
    pushLog('refresh：数据已更新（模拟）')
  }, 1000)
}

const onNodeClick = (record: BizExpressRecord): void => {
  pushLog(`node-click：${record.time} ${record.context.slice(0, 12)}…`)
}

onUnmounted(() => {
  if (timer !== null) clearTimeout(timer)
})
</script>

<template>
  <div style="max-width: 460px">
    <BizExpressTrack
      :company="{ name: '中国邮政', code: 'EMS', icon: '📮' }"
      tracking-no="EMS9987123044567"
      :records="records"
      :status="loading ? 'loading' : 'success'"
      refreshable
      @copy="onCopy"
      @refresh="onRefresh"
      @node-click="onNodeClick"
    />
    <div style="margin-top: 10px; font-size: 12px; color: var(--el-text-color-secondary)">
      事件回显（最近 6 条）：
      <ul style="margin: 6px 0 0; padding-left: 18px; line-height: 1.9">
        <li v-for="log in logs" :key="log.id">{{ log.text }}</li>
        <li v-if="logs.length === 0">（暂无，点击复制 / 刷新 / 节点试试）</li>
      </ul>
    </div>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
company	BizExpressCompany	—	快递公司（name 必填，code / icon 可选）
tracking-no	string	''	运单号（等宽字体展示 + 复制）
records	BizExpressRecord[]	[]	轨迹记录（内部按 direction 排序）
direction	'desc' | 'asc'	'desc'	展示顺序：desc 最新在前
status	'success' | 'loading' | 'error' | 'empty'	'success'	整体状态（骨架屏 / 失败占位）
compact	boolean	false	紧凑模式：隐藏所在地、收紧留白
show-header	boolean	true	显示头部
show-duration	boolean	false	desc 模式下显示节点间隔耗时
signed	boolean	false	已签收：最新节点 success 色 + 终态徽标
terminal-text	string	'已签收'	签收终态徽标文案
refreshable	boolean	false	显示刷新按钮

Events

事件名	参数	说明
copy	(trackingNo: string)	运单号复制成功
refresh	—	刷新 / 失败重试
node-click	(record: BizExpressRecord)	节点点击

Slots

插槽名	说明
header	自定义头部（作用域：company / trackingNo / refresh）
node	自定义节点内容（作用域：record / index / first）
empty	自定义空态
footer	底部补充区

Expose

名称	类型	说明
getRecords	() => BizExpressRecord[]	排序后的展示记录副本
getTotalDuration	() => string	首末节点总耗时文本；无法解析返回 ''