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

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

版本：0\.1\.0
npm 元数据更新时间：2026-10-01T11:40:01.839Z
中文译文更新时间：2026-11-09T14:42:58.239Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：81.3 kB，37 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-10-01T11:32:10.198Z
- 最新版本发布：2026-10-01T11:40:01.473Z
- 近 30 天下载量：2438（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

在iOS上显示液态玻璃的本地标签栏的电容插件.

## 安装

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

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

## README

# 电容标签栏插件

显示原生插件 [选项卡栏](https://developer.apple.com/documentation/uikit/uitabbar) iOS上有"液态玻璃".

[![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/)

## 特征

-   🫧 **液体玻璃**:将iOS 26上的原生液体玻璃标签栏和更早版本的经典标签栏进行渲染.
-   🧭 **标签**: 使用您的资产目录中的 SF 符号或图像作为图标并显示徽章 .
-   🎨 **颜色**: 自定义所选和未选标签的颜色.
-   📐 **安全区**: 扩展网页视图的下层安全区域,所以您的内容从未被标签栏所覆盖.
-   🚀 **发射配置**: 显示启动时的标签栏, 不等待您的网络应用程序 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

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

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **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-tab-bar` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

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

此插件仅可用于 **iOS系统**。在Android和Web上,所有方法都否认未执行.

### iOS系统

标签栏被放置在网页视图上方,而网页视图的下层安全区域设置会由标签栏的高度而增加. 您的网络应用程序必须满足以下要求, 使其内容不被标签栏覆盖 :

-   这个 `viewport` 您页面的元标签必须包含 `viewport-fit=cover`数字 :
    
    ```html
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    ```
    
-   这个 [`ios.contentInset`](https://capacitorjs.com/docs/config) 配置选项必须设置为 `never` (默认). 与 `always`,该套件将应用两次.
    
-   您的内容必须尊重底层安全区域设置, 例如使用 `padding-bottom: env(safe-area-inset-bottom)`。 。 。 .
    

如果您使用 [`@capacitor/splash-screen`](https://capacitorjs.com/docs/apis/splash-screen),不配置 `tabs` 在您的电容配置中, 标签栏将显示在喷出屏幕上 。 相反,打电话 `setTabs(...)` 财务报告和审定财务报表 `show()` 之后 `SplashScreen.hide()`。 。 。 .

## 配置

这些配置值是可用的 :

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`tabs`** | `Tab[]` | 发射时要显示的标签 。 如果设定了,则从发射中创建并可见标签栏. 使用时不设置此选项 `@capacitor/splash-screen`,因为标签栏会显示在喷出屏幕上。 仅在iOS上可用. | 0.1.0 (中文(简体) ) |
| **`selectedTabId`** | `string` | 启动时要选择的标签的ID 。 如果没有设置,则选择第一个标签。 仅在iOS上可用. | 0.1.0 (中文(简体) ) |
| **`selectedColor`** | `string` | 所选标签的颜色作为十六进制颜色代码 。 如果没有设定,则使用系统默认值. 仅在iOS上可用. | 0.1.0 (中文(简体) ) |
| **`unselectedColor`** | `string` | 未选中标签的颜色作为十六进制颜色代码 。 如果没有设定,则使用系统默认值. 对iOS 26和后期没有影响,因为系统决定了液态玻璃上未选取的分页的颜色. 仅在iOS上可用. | 0.1.0 (中文(简体) ) |

### 实例

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

```json
{
  "plugins": {
    "TabBar": {
      "tabs": [{ "id": "home", "title": "Home", "systemImage": "house.fill" }],
      "selectedTabId": "home",
      "selectedColor": "#007AFF",
      "unselectedColor": "#8E8E93"
    }
  }
}
```

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

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

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

const config: CapacitorConfig = {
  plugins: {
    TabBar: {
      tabs: [{ "id": "home", "title": "Home", "systemImage": "house.fill" }],
      selectedTabId: "home",
      selectedColor: "#007AFF",
      unselectedColor: "#8E8E93",
    },
  },
};

export default config;
```

## 演示

| iOS系统 |
| --- |
| ![iOS Demo](https://raw.githubusercontent.com/capawesome-team/capacitor-plugins/main/packages/tab-bar/assets/tab-bar-demo-ios.png) |

## 使用量

以下示例显示如何设置标签栏并响应标签选择.

### 设置标签并显示标签栏

设置标签并显示标签栏 。 每个标签使用 SF 符号(`systemImage`)或来自您应用程序资产目录的图像( )`image`作为它的图标。 仅在iOS上可用 :

```typescript
import { TabBar } from '@capawesome/capacitor-tab-bar';

const showTabBar = async () => {
  await TabBar.setTabs({
    tabs: [
      { id: 'home', title: 'Home', systemImage: 'house.fill' },
      { id: 'search', title: 'Search', systemImage: 'magnifyingglass' },
      { id: 'inbox', title: 'Inbox', systemImage: 'tray.fill', badge: '3' },
      { id: 'profile', title: 'Profile', image: 'profile-icon' },
    ],
    selectedTabId: 'home',
  });
  await TabBar.show();
};

const hideTabBar = async () => {
  await TabBar.hide();
};
```

或者,在您的 Capacitor 配置中配置标签以显示启动时的标签栏(参见 [配置](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-configuration)) (中文(简体) ).

### 监听标签选择

这个 `tabSelected` 每次用户点击标签,包括已经选中的标签,都会释放出事件。 仅在iOS上可用 :

```typescript
import { TabBar } from '@capawesome/capacitor-tab-bar';

const addListener = async () => {
  await TabBar.addListener('tabSelected', event => {
    console.log('Tab selected:', event.id);
  });
};
```

### 在程序上选择标签

选择一个标签, 例如在您网络应用中导航后 。 此方法不会释放 `tabSelected` 活动。 仅在iOS上可用 :

```typescript
import { TabBar } from '@capawesome/capacitor-tab-bar';

const selectTab = async () => {
  await TabBar.selectTabById({ id: 'search' });
};
```

### 更新徽章

打电话 `setTabs(...)` 重新使用更新的标签。 目前选中的标签仍为选中 。 仅在iOS上可用 :

```typescript
import { TabBar } from '@capawesome/capacitor-tab-bar';

const updateBadge = async () => {
  await TabBar.setTabs({
    tabs: [
      { id: 'home', title: 'Home', systemImage: 'house.fill' },
      { id: 'search', title: 'Search', systemImage: 'magnifyingglass' },
      { id: 'inbox', title: 'Inbox', systemImage: 'tray.fill', badge: '4' },
      { id: 'profile', title: 'Profile', image: 'profile-icon' },
    ],
  });
};
```

### 自定义颜色

设置选中和未选中标签的颜色 。 未提供的颜色被重置为系统默认值。 在iOS 26上和后期,未选取的颜色没有效果,因为系统决定了液态玻璃上未选取的分页的颜色. 仅在iOS上可用 :

```typescript
import { TabBar } from '@capawesome/capacitor-tab-bar';

const setColors = async () => {
  await TabBar.setColors({
    selectedColor: '#FF2D55',
    unselectedColor: '#8E8E93',
  });
};
```

## 离子框架

如果您使用 [离子框架](https://ionicframework.com/),可以替换 `ion-tab-bar` 使用 iOS 上的本地标签栏,并继续使用 Ionic 路由器进行导航:

1.  隐藏 `ion-tab-bar` iOS上的数据:
    
    ```css
    .plt-ios ion-tab-bar {
      display: none;
    }
    ```
    
2.  使用路由器导航到已调制的标签, 当路由更改为其它标签时选择本地标签 。 本地标签使用相同的ID `tab` 您的财产 `ion-tab-button` 要素。 下例使用Angular,但同一方法与React和Vue配合:
    
    ```html
    <ion-tabs (ionTabsDidChange)="handleTabsDidChange($event)">
      <!-- ... -->
    </ion-tabs>
    ```
    
    ```typescript
    import { Component, OnInit } from '@angular/core';
    import { Router } from '@angular/router';
    import { Capacitor } from '@capacitor/core';
    import { TabBar } from '@capawesome/capacitor-tab-bar';
    
    @Component({
      selector: 'app-tabs',
      templateUrl: 'tabs.page.html',
    })
    export class TabsPage implements OnInit {
      private readonly isIos = Capacitor.getPlatform() === 'ios';
    
      constructor(private readonly router: Router) {}
    
      ngOnInit() {
        if (this.isIos) {
          void TabBar.addListener('tabSelected', ({ id }) => {
            void this.router.navigateByUrl(`/tabs/${id}`);
          });
        }
      }
    
      handleTabsDidChange(event: { tab: string }) {
        if (this.isIos) {
          void TabBar.selectTabById({ id: event.tab });
        }
      }
    }
    ```
    
3.  将您的内容与底部安全区域嵌入, 包括本地标签栏的高度 :
    
    ```css
    ion-content {
      --padding-bottom: env(safe-area-inset-bottom);
    }
    ```
    

## API 密码

-   [`hide()`](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-hide)
-   [`selectTabById(...)`](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-selecttabbyid)
-   [`setColors(...)`](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-setcolors)
-   [`setTabs(...)`](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-settabs)
-   [`show()`](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-show)
-   [`addListener('tabSelected', ...)`](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-addlistenertabselected-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-interfaces)

### 隐藏( c)

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

隐藏标签栏 .

标签保存并重置下层安全区域.

仅在iOS上可用.

**自:** 0.1.0 (中文(简体) )

* * *

### 选择 TabById(...)

```typescript
selectTabById(options: SelectTabByIdOptions) => Promise<void>
```

选择带有给定ID的标签 .

此方法不会释放 `tabSelected` 活动.

仅在iOS上可用.

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

**自:** 0.1.0 (中文(简体) )

* * *

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

```typescript
setColors(options: SetColorsOptions) => Promise<void>
```

设置标签的颜色 .

未提供的颜色被重置为系统默认值.

仅在iOS上可用.

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

**自:** 0.1.0 (中文(简体) )

* * *

### 设置标签(...)

```typescript
setTabs(options: SetTabsOptions) => Promise<void>
```

设置标签栏的标签 .

这将取代所有已存在的标签 . 带有标识的标签 `selectedTabId` 如果提供,则选中. 否则,如果当前选中的标签的ID仍然存在,或者第一个标签被选中,则该标签将保留选中.

这种方法不会改变标签栏的能见度.

仅在iOS上可用.

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

**自:** 0.1.0 (中文(简体) )

* * *

### 显示 ()

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

显示标签栏 .

标签栏放在屏幕下方和下方 安全区域内置的网页视图会因标签栏的高度而增加.

标签必须首先使用 `setTabs(...)` 或 `tabs` 配置 .

仅在iOS上可用.

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( 未选中),...)

```typescript
addListener(eventName: 'tabSelected', listenerFunc: (event: TabSelectedEvent) => void) => Promise<PluginListenerHandle>
```

用户点击标签时调用 .

如果用户点击已选中的标签, 也会释放此事件 .

仅在iOS上可用.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'tabSelected'` |
| **`listenerFunc`** | `(event: [TabSelectedEvent](https://npmcn.com/package/%40capawesome/capacitor-tab-bar/#readme-tabselectedevent)) => void` |

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

**自:** 0.1.0 (中文(简体) )

* * *

### 删除所有收听器( )

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

删除此插件的所有听众 .

仅在iOS上可用.

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 选择 TabById 选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 要选择的标签的ID . | 0.1.0 (中文(简体) ) |

#### 设置颜色选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`selectedColor`** | `string` | 所选标签的颜色作为十六进制颜色代码 。 如果不提供,则使用系统默认值. | 0.1.0 (中文(简体) ) |
| **`unselectedColor`** | `string` | 未选中标签的颜色作为十六进制颜色代码 。 如果不提供,则使用系统默认值。 对iOS 26和后期没有影响,因为系统决定了液态玻璃上未选取的分页的颜色. | 0.1.0 (中文(简体) ) |

#### 设置标签选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`tabs`** | `Tab[]` | 要显示的标签 。 每个标签必须有一个独特的ID. | 0.1.0 (中文(简体) ) |
| **`selectedTabId`** | `string` | 要选择的标签的ID 。 如果未提供, 如果当前选中的标签仍然存在, 则保留选中的标签 。 否则,将选择第一个标签 . | 0.1.0 (中文(简体) ) |

#### 标签

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 标签的唯一标识 . | 0.1.0 (中文(简体) ) |
| **`title`** | `string` | 分页标题. | 0.1.0 (中文(简体) ) |
| **`systemImage`** | `string` | 要用作标签图标的 SF 符号名称 。 就是其中一个 `systemImage` 或者说 `image` 必须提供. | 0.1.0 (中文(简体) ) |
| **`image`** | `string` | 用作标签图标的应用程序资产目录中的图像名称 。 图像作为模板图像提供. 就是其中一个 `systemImage` 或者说 `image` 必须提供. | 0.1.0 (中文(简体) ) |
| **`badge`** | `string` | 标签的徽标值 。 如果不提供徽章,则不显示徽章. | 0.1.0 (中文(简体) ) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 标签选中事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 被窃听的标签的识别码 . | 0.1.0 (中文(简体) ) |

## 通讯

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

## 更改日志

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

## 许可证

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

## 常见问题

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

在iOS上显示液态玻璃的本地标签栏的电容插件\.

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

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

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

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

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

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

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

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

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

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

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

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