# @baukit/navigation 中文文档

规范地址：https://npmcn.com/package/%40baukit/navigation/

版本：0\.18\.3
npm 元数据更新时间：2026-11-07T02:37:06.035Z
中文译文更新时间：2026-11-07T18:50:08.470Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40baukit/navigation
原文对照：https://npmcn.com/package/%40baukit/navigation/?lang=original
项目主页：https://github.com/PatrickKoss/baukit#readme
源码仓库：https://github.com/PatrickKoss/baukit

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

- 包体积（解压后）：361 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：react ^19\.2\.0，react-dom ^19\.2\.0，react-native ^0\.86\.3，@baukit/a11y-core ^0\.18\.3，@baukit/ui-tokens ^0\.18\.3
- 首次发布：2026-10-04T05:03:22.677Z
- 最新版本发布：2026-11-07T02:37:05.659Z
- 近 30 天下载量：8109（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

React Web 和 React Industrial 产品共享相撞导航.

## 安装

```sh
npm install @baukit/navigation
```

也可以使用：`pnpm add @baukit/navigation`、`yarn add @baukit/navigation`、`bun add @baukit/navigation`

## README

# @baukit/导航

React DOM 和 React Natural 的可折叠导航. 产品供应路线, 复制、图标渲染器和符号。 软件包不导入路由器、图标库或 尾风码.

## 条目

-   `@baukit/navigation` 包含 TypeScript 模型, 验证, 活动路由 分辨率、节旋转、减少披露和布局选择。 它已经 不执行运行时间导入 .
-   `@baukit/navigation/web` 包含 `AppNavigation` 财务报告和审定财务报表 `SectionPicker` 为DOM. 它从不进口回放原生,包括 `a11y-core`。 。 。 .
-   `@baukit/navigation/native` 包含用于反应原生和 反应原生网. 使用 `AppNavigation` 作为博览会路由器自定义 `tabBar`。 。 。 .
-   `@baukit/navigation/web.css` 样式 DOM 条目 `--bk-*` 变量.

```tsx
import { AppNavigation, SectionPicker } from '@baukit/navigation/web';
import '@baukit/navigation/web.css';

const progress = {
  id: 'progress',
  label: 'Progress',
  href: '/progress',
  icon: ({ active, size }) => <ChartIcon filled={active} size={size} />,
  children: [
    { id: 'overview', label: 'Overview', href: '/progress' },
    { id: 'history', label: 'History', href: '/progress/history' },
  ],
};

<AppNavigation
  label={copy.primary}
  collapseLabel={copy.collapse}
  expandLabel={copy.expand}
  closeLabel={copy.close}
  items={[progress]}
  pathname={pathname}
  onNavigate={(href) => router.navigate(href)}
  profile={{ label: 'Account', initials: 'AB', href: '/profile' }}
/>;
<SectionPicker closeLabel={copy.close} item={progress} pathname={pathname} onNavigate={navigate} />;
```

声明 `items` 作为 `readonly NavigationItem<NavigationIcon>[]` 图标 参数。 网络和本地条目每个导出 `NavigationIcon`. 制作人 实收 `{ active, size }`。包装器将装饰图标从辅助图标中隐藏 技术。 在 `children` 当他们属于循环.

默认路由匹配比较路径并忽略了查询字符串和散列. 它接受一个精确的路径或被斜线限制的后人. `matches(pathname)` 替换它。 孩子们胜过父母 也是最长的 匹配的href在儿童中获胜。 通过一个路由别名的自定义匹配器, 搜索参数或散列。 缺少的匹配选择什么. `nextSectionHref` 返回丢失的匹配的第一个孩子,并在最后一个孩子上包装.

在 1024 像素以下, 组件会使标签上方的图标成为下方栏 . 它支持六个主要项目外加一个可选配置. 320 CSS 像素,网络 栏中有310个像素,每边有5个像素。 七个44像素目标 需要308像素。 更长的标签在按钮内椭圆; 可用的标签 保留全文。 在1024像素时,它制造出280像素铁路. 折叠减少 它到76像素。 活动区域开始打开. 点击崩溃的披露 拓宽铁路并打开该段.

`collapsed`, (中文(简体) ), `defaultCollapsed`,以及 `onCollapsedChange` 控制的支助和 不受控制的状态。 在产品偏好中坚持控制值 存储。 供应 `collapseLabel`, (中文(简体) ), `expandLabel`,以及 `label` 从产品目录。 网络和本土 `AppNavigation` 财务报告和审定财务报表 `SectionPicker` 还要求 `closeLabel` 用于可见和可访问菜单 关闭控制。 组件没有英语默认值.

Web使用真实的锚. `onNavigate` 仅截取未修改的主点击. 没有它,浏览器跟随href. `renderLink(props)` 能够返回路由器 链接. 在KeyDown、Click和KeyDown上转发所有提供的道具,特别是ref、ref ARIA属性. 在浏览器中保留已修改的点击. TanStack路由器产品 能够映射 `href` 改为 `to`,或使用 `onNavigate` 他们的路由器实例.

