HeadBar — 顶部导航栏

固定在顶部的品牌导航栏。左侧为 Logo + 标题文字，右侧支持通过配置渲染导航按钮、分割线、账户信息和操作按钮；也可以用默认插槽完全自定义。

-File

adminSUPER

基础用法

<template>
  <HeadBar
    title="-File"
    logo-href="https://ksite.xin/"
    :nav-items="navItems"
    :user="currentUser"
    :action-items="actionItems"
    @nav-click="handleNavClick"
    @action-click="handleActionClick"
  />
</template>

<script setup>
import { HeadBar } from 'ui-components/element-plus'
import 'ui-components/element-plus/index.css'

const navItems = [
  { text: '用户端', key: 'user' },
  { text: '系统设置', key: 'settings' },
]

// 账户信息由业务侧传入；不传 user 或 show-user=false 时不显示。
const currentUser = {
  username: 'admin',
  role: 'SUPER',
}

const actionItems = [
  { text: '退出', key: 'logout', variant: 'logout' },
]

const handleNavClick = (item) => {
  if (item.key === 'user') router.push('/user/projects')
  if (item.key === 'settings') router.push('/admin/settings')
}

const handleActionClick = (item) => {
  if (item.key === 'logout') logout()
}
</script>

分割线和按钮配置

分割线有两种方式：

const navItems = [
  { text: '用户端', key: 'user' },
  { type: 'divider' },
  { text: '系统设置', key: 'settings' },
]

或者挂在某个按钮前后：

const navItems = [
  { text: '用户端', key: 'user' },
  { text: '系统设置', key: 'settings', dividerBefore: true },
]

按钮配置支持这些常用字段：

字段	说明
text	按钮文字
key	业务标识，点击事件里用它判断动作
href	传入后渲染为链接
target	链接打开方式
active	当前项高亮
disabled	禁用
hidden	隐藏
class	追加 class
variant	操作按钮样式，'logout' 会使用退出按钮 hover 样式
onClick	可选点击函数；也可以统一监听 nav-click / action-click

账户信息

账户信息应该由业务侧状态传入，例如 Pinia、接口返回或父组件 props：

<HeadBar
  :nav-items="navItems"
  :user="auth.user ? { username: auth.user.username, role: auth.user.role?.toUpperCase() } : null"
  :action-items="actionItems"
/>

不传 user 时不会显示账户区域。已有用户但某个页面想隐藏，可以设置：

<HeadBar :user="auth.user" :show-user="false" />

Slot 用法

HeadBar 有两个 slot：

名称	位置	用途
default	右侧区域	完全接管右侧内容，比如导航、账户、退出按钮
brand	左侧区域	完全接管 Logo + 标题区域

一旦传入默认 slot，navItems、user、actionItems 的默认渲染就不会生效，右侧内容由你自己写。

默认 slot：自定义右侧内容

<template>
  <HeadBar title="-File" logo-href="https://ksite.xin/">
    <div class="kh-nav-space">
      <button class="kh-nav-btn" @click="goUser">用户端</button>
      <button class="kh-nav-btn" @click="goSettings">系统设置</button>

      <span class="kh-nav-divider" />

      <div v-if="user" class="kh-user-info">
        <span class="kh-username">{{ user.username }}</span>
        <span v-if="user.role" class="kh-user-role">{{ user.role }}</span>
      </div>

      <button class="kh-action-btn kh-logout-btn" @click="logout">退出</button>
    </div>
  </HeadBar>
</template>

slot 里可以直接复用内置 class：

class	作用
kh-nav-space	右侧横向容器
kh-nav-btn	导航按钮
kh-nav-divider	竖向分割线
kh-user-info	账户信息容器
kh-username	用户名
kh-user-role	角色标签
kh-action-btn	右侧操作按钮
kh-logout-btn	退出按钮 hover 样式

也可以放 Element Plus 组件，只要套上对应 class：

<HeadBar title="-File">
  <div class="kh-nav-space">
    <el-button text class="kh-nav-btn" @click="goUser">用户端</el-button>
    <span class="kh-nav-divider" />
    <el-button class="kh-action-btn kh-logout-btn" size="small" @click="logout">
      退出
    </el-button>
  </div>
</HeadBar>

brand slot：自定义左侧品牌

<HeadBar>
  <template #brand>
    <a class="kh-logo-wrapper" href="/">
      <img class="kh-logo-icon" :src="logo" alt="K Logo" />
      <h1 class="kh-app-title">-File</h1>
    </a>
  </template>
</HeadBar>

如果只是换 Logo 或标题，优先用 logo、title、logoHref；只有左侧结构也要变时再用 brand slot。

更换 Logo 和标题

不传 logo 时使用内嵌默认 Logo；传入任意图片地址即可替换。title 控制标题文字。

<HeadBar title="Dashboard" :logo="myLogo">
  <button>设置</button>
</HeadBar>

自定义主题色

通过覆盖 CSS 变量即可更换主色（适合多产品复用）：

.my-header :deep(.kh-head-bar) {
  --kh-accent: #10b981;
  --kh-accent-hover-bg: #ecfdf5;
}

Props

名称	类型	默认值	说明
title	String	'-File'	Logo 旁的标题文字
logo	String	''	Logo 图片地址，为空使用内嵌默认 Logo
logoAlt	String	'Logo'	Logo 的 alt 文本
logoHref	String	''	点击 Logo 跳转链接，为空则不可点击
logoTarget	String	'_blank'	Logo 链接的 target
fixed	Boolean	true	是否固定在顶部（position: fixed）
navItems	Array	[]	导航按钮配置
actionItems	Array	[]	右侧操作按钮配置
user	Object | null	null	可选账户信息，如 { username, role }
showUser	Boolean	true	是否显示账户信息
userDivider	Boolean	true	账户信息前是否自动显示分割线

Slots

名称	说明
default	右侧内容区，注入导航按钮、用户信息、操作按钮等
brand	完全覆盖左侧 Logo + 标题区域，用于深度定制

Events

名称	参数	说明
nav-click	(item, event)	点击 navItems 中的按钮
action-click	(item, event)	点击 actionItems 中的按钮

CSS 变量

变量	默认值	说明
--kh-accent	#ef4444	品牌主色
--kh-accent-hover-bg	#fef2f2	悬停背景
--kh-accent-soft-border	#fecaca	悬停描边色
--kh-accent-glow	rgba(239,68,68,.25)	Logo 悬停光晕
--kh-title-color	#1f2937	标题文字色
--kh-text-color	#4b5563	正文文字色
--kh-height	64px	导航栏高度
--kh-padding-x	32px	左右内边距
--kh-bg	#ffffff	背景色
--kh-z-index	1000	层级