# @avament-pub/navbar-ui 中文文档

规范地址：https://npmcn.com/package/%40avament-pub/navbar-ui/

版本：0\.6\.5
npm 元数据更新时间：2026-10-29T22:34:51.200Z
中文译文更新时间：2026-11-07T07:38:46.021Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40avament-pub/navbar-ui
原文对照：https://npmcn.com/package/%40avament-pub/navbar-ui/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：clsx \>=2\.0\.0，axios \>=1\.6\.0，react \>=18，i18next \>=23\.0\.0，date-fns \>=3\.0\.0，react-dom \>=18，lucide-react \>=0\.400\.0，react-i18next \>=14\.0\.0，tailwind-merge \>=2\.0\.0，react-day-picker \>=9\.0\.0，@avament-pub/select \>=0\.3\.0，@radix-ui/react-slot \>=1\.2\.0，@radix-ui/react-label \>=2\.1\.0，@tanstack/react-query \>=5\.0\.0，@radix-ui/react-dialog \>=1\.1\.0，@radix-ui/react-select \>=2\.2\.0，@radix-ui/react-popover \>=1\.1\.0，@radix-ui/react-checkbox \>=1\.1\.0，class-variance-authority \>=0\.7\.0，@avament-pub/color-picker \>=0\.1\.0，@avament-pub/image-editor \>=0\.1\.0
- 首次发布：2026-10-03T06:41:27.747Z
- 最新版本发布：2026-10-29T22:34:50.984Z
- 近 30 天下载量：2369（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

自成一体的 Avament navbar UI 用于 react / Next.js apps (包括嵌入式支持创建报告)

## 安装

```sh
npm install @avament-pub/navbar-ui
```

也可以使用：`pnpm add @avament-pub/navbar-ui`、`yarn add @avament-pub/navbar-ui`、`bun add @avament-pub/navbar-ui`

## README

# `@avament-pub/navbar-ui`

自成一体 **Avament 导航** 用于 react / Next.js apps - 否 `@/` 进口,没有商店,没有API电话。 主机提供标签,路线,项目数据和主题CSS.

