Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Timeline 时间线
按时间顺序从上到下列出一串记录,例如操作日志、物流进度、项目里程碑。每条记录用一个 NsTimelineItem。
引入
import { NsTimeline, NsTimelineItem } from '@ns/ui'
基础用法
NsTimelineItem 的默认插槽是内容,timestamp 是时间文字,显示在内容下面。
<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 时,最后一项显示在最上面。只是显示顺序反过来,不用改数据的顺序。
<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。
<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 搭配。
左边是大小和空心的四种组合,右边是每种类型的大号空心节点:
<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。实心节点用它做底色,空心节点用它做边框色。
<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 指定。
<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(上面)。时间比内容更重要时(例如操作日志)放在上面。
<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。
<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>
丰富内容
内容区可以放任意元素和组件。内容多高,连线就跟着拉多长。
<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 生成。下面点“新增一条”往数组末尾加记录,打开开关后最新的记录显示在最上面。
<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 | - | 自定义节点,代替默认的圆点 |
类型
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 键的顺序还是原来的。
优化点
- [ ] 支持节点动画效果
- [ ] 支持节点点击交互
- [ ] 支持时间线分组显示
- [ ] 支持时间线左右交替排列
- [ ] 支持时间戳显示在节点左边
- [ ] 支持“进行中”的加载节点