# @capawesome/capacitor-navigation-bar 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/

版本：8\.0\.2
npm 元数据更新时间：2026-09-02T08:22:55.676Z
中文译文更新时间：2026-11-09T08:01:21.119Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-navigation-bar
原文对照：https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/navigation-bar/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

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

- 包体积（解压后）：72.4 kB，36 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-05-27T08:52:18.334Z
- 最新版本发布：2026-09-02T08:22:55.260Z
- 近 30 天下载量：3795（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

电容插件可以设置Android上导航栏的背景颜色和按钮样式.

## 安装

```sh
npm install @capawesome/capacitor-navigation-bar
```

也可以使用：`pnpm add @capawesome/capacitor-navigation-bar`、`yarn add @capawesome/capacitor-navigation-bar`、`bun add @capawesome/capacitor-navigation-bar`

## README

# 电容导航栏插件

用于设置导航栏背景颜色和按钮样式的电容插件.

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

Capacitor导航条插件为自定义Capacitor应用中的Android导航条提供了最完整的解决方案之一. 以下是一些关键特征:

-   🎨 **背景颜色**: 将导航栏背景设置为任何十六进制颜色或完全透明.
-   🔘 **按钮样式**: 选择暗或淡导航条按钮,或跟随系统外观.
-   ➖ **分隔符颜色**:自定义Android 9+上的导航条分色.
-   👁️ **可见度**:按要求隐藏或显示导航栏.
-   ⚙️ **配置**:通过Capacitor配置在应用启动时应用默认值.
-   🤝 **兼容性**: 与 [Android 暗模式支持](https://capawesome.io/docs/sdks/capacitor/android-dark-mode-support/), (中文(简体) ), [Android 边缘到边缘支持](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/) 财务报告和审定财务报表 [家庭指标](https://capawesome.io/docs/sdks/capacitor/home-indicator/) 插件 .
-   🔁 **最新数据**:总是支持最新的Capacitor版本.
-   ⭐️ **支助**: 卡帕韦斯克团队优先支持.
-   ✨ **手工业**:由地而上地而上以关怀和专长而来,不是要塞或AI生成.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

导航栏插件一般用于使Android系统导航栏与应用程序的设计相融合,例如:

-   **品牌主题**: 将导航栏背景设定为您的品牌颜色, 这样它就能与您的应用程序的其余部分匹配 .
-   **暗模式支持**:当用户在光和暗的主题之间切换时切换导航栏颜色和按钮样式.
-   **记忆中的经历**:隐藏用于视频或游戏等全屏内容的导航栏,然后再次显示.
-   **一致的应用启动**:在应用启动时通过Capacitor配置应用默认颜色,分色,和按钮样式.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |

## 指南

-   [边缘到边缘和安全区域:完整指南](https://capawesome.io/blog/capacitor-edge-to-edge-and-safe-areas-guide/)

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-navigation-bar` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行下列命令来安装插件:

```bash
npm install @capawesome/capacitor-navigation-bar
npx cap sync
```

## 配置

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`color`** | `string` | 要设置为导航栏背景颜色的十六进制颜色 。 使用 `'transparent'` 使导航栏透明。 只能从Android上找到. | 8.0.0 (单位:千美元) |
| **`dividerColor`** | `string` | 要设置为导航条分隔符的十六进制颜色 。 使用 `'transparent'` 来隐藏分裂者。 仅在Android(API级28+)上可用. | 8.0.0 (单位:千美元) |
| **`style`** | `'DARK' | 'LIGHT' | 'DEFAULT'` | 导航条按钮的样式. 只能从Android上找到. | 8.0.0 (单位:千美元) |

### 实例

单位 `capacitor.config.json`数字 :

```json
{
  "plugins": {
    "NavigationBar": {
      "color": "#ffffff",
      "dividerColor": "#d9d9d9",
      "style": "LIGHT"
    }
  }
}
```

单位 `capacitor.config.ts`数字 :

```ts
/// <reference types="@capawesome/capacitor-navigation-bar" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    NavigationBar: {
      color: "#ffffff",
      dividerColor: "#d9d9d9",
      style: "LIGHT",
    },
  },
};

export default config;
```

## 使用量

以下例子显示如何设置导航条颜色和按钮样式,读取当前颜色和样式,并隐藏并显示导航条.

### 设置导航栏颜色

将导航栏的背景颜色设定为任何十六进制颜色,或通过 `'transparent'` 使其完全透明。 仅在Android上可用:

```typescript
import { NavigationBar } from '@capawesome/capacitor-navigation-bar';

const setColor = async () => {
  await NavigationBar.setColor({ color: '#ffffff' });
};
```

### 设置按钮样式

选择暗或淡导航栏按钮,或使用 `Style.Default` 以跟踪当前设备的外观。 仅在Android上可用:

```typescript
import { NavigationBar, Style } from '@capawesome/capacitor-navigation-bar';

const setStyle = async () => {
  await NavigationBar.setStyle({ style: Style.Light });
};
```

### 读取当前颜色和样式

获取导航栏当前背景颜色和按钮样式。 仅在Android上可用:

```typescript
import { NavigationBar } from '@capawesome/capacitor-navigation-bar';

const getColor = async () => {
  const { color } = await NavigationBar.getColor();
  return color;
};

const getStyle = async () => {
  const { style } = await NavigationBar.getStyle();
  return style;
};
```

### 隐藏并显示导航栏

按要求隐藏导航栏,例如全屏内容,然后再次显示。 仅在Android上可用:

```typescript
import { NavigationBar } from '@capawesome/capacitor-navigation-bar';

const hide = async () => {
  await NavigationBar.hide();
};