|  |  |
| --- | --- |
| **软件包** | [`@avament-pub/navbar-ui`](https://www.npmjs.com/package/@avament-pub/navbar-ui) |
| **反应** | 第18条(同级) |
| **依赖性** | [`lucide-react`](https://www.npmjs.com/package/lucide-react) |
| **许可证** | 麻省理工学院 |

* * *

## 目录

1.  [安装](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-1-install)
2.  [快开始](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-2-quick-start)
3.  [布局结构](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-3-layout-structure)
4.  [地物标志](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-4-feature-flags)
5.  [项目拾取模式](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-5-project-picker-modes)
6.  [标记](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-6-logo)
7.  [天气](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-7-weather)
8.  [朗/ 主题](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-8-lang--theme)
9.  [主机约束清单](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-9-host-binding-checklist)
10.  [主机插槽](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-10-host-slots)
11.  [拉特](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-11-rtl)
12.  [主题 / CSS](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-12-theming--css)
13.  [出口](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-13-exports)

* * *

## 1\. 安装

```bash
npm install @avament-pub/navbar-ui
```

```bash
yarn add @avament-pub/navbar-ui
pnpm add @avament-pub/navbar-ui
```

**所需资源**

-   反应 18+ / 反应 DOM 18+
-   Next.js App路由器中的客户端组件(`"use client"` 包含在捆绑中)

可选( Next.js App 路由器) :

```ts
transpilePackages: ["@avament-pub/navbar-ui"];
```

* * *

## 2\. 快速启动

```tsx
import { Navbar } from "@avament-pub/navbar-ui";
import Link from "next/link";

<Navbar
  pathname={pathname}
  dir="ltr"
  labels={{ selectAProject: "Select a project", /* … */ }}
  routes={{
    home: "https://avament.com/home",
    settings: "/settings",
    support: "https://support.avament.com",
  }}
  logo={{ src: "/logos/main.svg", href: "https://avament.com/home" }}
  projectPicker={{
    mode: "interactive",
    selectedProjectId,
    selectedProjectName,
    projects,
    onSelect: handleProjectSelect,
  }}
  LinkComponent={Link}
/>
```

* * *

## 3\. 布局结构

主要场地和分场地共享 **一个条形结构**. 软件包拥有放置——只接收有线道具.

**桌面( 固定顺序) :**

| 左边 | 对 |
| --- | --- |
| 导航动作 ^ 选择在拾取器旁 ^ 项目拾取器 | · 语言 `trailingSlot` • 妇女 **标志** |

天气让 **居中** 在栏(桌面) `features.weather` 在主家布局上启用.

**导航动作** 取决于 `layout` +页:

| 模式 | 左侧图标 |
| --- | --- |
| 家庭主户`layout="default"`, (中文(简体) ), `/home`(中文(简体) ) | 支持 ・ 设置 |
| 主要内页 | 回到 \\ 设置 \\ 家 |
| 分站点(`layout="submodule"`(中文(简体) ) | 回到 \\ 设置 \\ 家 |
| 子模块 + `features.support: true` | 后 支持 / 设置 / 家 |
| 离家 + `supportCreate` 或者说 `onSupportClick` | 支持打开 in-app 创建对话框; 家保存 `routes.support` 链接 |

**可选项目选择器** (左组,取取取者前:

1.  `moduleLabel` ——避孕药标签(如:. `"AVAMENT-Intern"`(中文(简体) )
2.  `context` - 外部/内部分块控制
3.  `projectPickerLeadingSlot` 任何自定义用户界面

```tsx
// Main website (home)
<Navbar
  pathname="/home"
  isHomeLayout
  features={{ weather: true, support: true }}
  projectPicker={{ mode: "interactive", … }}
  weather={forecast}
  logo={logo}
  /* … */
/>

// Sub-site (ticket, check, …)
<Navbar
  layout="submodule"
  pathname={pathname}
  moduleLabel="AVAMENT-Intern"
  context={{
    value: visibility,
    onChange: setVisibility,
    options: [
      { value: "external", label: "External" },
      { value: "internal", label: "Internal" },
    ],
  }}
  projectPicker={{ mode: "interactive", … }}
  features={{ langTheme: true }}
  langTheme={{ language, onLanguageChange, theme, onThemeChange, isDarkMode }}
  trailingSlot={<CreateTicketButton />}
  onBack={() => {
    if (pathname === "/") window.location.href = routes.landing ?? "https://avament.com";
    else router.back();
  }}
  /* …labels, routes, logo, LinkComponent */
/>
```

**`trailingSlot`数字 :** 标识前只应用动作(创建批次,创建票).

使用 `contextSlot` 或者说 `projectPickerLeadingSlot` 仅当内置选项不够时.

* * *

## 4\. 地物标志

| Prop | 默认 | 效果 |
| --- | --- | --- |
| `features.weather` | `false` | 中心天气带(桌面、家庭布局) |
| `features.support` | 主家:是;子模块:否(设置) `true` 显示) | 导航行动中的头像支持链接 |
| `features.supportCreate` | `false` | 离家: 嵌入式支持创建对话框( API from) `NEXT_PUBLIC_BASE_URL` 编号 : `NEXT_PUBLIC_API_URL`, SSO cookie; 需要重新查询 + i18n) |
| `supportCreate` | —— 说 | 可选覆盖( N)`createDialogTitle`, (中文(简体) ), `onOpenChange`, ) 当 `features.supportCreate` 开始 |
| `onSupportClick` | —— 说 | 离家:手动耳机处理器(覆盖) `supportCreate` 当两个设定时单击) |
| `features.langTheme` | `false` | 语言+主题拾取器(桌面) |
| `features.topicPill` | `false` | 仅读主题药丸 |
| `features.actions` | `true` | 设置 / home/ back 图标 |

* * *

## 5\. 项目取取器模式

| 模式 | 用户 |
| --- | --- |
| `interactive` | 以可点击的切夫龙下拉 |
| `readonly` | 只有标签——没有切夫龙,不能点击 |
| `hidden` | 未执行 |

```tsx
projectPicker={{
  mode: "readonly",
  selectedProjectId: "uuid",
  selectedProjectName: "Project Alpha",
}}
```

* * *

## 6\. 标识

静态 :

```tsx
logo={{ src: "/logos/check.svg", href: "https://check.avament.com", alt: "Check" }}
```

动态 :

```tsx
logo={{
  resolve: ({ pathname }) => ({
    src: pathname.startsWith("/check") ? "/logos/check.svg" : "/logos/main.svg",
    href: pathname === "/home" ? "https://avament.com/landing" : "https://avament.com/home",
  }),
}}
```

* * *

## 7\. 天气

主机获取数据; UI 只制作 :

```tsx
features={{ weather: true }}
weather={{
  days: forecast.days,
  locationLabel: forecast.locationLabel,
  timezone: forecast.timezone,
  locale: "de",
}}
```

* * *

## 8\. 朗/主题

受控拾取器——主机持续变化:

```tsx
features={{ langTheme: true }}
langTheme={{
  language: "de",
  onLanguageChange: (lang) => updateSettings({ language: lang }),
  theme: "dark",
  onThemeChange: (theme) => updateSettings({ theme }),
  isDarkMode: true,
}}
```

* * *

## 9\. 主机约束清单

1.  过 `labels` 从您的 i18n (`t()` • 目标)。 见 `REQUIRED_NAVBAR_LABEL_KEYS` 编号 : `OPTIONAL_NAVBAR_LABEL_KEYS` 出口.
2.  线 `projectPicker.onSelect` 您的认证/ 工程切换流 .
3.  过 `navigationBlocked` 当未保存/进口/编辑的警卫活动时.
4.  提供 `LinkComponent` (续) `Link`)或使用 `onNavigate` 还有你的路由器.
5.  执行 `onBack` 对后扣行为.
6.  包含主题 CSS( 见 [主题 / CSS](https://npmcn.com/package/%40avament-pub/navbar-ui/#readme-10-theming--css)) (中文(简体) ).

* * *

## 10\. 主机档

| Prop | 使用 |
| --- | --- |
| `moduleLabel` | 在项目拾取器旁建有避孕药 |
| `context` | 外部/内部分区控制 |
| `projectPickerLeadingSlot` | 自定义工程拾取器旁的 UI |
| `trailingSlot` | 标识前的 App 动作( 创造票等) |

* * *

## 11\. 拉特里语

过 `dir="rtl"` 当应用语言是阿拉伯语(或任何RTL语言)时:

```tsx
<Navbar dir={locale === "ar" ? "rtl" : "ltr"} /* … */ />
```

软件包自动映射了栏:

-   **左组** (动作+取出项目) 视觉 **对**
-   **右组** (朗语/主题+标志) 视觉 **左边**
-   **天气** 保持中心状态
-   降水量与触发器一致 **内置启动** 边缘
-   在 RTL 中后箭头图标翻转

项目拾取器文本和菜单继承 `dir` 从导航站。 天气温度不变 `dir="ltr"` 数字可读性.

* * *

## 12\. 主题/CSS

此软件包使用 **提供 Tailwind 主题公用事业**。您的应用程序必须定义 :

-   `bg-theme`, (中文(简体) ), `border-theme`, (中文(简体) ), `surface-theme`, (中文(简体) ), `text-theme-primary`
-   `hover:bg-input-theme`, (中文(简体) ), `bg-theme-surface`, (中文(简体) ), `border-theme-border`
-   `--input-border-color` CSS 变量
-   `animate-project-picker-pulse` 键框动画
-   `shadow-glass`, (中文(简体) ), `shadow-glass-dark` (可选,指降水/人流)

没有这些类,导航器会变形 但看起来没有风格.

**支持创建对话框** (单位:千美元)`features.supportCreate`: 主题 CSS 导入自 `@avament-pub/navbar-ui`。可选的手动导入 : `@avament-pub/navbar-ui/styles.css`。主机应用程序应当定义 `--surface-color`, (中文(简体) ), `--text-primary-color`, (中文(简体) ), `--input-border-color`,以及相关的令牌(见协议/ticket应用).

* * *

## 13\. 出口

```ts
// Components
export { Navbar, NavDropdown, WeatherForecastWidget, ProjectPicker, LangPicker, ThemePicker, NavbarSegmentedControl };

// Constants
export { NAV_ICON_SIZE, navIconButtonClass, navIconButtonClassNoMargin, DEFAULT_LANGUAGE_OPTIONS };
export { REQUIRED_NAVBAR_LABEL_KEYS, OPTIONAL_NAVBAR_LABEL_KEYS };

// Types
export type {
  NavbarProps,
  NavbarLayout,
  NavbarContextControl,
  NavbarContextOption,
  NavbarFeatures,
  NavbarRoutes,
  NavbarLabels,
  NavbarLogoConfig,
  NavbarProject,
  NavbarProjectPicker,
  NavbarWeather,
  NavbarWeatherDay,
  NavbarLangTheme,
  NavbarTheme,
  NavbarLinkComponent,
  ProjectPickerMode,
};
```

## 常见问题

### @avament-pub/navbar-ui 是什么？

自成一体的 Avament navbar UI 用于 react / Next\.js apps \(包括嵌入式支持创建报告\)

### 如何安装 @avament-pub/navbar-ui？

在项目目录运行 npm install @avament-pub/navbar-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：clsx（\>=2\.0\.0）、axios（\>=1\.6\.0）、react（\>=18）、i18next（\>=23\.0\.0）、date-fns（\>=3\.0\.0）、react-dom（\>=18）、lucide-react（\>=0\.400\.0）、react-i18next（\>=14\.0\.0）、tailwind-merge（\>=2\.0\.0）、react-day-picker（\>=9\.0\.0）、@avament-pub/select（\>=0\.3\.0）、@radix-ui/react-slot（\>=1\.2\.0）、@radix-ui/react-label（\>=2\.1\.0）、@tanstack/react-query（\>=5\.0\.0）、@radix-ui/react-dialog（\>=1\.1\.0）、@radix-ui/react-select（\>=2\.2\.0）、@radix-ui/react-popover（\>=1\.1\.0）、@radix-ui/react-checkbox（\>=1\.1\.0）、class-variance-authority（\>=0\.7\.0）、@avament-pub/color-picker（\>=0\.1\.0）、@avament-pub/image-editor（\>=0\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @avament-pub/navbar-ui 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @avament-pub/navbar-ui 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @avament-pub/navbar-ui 可以商用吗？

@avament-pub/navbar-ui 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @avament-pub/navbar-ui 的下载量有多少？

根据 npm 官方下载统计，@avament-pub/navbar-ui 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,369 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @avament-pub/navbar-ui 还在维护吗？

最新版本 0\.6\.5 发布于 2026/10/30（8 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/10/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。