PageHeader 页头
放在页面最上方,显示页面标题、副标题、返回按钮、面包屑和右侧的操作按钮。
引入
ts
import { NsPageHeader } from '@ns/ui'
基础用法
title 是标题,subtitle 是标题右边的副标题,两个都可以单独用。
vue
<template>
<NsSpace direction="vertical" fill>
<NsPageHeader title="用户管理" subtitle="管理系统中的所有用户" />
<NsPageHeader title="只有标题" />
</NsSpace>
</template>
返回按钮
show-back 为 true 时标题左边显示返回按钮,点击(或聚焦后按回车、空格)触发 back 事件。组件不会自己跳转,要在事件里处理,例如调用路由的 back();下面的示例用提示代替跳转。back-icon 换按钮的图标(NsIcon 的 name),默认 arrow-left。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsMessage, NsPageHeader, NsSpace } from '@ns/ui'
const backCount = ref(0)
// 实际使用时在这里跳转,例如 router.back()
const handleBack = () => {
backCount.value += 1
NsMessage.info('触发了 back 事件')
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsPageHeader title="用户详情" subtitle="默认图标 arrow-left" show-back @back="handleBack" />
<NsPageHeader
title="编辑用户"
subtitle="图标 chevron-left"
show-back
back-icon="chevron-left"
@back="handleBack"
/>
<NsPageHeader
title="订单列表"
subtitle="图标 double-left"
show-back
back-icon="double-left"
@back="handleBack"
/>
</NsSpace>
<p style="margin-top: 12px">已触发 {{ backCount }} 次 back</p>
</template>
图标
icon 在标题前面显示一个图标(NsIcon 的 name),和返回按钮同时用时在返回按钮的右边。
vue
<template>
<NsSpace direction="vertical" fill>
<NsPageHeader title="系统设置" icon="setting" />
<NsPageHeader title="成员管理" subtitle="共 32 人" icon="users" />
<NsPageHeader title="文件详情" icon="folder" show-back />
</NsSpace>
</template>
面包屑和操作区
breadcrumb 插槽显示在最上面,独占一行;extra 插槽显示在标题这一行的最右边,空间不够时换到下一行。extra 里放几个按钮时用 NsSpace 排开,不然会挨在一起。
vue
<script setup lang="ts">
import { NsPageHeader, NsBreadcrumb, NsBreadcrumbItem, NsButton, NsSpace } from '@ns/ui'
</script>
<template>
<NsPageHeader title="用户管理" subtitle="共 128 人">
<template #breadcrumb>
<NsBreadcrumb>
<NsBreadcrumbItem to="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem to="/system">系统管理</NsBreadcrumbItem>
<NsBreadcrumbItem>用户管理</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
<template #extra>
<NsSpace>
<NsButton icon="upload">导入</NsButton>
<NsButton icon="download">导出</NsButton>
<NsButton type="primary" icon="plus">新增用户</NsButton>
</NsSpace>
</template>
</NsPageHeader>
</template>
底部和内容
footer 插槽显示在标题行下面,常用来放标签页;默认插槽显示在 footer 下面,放说明文字等内容。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { NsPageHeader, NsTabs, NsTabPane } from '@ns/ui'
const activeTab = ref<string | number>('basic')
</script>
<template>
<NsPageHeader title="订单详情" show-back>
<template #footer>
<NsTabs v-model="activeTab">
<NsTabPane name="basic" label="基本信息" />
<NsTabPane name="log" label="操作记录" />
</NsTabs>
</template>
<p style="margin: 0; color: var(--ns-text-color-secondary)">订单号:20261117001</p>
</NsPageHeader>
</template>
自定义标题
title、subtitle 插槽可以放文字以外的内容,写了插槽时对应的属性不显示。
vue
<script setup lang="ts">
import { NsPageHeader, NsTag } from '@ns/ui'
</script>
<template>
<NsPageHeader>
<template #title>
项目 A
<NsTag type="success" style="margin-left: 8px">进行中</NsTag>
</template>
<template #subtitle>负责人:李四</template>
</NsPageHeader>
</template>
幽灵模式
ghost 为 true 时去掉背景色和底部分割线,上下内边距变小、左右没有内边距,适合放在已经有背景的容器里。下面两个页头放在同样的灰色容器里,上面是普通页头,下面是幽灵模式:
vue
<template>
<NsSpace direction="vertical" fill>
<div class="box">
<NsPageHeader title="数据概览" subtitle="普通页头" />
</div>
<div class="box">
<NsPageHeader title="数据概览" subtitle="ghost" ghost />
</div>
</NsSpace>
</template>
<style scoped>
.box {
padding: var(--ns-spacing-4);
background-color: var(--ns-bg-color-page);
border-radius: var(--ns-border-radius);
}
</style>
完整示例
所有插槽和属性一起用:面包屑、返回按钮、图标、标题、副标题、操作区、底部标签页和内容区。
vue
<script setup lang="ts">
import { ref } from 'vue'
import {
NsBreadcrumb,
NsBreadcrumbItem,
NsButton,
NsMessage,
NsPageHeader,
NsSpace,
NsTabPane,
NsTabs,
NsTag
} from '@ns/ui'
const activeTab = ref<string | number>('detail')
const handleBack = () => {
NsMessage.info('返回上一页')
}
</script>
<template>
<NsPageHeader icon="file" show-back @back="handleBack">
<template #breadcrumb>
<NsBreadcrumb>
<NsBreadcrumbItem to="/">首页</NsBreadcrumbItem>
<NsBreadcrumbItem to="/contract">合同管理</NsBreadcrumbItem>
<NsBreadcrumbItem>合同详情</NsBreadcrumbItem>
</NsBreadcrumb>
</template>
<template #title>
HT-2026-0018
<NsTag type="warning" style="margin-left: 8px">待审批</NsTag>
</template>
<template #subtitle>采购合同</template>
<template #extra>
<NsSpace>
<NsButton icon="edit">编辑</NsButton>
<NsButton type="danger" variant="outline">驳回</NsButton>
<NsButton type="primary" icon="check">通过</NsButton>
</NsSpace>
</template>
<template #footer>
<NsTabs v-model="activeTab">
<NsTabPane name="detail" label="合同信息" />
<NsTabPane name="attachment" label="附件" />
<NsTabPane name="history" label="审批记录" />
</NsTabs>
</template>
<p style="margin: 0; color: var(--ns-text-color-secondary)">
当前标签页:{{ activeTab }}。创建人:王五,创建时间 2026-11-10。
</p>
</NsPageHeader>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | string | - | 标题。写了 title 插槽时不显示 |
| subtitle | string | - | 副标题。写了 subtitle 插槽时不显示 |
| icon | string | - | 标题前面的图标名(NsIcon 的 name) |
| showBack | boolean | false | 是否显示返回按钮 |
| backIcon | string | 'arrow-left' | 返回按钮的图标名(NsIcon 的 name) |
| ghost | boolean | false | 是否去掉背景色和底部分割线 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| back | - | 点返回按钮(或聚焦后按回车、空格)时触发 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 内容区,显示在最下面(footer 的下面) |
| breadcrumb | - | 面包屑,显示在最上面,独占一行 |
| title | - | 标题内容,替换 title 属性 |
| subtitle | - | 副标题内容,替换 subtitle 属性 |
| extra | - | 操作区,显示在标题这一行的最右边 |
| footer | - | 底部,显示在标题行下面、内容区上面 |
类型
ts
import type { PageHeaderProps, PageHeaderEmits } from '@ns/ui'
interface PageHeaderProps {
title?: string
subtitle?: string
icon?: string
showBack?: boolean
backIcon?: string
ghost?: boolean
}
interface PageHeaderEmits {
back: []
}
注意事项
- 返回按钮默认不显示,要显示需加
show-back。 - 图标只能用
icon属性传图标名,没有icon插槽。 - 返回按钮是原生
<button>,带aria-label="返回",可以用 Tab 键聚焦,按回车或空格触发back。 - 没写的插槽不占位置。用
v-if控制的插槽内容,出现、消失时页头会跟着更新。 - 组件没有暴露方法。