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.
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控制的插槽内容,出现、消失时页头会跟着更新。 - 组件没有暴露方法。