Card 卡片
把一组相关的信息放进一个带边框和阴影的容器里,由标题区、内容区和底部三部分组成,可以加封面图、折叠和关闭按钮。
引入
import { NsCard } from '@ns/ui'
基础用法
title 设置标题,默认插槽是内容。
<script setup lang="ts">
import { NsCard } from '@ns/ui'
</script>
<template>
<NsCard title="卡片标题">
<p>卡片内容</p>
</NsCard>
</template>
标题和副标题
subtitle 显示在标题下面。也可以用 title、subtitle 插槽自定义;header 插槽(或旧写法 header 属性)的内容显示在标题和副标题下面,需要完全自定义标题区时用它。
<script setup lang="ts">
import { NsCard, NsSpace, NsTag } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsCard title="卡片标题" subtitle="这是副标题">
<p>卡片内容</p>
</NsCard>
<NsCard>
<template #title>自定义标题</template>
<p>卡片内容</p>
</NsCard>
<NsCard title="订单 #20261118">
<template #subtitle>
<NsSpace size="small">
<NsTag type="success" size="small">已支付</NsTag>
<NsTag type="info" size="small">待发货</NsTag>
</NsSpace>
</template>
<p>用 subtitle 插槽在标题下面放标签</p>
</NsCard>
<NsCard>
<template #header>
<div><strong>header 插槽</strong>:标题区完全自己写</div>
</template>
<p>卡片内容</p>
</NsCard>
<NsCard header="header 属性(旧写法)">
<p>新代码建议用 title</p>
</NsCard>
</NsSpace>
</template>
标题右侧操作区
header-extra 插槽放在标题区右侧,适合放“编辑”“更多”这类按钮。可折叠卡片里点这个区域不会折叠,点标题区的其他地方会折叠。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCard, NsButton, NsSpace } from '@ns/ui'
const editCount = ref(0)
const edit = () => {
editCount.value += 1
}
</script>
<template>
<NsCard title="用户信息" collapsible>
<template #header-extra>
<NsSpace size="small">
<NsButton size="small" @click="edit">编辑</NsButton>
<NsButton size="small" variant="text" icon="more-horizontal" aria-label="更多" />
</NsSpace>
</template>
<p>点了 {{ editCount }} 次“编辑”,卡片没有折叠</p>
</NsCard>
</template>
底部
footer 插槽是底部区域,文字是次要色。action 插槽放一排操作按钮,按钮之间自动留 8px 间距,显示在 footer 内容的下面。两个插槽可以只写一个。
<script setup lang="ts">
import { NsCard, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsCard title="带底部的卡片">
<p>卡片内容</p>
<template #footer>更新于 2026-11-17</template>
<template #action>
<NsButton size="small">取消</NsButton>
<NsButton size="small" type="primary">确定</NsButton>
</template>
</NsCard>
<NsCard title="只有 footer">
<p>卡片内容</p>
<template #footer>共 12 条记录</template>
</NsCard>
<NsCard title="只有 action">
<p>卡片内容</p>
<template #action>
<NsButton size="small" icon="edit">编辑</NsButton>
<NsButton size="small" icon="share">分享</NsButton>
<NsButton size="small" type="danger" icon="trash">删除</NsButton>
</template>
</NsCard>
</NsSpace>
</template>
封面
cover 传图片地址,显示在卡片最上面。图片的 alt 是 title,没有 title 时为空(读屏会跳过)。
<script setup lang="ts">
import { NsButton, NsCard, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start">
<NsCard cover="/images/cover.png" title="风景" style="width: 300px">
<p>卡片内容</p>
</NsCard>
<NsCard cover="/images/cover.png" hoverable style="width: 300px">
<p>没有标题,图片的 alt 为空</p>
<template #action>
<NsButton size="small" type="primary">查看</NsButton>
</template>
</NsCard>
</NsSpace>
</template>
阴影、边框和悬浮效果
shadow 设置阴影显示时机:always(默认,一直显示)、hover(悬停时显示)、never(不显示)。:bordered="false" 去掉边框。hoverable 让卡片在悬停时上浮 2px 并加深阴影,鼠标变成手形,适合可点击的卡片。把鼠标移到下面的卡片上对比:
<script setup lang="ts">
import { NsCard } from '@ns/ui'
</script>
<template>
<div class="grid">
<NsCard title="一直显示(always)">
<p>默认值</p>
</NsCard>
<NsCard title="悬停显示(hover)" shadow="hover">
<p>移上来才有阴影</p>
</NsCard>
<NsCard title="不显示(never)" shadow="never">
<p>只有边框</p>
</NsCard>
<NsCard title="无边框" :bordered="false">
<p>只有阴影</p>
</NsCard>
<NsCard title="悬停显示、无边框" shadow="hover" :bordered="false">
<p>平时和背景融在一起</p>
</NsCard>
<NsCard title="悬浮卡片(hoverable)" hoverable>
<p>悬停时上浮</p>
</NsCard>
</div>
</template>
<style scoped>
.grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
gap: var(--ns-spacing-4);
}
</style>
尺寸
size 有 small、default、large 三种,改变内边距和字号,依次是:内容区内边距 12、16、20px,正文和底部文字 12、14、16px,标题 14、16、20px,折叠、关闭按钮的图标 14、16、18px。不写时跟随 NsConfigProvider 的 size,都没有时是 default。
medium 是旧写法,已不推荐,效果和 default 一样,旧代码不用改也能用。
<script setup lang="ts">
import { NsButton, NsCard, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsCard size="small" title="小尺寸(small)" subtitle="副标题" collapsible closable>
<p>卡片内容</p>
<template #footer>底部文字</template>
<template #action>
<NsButton size="small" type="primary">确定</NsButton>
</template>
</NsCard>
<NsCard title="默认尺寸(default)" subtitle="副标题" collapsible closable>
<p>卡片内容</p>
<template #footer>底部文字</template>
<template #action>
<NsButton type="primary">确定</NsButton>
</template>
</NsCard>
<NsCard size="large" title="大尺寸(large)" subtitle="副标题" collapsible closable>
<p>卡片内容</p>
<template #footer>底部文字</template>
<template #action>
<NsButton size="large" type="primary">确定</NsButton>
</template>
</NsCard>
</NsSpace>
</template>
内容区样式
body-style 给内容区加行内样式,例如去掉内边距让图片贴边,或者换底色。
<script setup lang="ts">
import { NsCard, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start">
<NsCard :body-style="{ padding: '0' }" style="width: 300px">
<img src="/images/cover.png" alt="" style="width: 100%; display: block" />
</NsCard>
<NsCard
title="换了底色和内边距"
:body-style="{ padding: '32px', backgroundColor: 'var(--ns-fill-color)' }"
style="width: 300px"
>
<p>内容区底色是 --ns-fill-color</p>
</NsCard>
</NsSpace>
</template>
可折叠
collapsible 让卡片可以折叠:点标题区(右侧操作区除外)或右侧的折叠按钮切换。折叠后只剩标题区,底部也会隐藏。用 v-model:collapsed 可以在外部读取和控制折叠状态;只想设初始状态时直接写 collapsed。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCard, NsButton, NsSpace } from '@ns/ui'
const collapsed = ref(false)
</script>
<template>
<NsSpace direction="vertical" fill>
<div>
<NsButton @click="collapsed = !collapsed">{{ collapsed ? '展开' : '折叠' }}</NsButton>
</div>
<NsCard v-model:collapsed="collapsed" title="可折叠卡片" collapsible>
<p>卡片内容</p>
<template #footer>当前状态:{{ collapsed ? '已折叠' : '已展开' }}</template>
</NsCard>
<NsCard title="一开始就是折叠的" collapsible collapsed>
<p>点标题区展开</p>
<template #footer>展开后才显示底部</template>
</NsCard>
</NsSpace>
</template>
可关闭
closable 在标题区右侧显示关闭按钮(没有标题时也会显示)。点击只发出 close 事件,卡片不会自己消失,要由父组件隐藏。和 collapsible 一起用时,折叠按钮在关闭按钮左边。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCard, NsSpace } from '@ns/ui'
const visible = ref(true)
const noTitleVisible = ref(true)
const reset = () => {
visible.value = true
noTitleVisible.value = true
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsCard v-if="visible" title="可关闭卡片" closable collapsible @close="visible = false">
<p>卡片内容</p>
</NsCard>
<NsCard v-if="noTitleVisible" closable @close="noTitleVisible = false">
<p>没有标题也显示关闭按钮</p>
</NsCard>
<div v-if="!visible || !noTitleVisible">
<NsButton icon="refresh" @click="reset">重新显示</NsButton>
</div>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | string | - | 标题 |
| subtitle | string | - | 副标题,显示在标题下面 |
| header | string | - | 标题区的文字,旧写法,新代码建议用 title |
| cover | string | - | 封面图片地址 |
| bodyStyle | Record<string, string | number> | - | 内容区的行内样式 |
| shadow | 'always' | 'hover' | 'never' | 'always' | 阴影显示时机 |
| bordered | boolean | true | 是否显示边框 |
| hoverable | boolean | false | 悬停时是否上浮并加深阴影 |
| collapsible | boolean | false | 是否可折叠 |
| collapsed | boolean | false | 是否已折叠,支持 v-model:collapsed。只在 collapsible 时起作用 |
| closable | boolean | false | 是否显示关闭按钮 |
| size | 'large' | 'default' | 'small' | 'medium' | - | 尺寸。不写时跟随 NsConfigProvider 的 size,都没有时是 'default'。'medium' 已不推荐,等同于 'default' |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:collapsed | (collapsed: boolean) | 用户点标题区或折叠按钮切换折叠状态时触发,v-model:collapsed 用的就是它 |
| close | - | 点关闭按钮时触发。卡片不会自己隐藏 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 内容区 |
| title | - | 自定义标题,替换 title 属性 |
| subtitle | - | 自定义副标题,替换 subtitle 属性 |
| header | - | 标题区的自定义内容,显示在标题和副标题下面,替换 header 属性 |
| header-extra | - | 标题区右侧的操作区,点这里不会折叠卡片 |
| footer | - | 底部区域 |
| action | - | 底部的一排操作按钮,显示在 footer 内容下面 |
类型
import type { CardProps, CardEmits, CardShadow, CardSize } from '@ns/ui'
type CardShadow = 'always' | 'hover' | 'never'
/** @deprecated 改用 'default'。'medium' 只为兼容旧代码保留,效果和 'default' 一样 */
type CardSizeMedium = 'medium'
type CardSize = 'large' | 'default' | 'small' | CardSizeMedium
interface CardProps {
header?: string
title?: string
subtitle?: string
bodyStyle?: Record<string, string | number>
shadow?: CardShadow
bordered?: boolean
hoverable?: boolean
collapsible?: boolean
collapsed?: boolean
closable?: boolean
cover?: string
size?: CardSize
}
interface CardEmits {
(e: 'update:collapsed', value: boolean): void
(e: 'close'): void
}
注意事项
closable只发出close事件,不会自己隐藏卡片,要由父组件用v-if或v-show控制。- 有
title、subtitle、header、closable、collapsible或标题区的任一插槽时才渲染标题区;有footer或action插槽时才渲染底部。插槽可以用v-if动态出现。 - 折叠后内容区用
v-show隐藏(内容里的组件不会被销毁),底部被移除。 - 关闭和折叠按钮都是
type="button"的原生按钮,卡片放在<form>里点它们不会提交表单;它们可以用 Tab 聚焦,按回车或空格触发。 - 不写
size时跟随NsConfigProvider的size,放在设了size的NsConfigProvider里时卡片会跟着变大或变小;不跟随NsForm的尺寸(卡片不是表单控件)。 size="medium"已不推荐,等同于size="default",根元素上的类名也是ns-card--default。
优化点
- [ ] 支持卡片元信息(头像、标题、描述)的快捷布局
- [ ] 增加
header-class、body-class、footer-class等样式属性 - [ ] 增加
embedded属性,用更深的背景色表现嵌入效果 - [ ] 增加
segmented属性,标题区、内容区、底部之间加分隔线的开关 - [ ] 支持加载中状态(内容区显示骨架屏)