设定 `replace` 打开 `SectionPicker` 以替换当前历史条目 区域被选中。 默认为 `false`。现有的回调保留其 除非要求替换。 网络接收 `onNavigate(href, event, { replace: true })`; 当地接收 `onNavigate(href, { replace: true })`。产品适配器必须应用以下选项:

```tsx
// Web with React Router
<SectionPicker
  closeLabel={copy.close}
  item={progress}
  pathname={pathname}
  replace
  onNavigate={(href, _event, options) => navigate(href, { replace: options?.replace ?? false })}
/>;

// Native with Expo Router, alongside the required item, labels, pathname and theme
const onNavigate = (href: string, options?: { readonly replace: boolean }) => {
  if (options?.replace === true) router.replace(href);
  else router.navigate(href);
};
```

网页 `renderLink` 接收 `replace: true` 用于替换时的拾取器链接 请求。 否则会省去字段,所以现有的渲染器会保留其 道具来. 路由器Link可以应用. 在将道具传播到 DOM 主锚之前删除它 . 默认主锚渲染器将其取出. 修改后点击保留普通浏览器 行为.

一个配置文件接受其中之一 `href` 或无空 `menu`。菜单条目有独特的 标识、标签和任何一种 `href` 或同步 `onSelect`设置 `tone: 'danger'` 破坏行动。 网络使用 `color.status.danger`; 本地用户 `NavigationTheme.danger` 对象 `background`。检查该对在 4.5:1 在这两个主题中。 本地在菜单关闭后引用回调, 使用 iOS `onDismiss` 或Android/web上未激活的Modal去除后的第一个帧. 接受链接条目 `matches(pathname)`在菜单中只选择最特定的匹配路径。 一个产品拥有自动同步 动作出错。 在其中启动同步签名 `onSelect` ,并在 产品. `imageUrl` 在图像失败后进行首字母缩写. `renderAvatar({ active, size })` 用产品替换图像或首字母 网上和原生地上的glyph或帧. 它接收路由选择状态和 28个单位的外形尺寸。 返回装饰内容. 包装器隐藏它 辅助技术;配置标签和字幕仍取出按钮名. Web自定义外观没有默认的背景或循环框架. 档案保存在酒吧和铁路下方最后.

活叶使用有口音图标和粗体标签的哑口音背景. 在拓宽的栏杆上,活动孩子的父母有口音文字和图标 没有填满。 活动图标渲染器接收 `active: true` 两行. 在酒吧和倒塌的铁道里,父母得到填充. 网络行曝光 `data-active="page"` 或者说 `data-active="ancestor"`; 不活动行省略属性. 覆盖 `--bk-navigation-active-background`, (中文(简体) ), `--bk-navigation-active-text` 财务报告和审定财务报表 `--bk-navigation-ancestor-text` 打开 `.bk-navigation` 以匹配产品调色板. 默认背景将14%的口音混合到导航背景上.

## 原生代号与外壳

供应a `NavigationTheme` 从产品编译出ui-tokens。 不使用 导航组件中的原始品牌颜色.

| 导航 主题字段 | 语义符号 |
| --- | --- |
| 背景情况 | 颜色、背景、主要或表面 |
| 文本 | 颜色. 文本. prime |
| 危险 | 颜色、状态、危险 |
| 哑巴 | 颜色. 文本. muded |
| 活动背景 | 由 ui-tokens 制取的相色( 角, 背景, 0.14) |
| 活动文本 | 颜色.背景.accent |
| 祖先图文 | 颜色.背景.accent |
| 边框 | 颜色、 边框、 主要 |
| 焦点 | 颜色 焦点 环 |
| 间距 | 空间。小 |
| 半径 | 半径 小数 |

使用测试的对比对 `activeText` 和哑巴 `activeBackground`。 。 。 . 检查 `ancestorText` 反对 `background` 我也一样. `blendColors` 财务报告和审定财务报表 `contrastRatio` 从 ui-tokens 检查这两个主题中的这些对。 土著 变化是立即发生的。 网络宽度转换只在运动减少后运行 解决,并且只有允许动议.

设置 Expo 标签 `tabBarPosition` 改为 `left` 铁路模式和 `bottom` 否则. 将安全区域设置和路径名传递到自定义标签栏 。 构成部分 占用本地的布局空间。 DOM 组件是固定的; 保留其宽度 或内容外壳中的底高. `NAVIGATION_DIMENSIONS` 出口 数字,包括44个单元网络和iOS目标以及48个dp Android目标. 匹配外壳的比值和宽度向铁路的过渡,或保留 宽度扩大。 仅允许转换 `data-motion="standard"`。 。 。 . 包含底部安全区域设置 。 取取器属于里面 当前章节的内容。 DOM 拾取器测量其下方的空间 触发和上方的紧凑底条。 里面有很长的部分 空间。 它在视图、内容布局或滚动时更新限制 位置变化.