const show = async () => {
  await NavigationBar.show();
};
```

## API 密码

-   [`getColor()`](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-getcolor)
-   [`getStyle()`](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-getstyle)
-   [`hide()`](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-hide)
-   [`setColor(...)`](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-setcolor)
-   [`setStyle(...)`](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-setstyle)
-   [`show()`](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-show)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-enums)

### 获取颜色( C)

```typescript
getColor() => Promise<GetColorResult>
```

获取导航栏当前背景颜色 .

只能从Android上找到.

**回返情况:** `Promise<[GetColorResult](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-getcolorresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 获取Style ()

```typescript
getStyle() => Promise<GetStyleResult>
```

获取导航条按钮的当前样式 .

只能从Android上找到.

**回返情况:** `Promise<[GetStyleResult](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-getstyleresult)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 隐藏( c)

```typescript
hide() => Promise<void>
```

隐藏导航栏 .

只能从Android上找到.

**自:** 8.0.0 (单位:千美元)

* * *

### 设置颜色(...)

```typescript
setColor(options: SetColorOptions) => Promise<void>
```

设置导航栏的背景颜色.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetColorOptions](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-setcoloroptions)` |

**自:** 8.0.0 (单位:千美元)

* * *

### 设置样式(...)

```typescript
setStyle(options: SetStyleOptions) => Promise<void>
```

设置导航条按钮的样式.

只能从Android上找到.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetStyleOptions](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-setstyleoptions)` |

**自:** 8.0.0 (单位:千美元)

* * *

### 显示 ()

```typescript
show() => Promise<void>
```

显示导航栏 .

只能从Android上找到.

**自:** 8.0.0 (单位:千美元)

* * *

### 接口

#### 获取颜色结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`color`** | `string` | 导航栏的十六进制颜色,或 `'transparent'` 如果导航栏完全透明. | 8.0.0 (单位:千美元) |

#### 获得 Style 成果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`style`** | `[Style](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-style)` | 导航条按钮的样式. | 8.0.0 (单位:千美元) |

#### 设置颜色选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`color`** | `string` | 要设置为导航栏背景颜色的十六进制颜色 。 使用 `'transparent'` 使导航栏透明. | 8.0.0 (单位:千美元) |
| **`dividerColor`** | `string` | 要设置为导航条分隔符的十六进制颜色 。 使用 `'transparent'` 来隐藏分裂者。 仅在Android(API级28+)上可用. | 8.0.0 (单位:千美元) |

#### 设置样式选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`style`** | `[Style](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-style)` | 导航条按钮的样式. | 8.0.0 (单位:千美元) |

### 数字

#### 样式

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Dark`** | `'DARK'` | 黑暗背景上的灯光图标. | 8.0.0 (单位:千美元) |
| **`Default`** | `'DEFAULT'` | 从当前设备外观中解析出 . | 8.0.0 (单位:千美元) |
| **`Light`** | `'LIGHT'` | 浅色背景上的黑暗图标. | 8.0.0 (单位:千美元) |

## 财务问题

### 为什么 `setColor` 财务报告和审定财务报表 `setStyle` 在Android 15+上不起作用的方法?

从Android 15开始,系统执行 [边缘到边缘显示](https://developer.android.com/develop/ui/views/layout/edge-to-edge) 默认。 在此模式下,导航栏完全透明 `Window.setNavigationBarColor` 因此,通过这个插件设置颜色没有可见效果. 如果您的应用程序瞄准了Android 15+,并且您想要给导航栏区域配色,请使用 [`@capawesome/capacitor-android-edge-to-edge-support`](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/android-edge-to-edge-support) 插件,它描绘了导航栏后面的覆盖.

### 为什么这个插件在iOS上无法使用?

iOS没有可以和Android上一样定制的系统导航条. 因此,此插件的所有方法在iOS上都没有执行,并错误地拒绝.

### 我该如何让导航栏透明化?

过 `'transparent'` 作为颜色到 `setColor` 方法或用作 `color` 数值 [电容配置](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-configuration)。也可以通过 `'transparent'` 作为 `dividerColor` 以隐藏导航条分隔符.

### 我可以应用一种颜色和风格 在应用程序发布?

是的,你可以定义 `color`, (中文(简体) ), `dividerColor`,以及 `style` 属性 `NavigationBar` 区域。 插件在应用程序启动时应用这些默认值, 所以你不必调用 `setColor` 或者说 `setStyle` 手动. 见 [配置](https://npmcn.com/package/%40capawesome/capacitor-navigation-bar/#readme-configuration) 例.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [Android 暗模式支持](https://capawesome.io/docs/sdks/capacitor/android-dark-mode-support/): Android 的无缝暗模式支持 `prefers-color-scheme` 兼容性.
-   [Android 边缘到边缘支持](https://capawesome.io/docs/sdks/capacitor/android-edge-to-edge-support/):在Android上支持边缘到边缘显示,包括设置状态栏和导航栏的背景颜色.
-   [家庭指标](https://capawesome.io/docs/sdks/capacitor/home-indicator/):隐藏并显示iOS上的家用指示器.
-   [屏幕方向](https://capawesome.io/docs/sdks/capacitor/screen-orientation/):锁定并解锁屏幕取向.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/navigation-bar/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/navigation-bar/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-navigation-bar 是什么？

电容插件可以设置Android上导航栏的背景颜色和按钮样式\.

### 如何安装 @capawesome/capacitor-navigation-bar？

在项目目录运行 npm install @capawesome/capacitor-navigation-bar，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-navigation-bar 支持 TypeScript 吗？

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

### @capawesome/capacitor-navigation-bar 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-navigation-bar 可以商用吗？

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

### @capawesome/capacitor-navigation-bar 的下载量有多少？

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

### @capawesome/capacitor-navigation-bar 还在维护吗？

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