FPageHeader 页头

页面级头部组件，提供标题、返回按钮、标签、操作按钮和元数据展示功能。

💡 组件命名规范：组件名主推 FPageHeader（保留兼容别名导出 FinPageHeader）。

---

快速上手与演示

基础用法

最简配置：传入标题和返回按钮。

loading

带标签和操作按钮

支持显示状态标签和操作按钮组。

loading

带元数据描述

支持显示二级元数据信息行。

loading

完整示例

结合标题、标签、按钮和元数据的完整场景。

loading

Card 模式

配合 PageLayout 使用的卡片模式。

loading

---

全量 API 参数指南

FPageHeaderProps (组件 Props 配置)

属性名	类型	默认值	说明
title	string	-	页面标题
back	boolean | BackConfig	true	返回按钮配置，false 隐藏
tags	PageHeaderTagConfig[]	[]	标签列表配置
descriptions	PageHeaderDescriptionItem[]	[]	元数据描述项列表
data	Record<string, any>	-	数据对象，用于描述项的字段绑定
actions	ActionButtonConfig[]	[]	操作按钮列表
actionsMaxCount	number	1	操作按钮最多直接平铺显示的个数
actionsMorePosition	'left' | 'right'	'right'	"更多"下拉菜单的位置
mode	'normal' | 'card'	'normal'	显示模式：normal 普通模式，card 卡片模式

BackConfig (返回按钮配置)

属性名	类型	默认值	说明
text	string	'返回列表'	返回按钮文本
visible	boolean	true	是否显示返回按钮
onClick	() => void	-	自定义返回按钮点击回调

PageHeaderTagConfig (标签配置)

属性名	类型	默认值	说明
label	string	必填	标签文本
type	'success' | 'info' | 'warning' | 'danger'	-	标签类型
plain	boolean	false	是否为朴素标签
visible	boolean | (() => boolean)	true	是否显示，支持函数动态计算

PageHeaderDescriptionItem (描述项配置)

属性名	类型	默认值	说明
label	string	必填	描述项标签
value	any	-	描述项值（优先级高于 field）
field	string	-	从 data 对象中取值的字段名
formatter	(value: any, item: PageHeaderDescriptionItem) => string	-	值格式化函数
visible	boolean | (() => boolean)	true	是否显示，支持函数动态计算

---

插槽 (Slots)

插槽名	说明	作用域参数
back	自定义返回按钮区域	-
title	自定义标题区域	-
header-left	自定义标题右侧区域（默认显示标签）	-
header-actions	自定义右侧操作按钮区域	-
header-subtitle	自定义副标题/描述区域（默认显示元数据）	-

---

事件 (Events)

事件名	说明	回调参数
back	点击返回按钮触发	-
action	点击操作按钮触发	(action: ActionButtonConfig, params: any)

---

使用示例

基础用法

<template>
  <FPageHeader title="订单详情" />
</template>

带返回按钮自定义

<template>
  <FPageHeader 
    title="订单详情"
    :back="{ text: '返回订单列表', onClick: handleBack }"
  />
</template>

<script setup lang="ts">
function handleBack() {
  console.log('自定义返回逻辑')
  router.push('/orders')
}
</script>

带标签和操作按钮

<template>
  <FPageHeader 
    title="订单详情"
    :tags="tags"
    :actions="actions"
    @action="handleAction"
  />
</template>

<script setup lang="ts">
const tags = [
  { label: '已支付', type: 'success' },
  { label: '待发货', type: 'warning' }
]

const actions = [
  { key: 'edit', label: '编辑', type: 'primary' },
  { key: 'delete', label: '删除', type: 'danger' }
]

function handleAction(action, params) {
  console.log('点击了', action.key)
}
</script>

带元数据描述

<template>
  <FPageHeader 
    title="订单详情"
    :data="orderData"
    :descriptions="descriptions"
  />
</template>

<script setup lang="ts">
const orderData = {
  orderNo: 'ORD202609150001',
  createTime: '2026-09-15 10:30:00',
  amount: 1299.00,
  status: 'paid'
}

const descriptions = [
  { label: '订单号', field: 'orderNo' },
  { label: '创建时间', field: 'createTime' },
  { 
    label: '订单金额', 
    field: 'amount',
    formatter: (val) => `¥${val.toFixed(2)}`
  },
  {
    label: '状态',
    value: '已支付',
    visible: () => orderData.status === 'paid'
  }
]
</script>

---

最佳实践

1. 返回按钮处理

推荐使用自定义 onClick 回调，而不是依赖浏览器默认的 history.back()：

const backConfig = {
  text: '返回列表',
  onClick: () => {
    // 可以在返回前做一些清理工作
    if (hasUnsavedChanges) {
      ElMessageBox.confirm('有未保存的修改，确定返回吗？')
        .then(() => router.push('/list'))
    } else {
      router.push('/list')
    }
  }
}

2. 动态标签显示

使用函数形式的 visible 实现标签的动态显示：

const tags = [
  { 
    label: '草稿', 
    type: 'info',
    visible: () => orderData.status === 'draft'
  },
  { 
    label: '已完成', 
    type: 'success',
    visible: () => orderData.status === 'completed'
  }
]

3. 描述项格式化

善用 formatter 对数据进行格式化展示：

const descriptions = [
  {
    label: '金额',
    field: 'amount',
    formatter: (val) => `¥${(val / 100).toFixed(2)}`
  },
  {
    label: '时间',
    field: 'createTime',
    formatter: (val) => dayjs(val).format('YYYY-MM-DD HH:mm:ss')
  }
]

---

类型定义

完整类型定义参考 packages/common/src/page-header/src/types.ts