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.
List 列表
把一组结构相近的内容按行排列,每一行用 NsListItem。可以带整个列表的头部、底部,以及每一项自己的标题和附加信息。
引入
import { NsList, NsListItem } from '@ns/ui'
基础用法
NsList 里放若干个 NsListItem,每一项的内容写在默认插槽里。鼠标移到列表项上时有浅色底。
<script setup lang="ts">
import { NsList, NsListItem } from '@ns/ui'
</script>
<template>
<NsList>
<NsListItem>写本周周报</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
<NsListItem>回复客户邮件</NsListItem>
</NsList>
</template>
带边框
border 给整个列表加一圈边框和圆角。上面是默认的不带边框,下面加了 border:
<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 传文字,显示在列表的最上面和最下面。
<template>
<NsList header="待办事项" footer="共 3 项" border>
<NsListItem>写本周周报</NsListItem>
<NsListItem>评审订单页设计稿</NsListItem>
<NsListItem>回复客户邮件</NsListItem>
</NsList>
</template>
要放按钮等其他内容时用 header、footer 插槽,写了插槽就不再显示对应的 prop。
<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:标题显示在内容上面,附加信息用小一号的字显示在内容下面。同样可以换成插槽。
<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。
<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 秒:
<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 就行(会落到它的根元素上)。下面点一项把它设为当前项,用自己的类名加上选中底色:
<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。
<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 | - | 列表项的附加信息 |
类型
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] 支持列表项悬停效果
- [ ] 支持列表项选中状态
- [ ] 支持列表分页加载