Timeline 时间线
按时间顺序从上到下列出一串记录,例如操作日志、物流进度、项目里程碑。每条记录用一个 NsTimelineItem。
引入
ts
import { NsTimeline, NsTimelineItem } from '@ns/ui'
基础用法
NsTimelineItem 的默认插槽是内容,timestamp 是时间文字,显示在内容下面。
vue
<script setup lang="ts">
import { NsTimeline, NsTimelineItem } from '@ns/ui'
</script>
<template>
<NsTimeline>
<NsTimelineItem timestamp="2026-01-05">项目立项</NsTimelineItem>
<NsTimelineItem timestamp="2026-02-10">完成设计稿</NsTimelineItem>
<NsTimelineItem timestamp="2026-04-20">开发完成</NsTimelineItem>
<NsTimelineItem timestamp="2026-05-08">正式上线</NsTimelineItem>
</NsTimeline>
</template>
反向排列
reverse 为 true 时,最后一项显示在最上面。只是显示顺序反过来,不用改数据的顺序。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch, NsTimeline, NsTimelineItem } from '@ns/ui'
const reverse = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSwitch v-model="reverse" active-text="最新的在上面(reverse)" />
<NsTimeline :reverse="reverse">
<NsTimelineItem timestamp="2026-01-05">项目立项</NsTimelineItem>
<NsTimelineItem timestamp="2026-02-10">完成设计稿</NsTimelineItem>
<NsTimelineItem timestamp="2026-04-20">开发完成</NsTimelineItem>
</NsTimeline>
</NsSpace>
</template>
节点类型
type 决定节点的颜色,可选 primary(默认)、success、warning、danger、info。
vue
<template>
<NsTimeline>
<NsTimelineItem type="primary" timestamp="type=primary">进行中</NsTimelineItem>
<NsTimelineItem type="success" timestamp="type=success">已完成</NsTimelineItem>
<NsTimelineItem type="warning" timestamp="type=warning">有风险</NsTimelineItem>
<NsTimelineItem type="danger" timestamp="type=danger">失败</NsTimelineItem>
<NsTimelineItem type="info" timestamp="type=info">未开始</NsTimelineItem>
</NsTimeline>
</template>
节点大小和空心
size 可选 normal(默认,12px)和 large(16px)。hollow 把节点画成空心的圆圈,边框颜色跟着 type。两个可以一起用,也能和任意 type 搭配。
左边是大小和空心的四种组合,右边是每种类型的大号空心节点:
vue
<template>
<NsSpace wrap align="start" :size="48">
<NsTimeline>
<NsTimelineItem timestamp="size=normal">普通节点</NsTimelineItem>
<NsTimelineItem size="large" timestamp="size=large">大号节点</NsTimelineItem>
<NsTimelineItem hollow timestamp="hollow">空心节点</NsTimelineItem>
<NsTimelineItem hollow size="large" timestamp="hollow + size=large">
大号空心节点
</NsTimelineItem>
</NsTimeline>
<NsTimeline>
<NsTimelineItem hollow size="large" type="primary">primary</NsTimelineItem>
<NsTimelineItem hollow size="large" type="success">success</NsTimelineItem>
<NsTimelineItem hollow size="large" type="warning">warning</NsTimelineItem>
<NsTimelineItem hollow size="large" type="danger">danger</NsTimelineItem>
<NsTimelineItem hollow size="large" type="info">info</NsTimelineItem>
</NsTimeline>
</NsSpace>
</template>
自定义颜色
color 传任意 CSS 颜色值,优先于 type。实心节点用它做底色,空心节点用它做边框色。
vue
<template>
<NsTimeline>
<NsTimelineItem color="#52c41a" timestamp="2026-01-05">实心节点</NsTimelineItem>
<NsTimelineItem color="#f5222d" hollow timestamp="2026-01-06">空心节点</NsTimelineItem>
<NsTimelineItem color="#722ed1" size="large" timestamp="2026-01-07">大号节点</NsTimelineItem>
<NsTimelineItem color="var(--ns-color-warning)" timestamp="2026-01-08">
也可以用主题变量
</NsTimelineItem>
</NsTimeline>
</template>
自定义节点
dot 插槽用来把圆点换成图标或其他内容。这时不再画圆点,插槽内容以连线为中心摆放,颜色跟随 type,也可以用 color 指定。
vue
<script setup lang="ts">
import { NsTimeline, NsTimelineItem, NsIcon } from '@ns/ui'
</script>
<template>
<NsTimeline>
<NsTimelineItem timestamp="2026-03-01 09:12">
<template #dot><NsIcon name="user" size="md" /></template>
张伟提交了发布申请
</NsTimelineItem>
<NsTimelineItem timestamp="2026-03-01 10:30" type="success">
<template #dot><NsIcon name="success" size="md" /></template>
审核通过
</NsTimelineItem>
<NsTimelineItem timestamp="2026-03-01 11:05" type="danger">
<template #dot><NsIcon name="error" size="md" /></template>
发布失败
</NsTimelineItem>
<NsTimelineItem timestamp="2026-03-01 11:20" color="#722ed1">
<template #dot><NsIcon name="clock" size="md" /></template>
等待重试
</NsTimelineItem>
</NsTimeline>
</template>
时间戳位置
placement 控制时间戳在内容的上面还是下面:bottom(默认,下面)、top(上面)。时间比内容更重要时(例如操作日志)放在上面。
vue
<template>
<NsSpace wrap align="start" :size="48">
<div>
<p class="demo-label">placement="bottom"</p>
<NsTimeline>
<NsTimelineItem timestamp="2026-01-05">项目立项</NsTimelineItem>
<NsTimelineItem timestamp="2026-02-10">完成设计稿</NsTimelineItem>
<NsTimelineItem timestamp="2026-04-20">开发完成</NsTimelineItem>
</NsTimeline>
</div>
<div>
<p class="demo-label">placement="top"</p>
<NsTimeline>
<NsTimelineItem timestamp="2026-01-05" placement="top">项目立项</NsTimelineItem>
<NsTimelineItem timestamp="2026-02-10" placement="top">完成设计稿</NsTimelineItem>
<NsTimelineItem timestamp="2026-04-20" placement="top">开发完成</NsTimelineItem>
</NsTimeline>
</div>
</NsSpace>
</template>
<style scoped>
.demo-label {
margin: 0 0 12px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
不显示时间戳
没传 timestamp 时不显示时间戳。传了但暂时不想显示时用 hide-timestamp。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch, NsTimeline, NsTimelineItem } from '@ns/ui'
const hide = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSwitch v-model="hide" active-text="第一项隐藏时间戳(hide-timestamp)" />
<NsTimeline>
<NsTimelineItem timestamp="2026-01-05" :hide-timestamp="hide">项目立项</NsTimelineItem>
<NsTimelineItem>没有传 timestamp</NsTimelineItem>
<NsTimelineItem timestamp="2026-04-20">正常显示时间戳</NsTimelineItem>
</NsTimeline>
</NsSpace>
</template>
丰富内容
内容区可以放任意元素和组件。内容多高,连线就跟着拉多长。
vue
<script setup lang="ts">
import { NsButton, NsTag, NsTimeline, NsTimelineItem } from '@ns/ui'
</script>
<template>
<NsTimeline>
<NsTimelineItem timestamp="2026-05-08 10:30" placement="top" type="success">
<h4 style="margin: 0 0 4px">已签收</h4>
<p style="margin: 0; color: var(--ns-text-color-secondary)">您的快件已由本人签收,感谢使用</p>
</NsTimelineItem>
<NsTimelineItem timestamp="2026-05-08 08:15" placement="top">
<h4 style="margin: 0 0 4px">
派送中
<NsTag size="small" type="warning">今日送达</NsTag>
</h4>
<p style="margin: 0 0 8px; color: var(--ns-text-color-secondary)">
快递员王师傅正在派送,电话 138 0000 1234
</p>
<NsButton size="small" icon="phone">联系快递员</NsButton>
</NsTimelineItem>
<NsTimelineItem timestamp="2026-05-07 21:40" placement="top" type="info">
<h4 style="margin: 0 0 4px">运输中</h4>
<p style="margin: 0; color: var(--ns-text-color-secondary)">已到达杭州转运中心</p>
</NsTimelineItem>
</NsTimeline>
</template>
按数据生成
记录一般来自数组,用 v-for 生成。下面点“新增一条”往数组末尾加记录,打开开关后最新的记录显示在最上面。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsSwitch, NsTimeline, NsTimelineItem } from '@ns/ui'
import type { TimelineItemType } from '@ns/ui'
interface ApprovalRecord {
id: number
time: string
text: string
type: TimelineItemType
}
const records = ref<ApprovalRecord[]>([
{ id: 1, time: '2026-01-01 09:00', text: '提交报销申请', type: 'primary' },
{ id: 2, time: '2026-01-01 10:30', text: '主管审批通过', type: 'success' },
{ id: 3, time: '2026-01-02 14:00', text: '财务打款', type: 'success' }
])
const reverse = ref(false)
const steps = ['补充发票', '财务复核', '归档']
const add = () => {
const id = records.value.length + 1
const now = new Date()
const pad = (n: number) => String(n).padStart(2, '0')
records.value.push({
id,
time: `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`,
text: steps[(id - 4) % steps.length] ?? '其他操作',
type: 'info'
})
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsButton type="primary" icon="plus" @click="add">新增一条</NsButton>
<NsSwitch v-model="reverse" active-text="最新的在上面" />
</NsSpace>
<NsTimeline :reverse="reverse">
<NsTimelineItem
v-for="record in records"
:key="record.id"
:timestamp="record.time"
:type="record.type"
>
{{ record.text }}
</NsTimelineItem>
</NsTimeline>
</NsSpace>
</template>
NsTimeline Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| reverse | boolean | false | 是否反向排列(最后一项显示在最上面) |
NsTimelineItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| timestamp | string | '' | 时间戳文字。是空字符串时不显示时间戳 |
| hideTimestamp | boolean | false | 是否隐藏时间戳 |
| placement | 'top' | 'bottom' | 'bottom' | 时间戳在内容的上面(top)还是下面(bottom) |
| type | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'primary' | 节点类型,决定节点的颜色 |
| color | string | '' | 节点颜色,任意 CSS 颜色值,优先于 type |
| size | 'normal' | 'large' | 'normal' | 节点大小 |
| hollow | boolean | false | 是否空心节点 |
NsTimeline Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsTimelineItem |
NsTimelineItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 这一条记录的内容 |
| dot | - | 自定义节点,代替默认的圆点 |
类型
ts
import type {
TimelineProps,
TimelineItemProps,
TimelineItemType,
TimelineItemSize,
TimelineItemPlacement
} from '@ns/ui'
type TimelineItemType = 'primary' | 'success' | 'warning' | 'danger' | 'info'
type TimelineItemSize = 'normal' | 'large'
type TimelineItemPlacement = 'top' | 'bottom'
interface TimelineProps {
reverse?: boolean
}
interface TimelineItemProps {
timestamp?: string
hideTimestamp?: boolean
placement?: TimelineItemPlacement
type?: TimelineItemType
color?: string
size?: TimelineItemSize
hollow?: boolean
}
另外还导出了 TimelineContext 和注入用的 TIMELINE_INJECTION_KEY,自己写和 NsTimeline 配合的子组件时才用得到。
注意事项
NsTimelineItem要直接放在NsTimeline里(可以隔着v-for、v-if)。最后一项不画连线是按“是不是最后一个子元素”判断的,中间包了别的元素,连线和间距就不对了。单独使用时会在控制台给出警告。NsTimelineItem没有标题属性,标题和正文都写在默认插槽里。- 用了
dot插槽后,size和hollow不再起作用,color只作为插槽内容的文字颜色。插槽内容的底色是页面背景色(--ns-bg-color),用来遮住后面的连线;时间线放在别的底色上时,图标周围会露出一小块背景色。 - 插槽里的图标建议不要超过 16px,太大会压到内容文字,也会超出时间线的左边(连线离左边 8px,16px 宽的内容正好贴边)。大号节点(16px)不会超出左边。
reverse只是把显示顺序反过来,DOM 里的顺序不变,读屏软件和 Tab 键的顺序还是原来的。
优化点
- [ ] 支持节点动画效果
- [ ] 支持节点点击交互
- [ ] 支持时间线分组显示
- [ ] 支持时间线左右交替排列
- [ ] 支持时间戳显示在节点左边
- [ ] 支持“进行中”的加载节点