# HeadNav

顶部导航栏组件，提供 logo、菜单、用户信息等标准顶栏结构，支持深色/浅色主题和多级菜单。

## 适用场景

- 应用系统的顶部主导航栏
- 需要展示应用 logo、导航菜单和用户信息
- 支持多级菜单导航（最多三级）

## Props

### HeadNav Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| logo | `ReactNode` | `-` | 否 | logo 节点，通常传入 `<NavLogo />` 或 `<ErpLogo />` |
| avatar | `string` | `-` | 否 | 用户头像 url |
| userInfo | `ReactNode` | `-` | 否 | 用户概要，一般为姓名（工号） |
| userMenu | `HeadNavMenuItemObject[]` | `-` | 否 | 用户下拉菜单 |
| userExtra | `ReactNode` | `-` | 否 | 用户旁附加内容（预留，暂无设计细则） |
| reverseColor | `boolean` | `true` | 否 | 是否使用反色，适用于深色背景 |
| menu | `HeadNavMenuItemObject[]` | `-` | 否 | 主导航菜单列表 |
| menuSelectedIds | `MenuItemId[]` | `-` | 否 | 菜单已选中 id 列表（控制值），使用此 prop 时须保持 menuItem.selected 为 undefined |
| menuDefaultSelectedIds | `MenuItemId[]` | `-` | 否 | 菜单已选中 id 列表的默认值 |
| onChangeSelectedIds | `(selectedIds: MenuItemId[]) => void` | `-` | 否 | selectedIds 变化时的回调（select/deselect 均会触发） |

### HeadNavMenuItemObject Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| id | `MenuItemId` | `-` | 否 | 唯一标识 |
| label | `ReactNode` | `-` | 是 | 显示内容 |
| disabled | `boolean` | `-` | 否 | 是否禁用 |
| icon | `SvgFC` | `-` | 否 | 图标，仅第一层菜单支持 |
| href | `string` | `-` | 否 | 链接地址，label 将包裹在 `<a>` 内 |
| target | `string` | `-` | 否 | `<a>` 的 target |
| title | `string` | `-` | 否 | 鼠标悬停 title 提示 |
| onClick | `MouseEventHandler<Element>` | `-` | 否 | 点击回调 |
| selected | `boolean` | `-` | 否 | 是否选中 |
| children | `MenuItemObject[]` | `-` | 否 | 子菜单项 |

### NavLogo Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| src | `string` | `-` | 否 | logo 图片地址，须为 viewBox height 40 的 svg 资源 |
| href | `string` | `-` | 否 | logo 跳转链接 |
| subheadSrc | `string` | `-` | 否 | 副标题图片地址，须为 viewBox height 24 的 svg 资源 |
| subheadHref | `string` | `-` | 否 | 副标题跳转链接；undefined 使用 logo 链接，null 无跳转，string 为自定义链接 |
| subheadDivider | `boolean` | `false` | 否 | 副标题是否带分割线 |
| reverseColor | `boolean` | `true` | 否 | 是否使用反色 |

### ErpLogo Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| src | `string` | `-` | 否 | logo 图片地址，须为 viewBox height 40 的 svg 资源 |
| href | `string` | `-` | 否 | logo 跳转链接 |
| subheadSrc | `string` | `-` | 否 | 副标题图片地址，须为 viewBox height 24 的 svg 资源 |
| subheadHref | `string` | `-` | 否 | 副标题跳转链接 |
| subheadDivider | `boolean` | `-` | 否 | 副标题是否带分割线 |
| reverseColor | `boolean` | `true` | 否 | 是否使用反色 |

## 典型用法

### 基础导航栏（深色）

```tsx
import { HeadNav, NavLogo } from '@befe/brick-comp-head-nav'
import subheadSrc from './subhead.svg'
import avatar from './avatar.jpeg'

const menu = [
    { id: '1', label: '单据', href: '/bills' },
    {
        id: '2',
        label: '工作台',
        children: [
            { id: '21', label: '工作台1', href: '/workbench/1' },
            { id: '22', label: '工作台2' },
        ],
    },
]

const userMenu = [
    { id: 'profile', label: '个人中心', onClick: () => {} },
    { id: 'logout', label: '退出', onClick: () => {} },
]

<HeadNav
    menu={menu}
    logo={<NavLogo subheadSrc={subheadSrc} />}
    userInfo={'张三（B12345）'}
    userMenu={userMenu}
    avatar={avatar}
/>
```

### 浅色主题

```tsx
import subheadSrc from './subhead-light.svg'

<div className={'head-nav-container'}>  {/* 需自行添加 border-bottom */}
    <HeadNav
        menu={menu}
        logo={<NavLogo reverseColor={false} subheadSrc={subheadSrc} />}
        userInfo={'张三（B12345）'}
        reverseColor={false}
        avatar={avatar}
    />
</div>
```

### 自定义主 logo

```tsx
import logoSrc from './custom-logo.svg'

<NavLogo src={logoSrc} reverseColor={false} />
```

### ERP 子系统使用 ErpLogo

```tsx
import { ErpLogo } from '@befe/brick-comp-head-nav'

<HeadNav
    logo={<ErpLogo subheadSrc={subheadSrc} />}
    menu={menu}
    userInfo={'张三（B12345）'}
/>
```

## 注意事项

- 破坏性变更（2023-06）：`NavLogo` 废弃 props `url`、`subhead`、`subheadUrl`、`originColor`，改为 `src`、`href`、`subheadSrc`、`subheadHref`、`reverseColor`
- 破坏性变更（2021）：`userInfoPrimary`、`userInfoSecondary` 合并为 `userInfo`（只有一行）
- `logo` 和 `subhead` 图片须为 SVG 格式，分别要求 viewBox height 为 40 和 24，不符合规范的 SVG 可能导致显示错位
- 浅色主题需要在容器上自行添加 `border-bottom`，因为 HeadNav 宽度有最大限制，border 需由容器来提供
- 不传 `avatar` 时头像位置是一个空占位圆：反色 nav 上其浅色底与 nav 底色有对比、直接可见；浅色 nav 上会额外加一圈占位虚线框来体现「圆」，传了 `avatar` 则没有这圈虚线
- `userExtra` 内的自定义节点仅做垂直近似居中（与几何中心差 1~2px），需要精确对齐请自行把节点撑到 nav 高度
- 使用 `menuSelectedIds` 控制选中状态时，须保持菜单项的 `selected` 属性为 `undefined`，两者不可同时使用