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.
Log 日志
按行显示日志,不同级别用不同颜色区分,新日志到来时自动滚动到底部。适合构建输出、任务执行记录、实时运行日志这类场景。
引入
import { NsLog } from '@ns/ui'
基础用法
用 logs 传入日志数组,每条日志至少要有 content。height 是面板高度,数字按 px 计算,默认 300。
<script setup lang="ts">
import { NsLog } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs: LogItem[] = [
{ content: '应用启动完成,监听端口 8080' },
{ content: '数据库连接成功' },
{ content: '加载配置文件 application.yml' }
]
</script>
<template>
<NsLog :logs="logs" :height="200" />
</template>
日志级别
level 支持 info、warn、error、debug 四种,不写时按 info 显示。warn、error 行带浅色背景,debug 行颜色较淡。
<script setup lang="ts">
import { NsLog } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs: LogItem[] = [
{ content: 'info:订单 SO20260001 创建成功', level: 'info' },
{ content: 'warn:商品 A-102 库存只剩 3 件', level: 'warn' },
{ content: 'error:调用支付接口超时(5000ms)', level: 'error' },
{ content: 'debug:请求参数 {"page":1,"size":20}', level: 'debug' },
{ content: '没写 level 时按 info 显示' }
]
</script>
<template>
<NsLog :logs="logs" :height="200" />
</template>
时间戳
传了 timestamp 的日志,会在内容前面显示时间。组件不做格式化,传什么字符串就显示什么;没传的行不显示时间。
<script setup lang="ts">
import { NsLog } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs: LogItem[] = [
{ content: '服务启动', timestamp: '2026-11-17 10:00:00' },
{ content: '内存使用率 85%', level: 'warn', timestamp: '2026-11-17 10:00:05' },
{ content: '定时任务“清理临时文件”执行失败', level: 'error', timestamp: '10:00:12' },
{ content: '这一行没有时间戳' }
]
</script>
<template>
<NsLog :logs="logs" :height="160" />
</template>
高度
height 传数字时按 px 计算;传字符串时原样使用,可以写 '10em'、'50vh',写 '100%' 时父元素要有高度。日志超出高度时在面板里滚动。
<script setup lang="ts">
import { NsLog, NsSpace } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs: LogItem[] = Array.from({ length: 12 }, (_, i) => ({
content: `同步第 ${i + 1} 批订单数据`
}))
</script>
<template>
<NsSpace direction="vertical" fill>
<NsLog :logs="logs" :height="120" />
<div style="height: 180px">
<NsLog :logs="logs" height="100%" />
</div>
</NsSpace>
</template>
上面是 :height="120",下面是 height="100%",父元素高 180px。
加载状态
loading 为 true 时右上角显示加载指示器,日志区域同时变淡。下面点按钮模拟拉取新日志,1.5 秒后追加到末尾:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLog, NsSpace } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs = ref<LogItem[]>([
{ content: '开始构建 web-admin', timestamp: '10:00:00' },
{ content: '安装依赖完成', timestamp: '10:00:18' }
])
const loading = ref(false)
const steps = ['编译 TypeScript', '打包静态资源', '上传到对象存储', '构建完成']
const fetchMore = () => {
loading.value = true
window.setTimeout(() => {
const step = steps[(logs.value.length - 2) % steps.length]
logs.value.push({ content: step, timestamp: new Date().toTimeString().slice(0, 8) })
loading.value = false
}, 1500)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton :loading="loading" icon="refresh" @click="fetchMore">拉取新日志</NsButton>
</NsSpace>
<NsLog :logs="logs" :loading="loading" :height="160" />
</NsSpace>
</template>
自动滚动
autoScroll 默认开启:日志数组被替换或者原地 push 时,自动滚动到底部。用户往上翻看旧日志时自动滚动会暂停,不会被拉回底部;滚回底部,或者调用 scrollToBottom() 后恢复。:auto-scroll="false" 时新日志到来也停在原处。
点“开始输出”模拟实时日志(每 0.3 秒一条,满 200 条自动停止),关掉开关再看区别:
<script setup lang="ts">
import { onUnmounted, ref } from 'vue'
import { NsButton, NsLog, NsSpace, NsSwitch } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs = ref<LogItem[]>([])
const autoScroll = ref(true)
const running = ref(false)
let timer: number | undefined
let count = 0
const stop = () => {
window.clearInterval(timer)
timer = undefined
running.value = false
}
const start = () => {
if (timer !== undefined) return
running.value = true
timer = window.setInterval(() => {
count++
const level = count % 13 === 0 ? 'error' : count % 5 === 0 ? 'warn' : 'info'
const content =
level === 'error'
? '调用库存接口超时,准备重试'
: level === 'warn'
? `订单 SO${20260000 + count} 的收货地址不完整`
: `同步订单 SO${20260000 + count}`
logs.value.push({ content, level, timestamp: new Date().toTimeString().slice(0, 8) })
if (logs.value.length >= 200) stop()
}, 300)
}
onUnmounted(stop)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton v-if="!running" type="primary" icon="arrow-right" @click="start">开始输出</NsButton>
<NsButton v-else icon="close" @click="stop">停止</NsButton>
<NsButton @click="logs = []">清空</NsButton>
<NsSwitch v-model="autoScroll" active-text="自动滚动(auto-scroll)" />
</NsSpace>
<NsLog :logs="logs" :auto-scroll="autoScroll" :height="240" />
</NsSpace>
</template>
滚动到顶部和底部
通过 ref 调用 scrollToTop()、scrollToBottom();scroll 事件的参数是当前的滚动位置 scrollTop。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLog, NsSpace } from '@ns/ui'
import type { LogExpose, LogItem } from '@ns/ui'
const logs: LogItem[] = Array.from({ length: 100 }, (_, i) => ({
content: `第 ${i + 1} 行:处理文件 report-${String(i + 1).padStart(3, '0')}.csv`
}))
const logRef = ref<LogExpose | null>(null)
const scrollTop = ref<number | null>(null)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton icon="arrow-up" @click="logRef?.scrollToTop()">滚到顶部</NsButton>
<NsButton icon="arrow-down" @click="logRef?.scrollToBottom()">滚到底部</NsButton>
<span>scrollTop:{{ scrollTop ?? '滚动后显示' }}</span>
</NsSpace>
<NsLog ref="logRef" :logs="logs" :height="200" @scroll="scrollTop = Math.round($event)" />
</NsSpace>
</template>
搜索过滤
search-query 不为空时,只显示内容里包含这个关键字的行,不区分大小写。只过滤,不高亮匹配的文字。试试输入 error 或 订单:
<script setup lang="ts">
import { ref } from 'vue'
import { NsInput, NsLog, NsSpace } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const keyword = ref('')
const logs: LogItem[] = [
{ content: 'ERROR 订单服务连接数据库失败', level: 'error' },
{ content: 'error in payment service', level: 'error' },
{ content: 'INFO 订单 SO20260001 创建成功' },
{ content: 'WARN 磁盘剩余空间不足 10%', level: 'warn' },
{ content: 'INFO 用户张伟登录成功' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsInput v-model="keyword" placeholder="搜索日志" clearable style="max-width: 240px" />
<NsLog :logs="logs" :search-query="keyword" :height="160" />
</NsSpace>
</template>
最大行数
max-lines 限制显示的行数,只保留最后 N 行(先按 search-query 过滤,再截取)。传入的 logs 不会被修改,日志一直增长时需要自己删掉旧数据。下面有 200 条日志,改数字看显示的行数:
<script setup lang="ts">
import { ref } from 'vue'
import { NsInputNumber, NsLog, NsSpace } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs: LogItem[] = Array.from({ length: 200 }, (_, i) => ({
content: `日志条目 ${i + 1}`
}))
const maxLines = ref<number | undefined>(100)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<span>最多显示</span>
<NsInputNumber v-model="maxLines" :min="1" :max="200" :step="10" />
<span>行(第 {{ 200 - (maxLines ?? 200) + 1 }} 到 200 条)</span>
</NsSpace>
<NsLog :logs="logs" :max-lines="maxLines" :height="200" />
</NsSpace>
</template>
虚拟滚动
日志很多(上万条)时开启 virtual-scroll,只渲染可见区域的几十行。虚拟模式下每行固定 24px 高、只显示一行,长行超出部分显示省略号。scrollToTop()、scrollToBottom() 和 scroll 事件在虚拟模式下同样可用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLog, NsSpace } from '@ns/ui'
import type { LogExpose, LogItem } from '@ns/ui'
const levels = ['info', 'warn', 'error', 'debug'] as const
const logs: LogItem[] = Array.from({ length: 10000 }, (_, i) => ({
content:
i % 50 === 0
? `日志条目 ${i + 1}:这一行特别长,用来演示虚拟模式下长行只显示一行,超出的部分显示省略号,需要看完整内容时请用普通模式`
: `日志条目 ${i + 1}`,
level: levels[i % 4]
}))
const logRef = ref<LogExpose | null>(null)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton icon="arrow-up" @click="logRef?.scrollToTop()">第一条</NsButton>
<NsButton icon="arrow-down" @click="logRef?.scrollToBottom()">最后一条</NsButton>
</NsSpace>
<NsLog ref="logRef" :logs="logs" virtual-scroll :height="400" />
</NsSpace>
</template>
清空日志
logs 是 prop,组件不能直接改。clearLogs() 会触发 update:logs([]) 和 clear:
- 用
v-model:logs绑定时会自动清空(上面的面板)。 - 只用
:logs时要在clear事件里自己清空数组(下面的面板)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsLog, NsSpace } from '@ns/ui'
import type { LogExpose, LogItem } from '@ns/ui'
const initial: LogItem[] = [
{ content: '开始备份数据库 order_db' },
{ content: '备份完成,文件大小 128MB' }
]
const logs = ref<LogItem[]>([...initial])
const logRef = ref<LogExpose | null>(null)
const otherLogs = ref<LogItem[]>([...initial])
const otherRef = ref<LogExpose | null>(null)
const clearCount = ref(0)
const handleClear = () => {
otherLogs.value = []
clearCount.value++
}
const restore = () => {
logs.value = [...initial]
otherLogs.value = [...initial]
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton icon="trash" @click="logRef?.clearLogs()">清空(v-model:logs)</NsButton>
<NsButton icon="trash" @click="otherRef?.clearLogs()">清空(:logs + @clear)</NsButton>
<NsButton @click="restore">恢复</NsButton>
</NsSpace>
<NsLog ref="logRef" v-model:logs="logs" :height="100" />
<NsLog ref="otherRef" :logs="otherLogs" :height="100" @clear="handleClear" />
<p>clear 事件触发了 {{ clearCount }} 次</p>
</NsSpace>
</template>
自定义行内容
默认插槽替换每一行的内容,参数是 { log, index }。行的级别颜色和背景仍然由组件负责。
<script setup lang="ts">
import { NsLog } from '@ns/ui'
import type { LogItem } from '@ns/ui'
const logs: LogItem[] = [
{ content: '订单 SO20260001 创建成功', level: 'info' },
{ content: '商品 A-102 库存只剩 3 件', level: 'warn' },
{ content: '调用支付接口超时', level: 'error' },
{ content: '请求参数 {"page":1}', level: 'debug' },
{ content: '没写级别时按 info 显示' }
]
</script>
<template>
<NsLog :logs="logs" :height="160">
<template #default="{ log, index }">
<span style="display: inline-block; width: 3em">{{ index + 1 }}</span>
<span>[{{ (log.level || 'info').toUpperCase() }}] {{ log.content }}</span>
</template>
</NsLog>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| logs | LogItem[] | [] | 日志数据,支持 v-model:logs |
| loading | boolean | false | 是否在右上角显示加载指示器,日志区域同时变淡 |
| maxLines | number | undefined | 最多显示的行数,只保留最后 N 行;不传时全部显示 |
| autoScroll | boolean | true | 有新日志时是否自动滚动到底部。用户滚离底部后暂停,滚回底部后恢复 |
| searchQuery | string | '' | 搜索关键字,不区分大小写的包含过滤,不高亮 |
| virtualScroll | boolean | false | 是否启用虚拟滚动。开启后每行固定 24px 高,长行显示省略号 |
| height | number | string | 300 | 面板高度。数字按 px;字符串原样使用,可以写 '50vh'、'100%'(父元素要有高度) |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| scroll | (scrollTop: number) | 日志区域滚动时触发,虚拟模式下也会触发 |
| clear | () | 调用 clearLogs() 时触发 |
| update:logs | (logs: LogItem[]) | 调用 clearLogs() 时触发,参数是空数组,v-model:logs 用的就是它 |
Slots
| 插槽 | 参数 | 说明 |
|---|---|---|
| default | { log: LogItem; index: number } | 自定义每一行的内容 |
方法
| 方法 | 参数 | 说明 |
|---|---|---|
| scrollToBottom | - | 滚动到底部,并恢复自动滚动 |
| scrollToTop | - | 滚动到顶部 |
| clearLogs | - | 触发 update:logs([]) 和 clear,需要配合 v-model:logs 才会真正清空 |
类型
import type { LogItem, LogLevel, LogProps, LogExpose } from '@ns/ui'
type LogLevel = 'info' | 'warn' | 'error' | 'debug'
interface LogItem {
content: string
level?: LogLevel
timestamp?: string
[key: string]: unknown
}
interface LogExpose {
scrollToBottom: () => void
scrollToTop: () => void
clearLogs: () => void
}
注意事项
- 虚拟模式下行高固定 24px,内容只显示一行,长行显示省略号;需要看完整内容时用普通模式。
- 普通模式下长行自动换行,内容里的空格、Tab 和
\n原样保留。 - 用户滚离底部后自动滚动会暂停,滚回底部或调用
scrollToBottom()后恢复。 - 不解析 ANSI 颜色码,
\x1b[31m这类控制字符会原样显示。 maxLines只影响显示,不会修改传入的logs;日志无限增长时请自己裁剪数组。- 自动滚动只监听数组替换和长度变化,原地修改某一行的
content不会触发滚动。 - 日志区域带
role="log",读屏软件会播报新增的日志;加载指示器带role="status"。
优化点
- [ ] 支持日志级别过滤
- [ ] 搜索关键字高亮
- [ ] 解析 ANSI 颜色码
- [ ] 支持复制全部、导出日志
- [ ] 虚拟模式开放行高配置