List 列表
把一组结构相近的内容按行排列,每一行用 NsListItem。可以带整个列表的头部、底部,以及每一项自己的标题和附加信息。
引入
ts
import { NsList, NsListItem } from '@ns/ui'
基础用法
NsList 里放若干个 NsListItem,每一项的内容写在默认插槽里。鼠标移到列表项上时有浅色底。
vue
<script setup lang="ts">
import { NsList, NsListItem } from '@ns/ui'
</script>
<template>
<NsList>
<NsListItem>写本周周报</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
<NsListItem>回复客户邮件</NsListItem>
</NsList>
</template>
带边框
border 给整个列表加一圈边框和圆角。上面是默认的不带边框,下面加了 border:
vue
<template>
<NsSpace direction="vertical" fill>
<NsList header="不带边框">
<NsListItem>写本周周报</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
</NsList>
<NsList header="border" border>
<NsListItem>写本周周报</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
</NsList>
</NsSpace>
</template>
头部和底部
header、footer 传文字,显示在列表的最上面和最下面。
vue
<template>
<NsList header="待办事项" footer="共 3 项" border>
<NsListItem>写本周周报</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
<NsListItem>回复客户邮件</NsListItem>
</NsList>
</template>
要放按钮等其他内容时用 header、footer 插槽,写了插槽就不再显示对应的 prop。
vue
<script setup lang="ts">
import { NsList, NsListItem, NsButton } from '@ns/ui'
</script>
<template>
<NsList border>
<template #header>
<div style="display: flex; justify-content: space-between; align-items: center">
<span>待办事项</span>
<NsButton size="small" type="primary" icon="plus">新增</NsButton>
</div>
</template>
<NsListItem>写本周周报</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
<template #footer>
<NsButton type="primary" variant="link" href="https://example.com" target="_blank">
查看全部
</NsButton>
</template>
</NsList>
</template>
列表项的标题和附加信息
NsListItem 也有 header、footer:标题显示在内容上面,附加信息用小一号的字显示在内容下面。同样可以换成插槽。
vue
<script setup lang="ts">
import { NsButton, NsList, NsListItem, NsSpace, NsTag } from '@ns/ui'
</script>
<template>
<NsList border>
<NsListItem header="版本 1.2.0 发布" footer="2026-03-01">
新增表格固定列,修复分页页码显示的问题。
</NsListItem>
<NsListItem footer="2026-02-15">
<template #header>
<NsSpace :size="8">
<strong>版本 1.1.0 发布</strong>
<NsTag size="small" type="success">稳定版</NsTag>
</NsSpace>
</template>
新增时间线组件。
</NsListItem>
<NsListItem header="版本 1.0.0 发布">
第一个正式版本。
<template #footer>
<NsSpace :size="8">
<span>2026-01-10</span>
<NsButton size="small" variant="link" type="primary">查看更新说明</NsButton>
</NsSpace>
</template>
</NsListItem>
</NsList>
</template>
尺寸
size 可选 large、default、small,同时影响头部、底部和每个列表项的内边距和字号。内边距是 20、16、12px;文字 large、default 都是 14px(large 的头部标题是 16px),small 是 12px。不写 size 时跟随 ConfigProvider,都没有时是 default。
vue
<template>
<NsSpace direction="vertical" fill>
<NsList size="large" header="large" footer="共 2 项" border>
<NsListItem header="写本周周报" footer="今天 18:00 前">周五下班前发给主管</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
</NsList>
<NsList header="default" footer="共 2 项" border>
<NsListItem header="写本周周报" footer="今天 18:00 前">周五下班前发给主管</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
</NsList>
<NsList size="small" header="small" footer="共 2 项" border>
<NsListItem header="写本周周报" footer="今天 18:00 前">周五下班前发给主管</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
</NsList>
</NsSpace>
</template>
加载中
loading 为 true 时在列表项上盖一层半透明的遮罩并显示加载图标,这时列表项不能点击。头部和底部不受影响。下面可以用开关直接切换,也可以点“刷新”模拟请求 1.5 秒:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsList, NsListItem, NsSpace, NsSwitch } from '@ns/ui'
const loading = ref(true)
const batch = ref(1)
const messages = ['张伟评论了你的文章', '王芳给你分配了任务', '系统将于今晚 23:00 维护']
const refresh = () => {
loading.value = true
window.setTimeout(() => {
batch.value++
loading.value = false
}, 1500)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsSwitch v-model="loading" active-text="loading" />
<NsButton icon="refresh" :loading="loading" @click="refresh">刷新</NsButton>
</NsSpace>
<NsList :loading="loading" header="最新消息" :footer="`第 ${batch} 次刷新`" border>
<NsListItem v-for="text in messages" :key="text">{{ text }}</NsListItem>
</NsList>
</NsSpace>
</template>
点击列表项
NsListItem 没有 click 事件,直接在它上面写 @click 就行(会落到它的根元素上)。下面点一项把它设为当前项,用自己的类名加上选中底色:
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsList, NsListItem } from '@ns/ui'
const contacts = [
{ id: 1, name: '张伟', dept: '研发部' },
{ id: 2, name: '王芳', dept: '市场部' },
{ id: 3, name: '李娜', dept: '财务部' }
]
const activeId = ref(1)
</script>
<template>
<NsList class="contacts" border>
<NsListItem
v-for="item in contacts"
:key="item.id"
:header="item.name"
:class="{ 'is-active': item.id === activeId }"
style="cursor: pointer"
@click="activeId = item.id"
>
{{ item.dept }}
</NsListItem>
<template #footer>当前选中:{{ contacts.find((c) => c.id === activeId)?.name }}</template>
</NsList>
</template>
<style scoped>
.contacts .is-active,
.contacts .is-active:hover {
background-color: var(--ns-color-primary-bg);
}
</style>
渲染数组
列表项一般用 v-for 生成。组件没有空状态,数组为空时自己在默认插槽里写提示,例如放一个 NsEmpty。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsEmpty, NsList, NsListItem, NsSpace } from '@ns/ui'
interface Todo {
id: number
title: string
desc: string
}
const candidates = ['整理会议纪要', '更新项目排期', '准备季度汇报', '跟进合同回款']
const items = ref<Todo[]>([
{ id: 1, title: '写本周周报', desc: '周五下班前发给主管' },
{ id: 2, title: '评审订单页设计稿', desc: '周三下午两点,3 号会议室' }
])
let nextId = 3
const add = () => {
const title = candidates[(nextId - 3) % candidates.length]
items.value.push({ id: nextId++, title, desc: '新加的待办' })
}
const remove = (id: number) => {
items.value = items.value.filter((item) => item.id !== id)
}
</script>
<template>
<NsList border :footer="`共 ${items.length} 条`">
<template #header>
<NsSpace wrap>
<NsButton size="small" type="primary" icon="plus" @click="add">新增</NsButton>
<NsButton size="small" :disabled="items.length === 0" @click="items = []">清空</NsButton>
</NsSpace>
</template>
<NsListItem v-for="item in items" :key="item.id" :header="item.title">
{{ item.desc }}
<template #footer>
<NsButton size="small" variant="link" type="danger" @click="remove(item.id)">
删除
</NsButton>
</template>
</NsListItem>
<NsEmpty v-if="items.length === 0" description="暂无待办" />
</NsList>
</template>
NsList Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| header | string | - | 列表头部的文字。写了 header 插槽时不显示 |
| footer | string | - | 列表底部的文字。写了 footer 插槽时不显示 |
| loading | boolean | false | 是否显示加载中的遮罩 |
| size | 'large' | 'default' | 'small' | - | 尺寸,影响头部、底部和列表项的内边距和字号。不写时跟随 ConfigProvider,都没有时是 'default' |
| border | boolean | false | 是否显示外边框 |
NsListItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| header | string | - | 列表项的标题,显示在内容上面。写了 header 插槽时不显示 |
| footer | string | - | 列表项的附加信息,显示在内容下面。写了 footer 插槽时不显示 |
NsList Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 列表内容,放 NsListItem |
| header | - | 列表头部 |
| footer | - | 列表底部 |
NsListItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 列表项的内容 |
| header | - | 列表项的标题 |
| footer | - | 列表项的附加信息 |
类型
ts
import type { ListProps, ListItemProps, ListSize } from '@ns/ui'
type ListSize = 'large' | 'default' | 'small'
interface ListProps {
header?: string
footer?: string
loading?: boolean
size?: ListSize
border?: boolean
}
interface ListItemProps {
header?: string
footer?: string
}
注意事项
- 没有列表项时列表是空的,组件没有“暂无数据”的提示,需要时自己判断后在默认插槽里写。
NsListItem没有click事件,也不是可聚焦的元素。要点击整行时在NsListItem上直接写@click(会落到它的根元素上),需要键盘操作时在里面放按钮或链接。NsListItem的size由外层的NsList决定,单独拿出来用时是默认尺寸。- 列表项的内容太长时会自动换行,连续的英文和数字也会被折断。
优化点
- [ ] 支持空状态(没有列表项时显示提示)
- [ ] 支持无限滚动加载
- [x] 支持列表项悬停效果
- [ ] 支持列表项选中状态
- [ ] 支持列表分页加载