在本地端, 配置菜单和节取器会以透明的方式打开 在边缘到边缘的系统栏下画出. `AppNavigation` 以该模式 `insets` 加上8个单位。 传出同样的 `insets` 对当地人 `SectionPicker`。 。 。 . 不设套,两个都保持8个单元的固定.

对于紧凑的本地内容, `useNavigationBarHeight(bottomInset, theme)` 储备金 空格,使用当前字体缩放和栏的打字和间距。 通过 同主题 `AppNavigation` 当你定制它。 默认高度为 75 dp 在底部设置之前. `getNavigationBarHeight(fontScale, bottomInset, metrics)` 提供了相同的计算,没有钩子。 它的可选衡量标准是: `spacing`, (中文(简体) ), `fontSize` 财务报告和审定财务报表 `lineHeight`。 。 。 . `NAVIGATION_DIMENSIONS.nativeBar` 默认本地 \* 高度; `bar` 仍为64像素 DOM高地.

在产品中保持路由头重点. 使用 `createRouteFocusController` 从 `@baukit/a11y-core/web` dOM 路由变更, 和产品屏幕过渡适配器 在本地。 导航不知道 哪个方向已经挂起.

DOM 样式表使用稳定 `bk-navigation*` 课程和 `data-layout`, (中文(简体) ), `data-collapsed`, (中文(简体) ), `data-active`, (中文(简体) ), `data-open`,以及 `data-motion` 属性. 产品可以在Plain CSS或Tailwind中覆盖这些选择器.

## 核查

`pnpm test` 运行模型和 DOM 测试, 使用 React 本地测试进行本地测试 图书馆和反应原生杰斯特预设,并检查已包装的出口. 博览 这些测试不需要. `pnpm test:browser` 通过 Playwright 运行 Chromium和WebKit的维特值为320、1023和1024像素,短而正常 高处. 它检查几何,44像素目标,浏览器警告和轴.

配置文件可以提供 `subtitle` 名称或同步状态。 铁路扩建和 配置菜单在标签下显示 。 配置按钮包含两行 在其无障碍标签中,包括在倒塌和紧凑的导航中.

土著 `NavigationTheme.typography` 可以设置 `fontFamily`, (中文(简体) ), `activeFontFamily`, (中文(简体) ), `fontSize`, (中文(简体) ), `barFontSize`, (中文(简体) ), `subtitleFontSize`, (中文(简体) ), `fontWeight`, (中文(简体) ), `activeFontWeight`, (中文(简体) ), `lineHeight` 财务报告和审定财务报表 `letterSpacing`选中条目使用 `activeFontFamily` 当设定和 `fontFamily` 否则。 当字体传送一个文件时设定它, 如 `IBMPlexSans_600SemiBold` 从博览会Google字体,所以Android使一个真实 半粗体 半粗体 半粗体 大小和行高使用 React 本地单位. 输入字段 保留默认大小和重量。 字体家族也适用于菜单条目, 首字母和节取子,因为网络导航继承了它的CSS字体家族.

## 品牌和附属档位

过 `renderBrand(state)` 用于文字标记或标志,以及 `renderAccessory(state)` 用于状态或产品控制。 两个都收到 `{ layout: 'bar' | 'rail', collapsed }`。 。 。 . 在倒塌的铁路上归还一个小标志和紧凑状态. 可用供应 标识和控件的名称。 Slot内容保留了自己的语义.

铁路将两个槽都置于控制之上. 紧凑的栏杆把它们放在上面 堆叠图标和标签目标。 当槽行的内容确实存在时, Web 将该槽行包裹 不合时宜。 本地测量槽行并包含在 `getNavigationBarHeight` 结束 `NavigationBarMetrics.slotHeight`。 。 。 . `useNavigationBarHeight(bottomInset, theme, slotHeight)` 接受同样的高度.

在两个平台上, `onBarHeightChange(height)` 报告完整的紧凑栏 高度,包括槽口和安全区域. 存储在内容外壳中以保留 底层空间。 更改观察员的高度,包括字体 变化。 原生报告高度从相同的计算到大小 那个酒吧 当槽可以改变大小时使用此回调 .

## 常见问题

### @baukit/navigation 是什么？

React Web 和 React Industrial 产品共享相撞导航\.

### 如何安装 @baukit/navigation？

在项目目录运行 npm install @baukit/navigation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.2\.0）、@baukit/a11y-core（^0\.18\.3）、@baukit/ui-tokens（^0\.18\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @baukit/navigation 支持 TypeScript 吗？

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

### @baukit/navigation 支持 ESM 还是 CommonJS？

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

### @baukit/navigation 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @baukit/navigation 可以商用吗？

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

### @baukit/navigation 的下载量有多少？

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

### @baukit/navigation 还在维护吗？

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