入门

1. 安装软件包

   npm

   npm i @capgo/capacitor-navigation-bar

   pnpm

   pnpm add @capgo/capacitor-navigation-bar

   yarn

   yarn add @capgo/capacitor-navigation-bar

   bun

   bun add @capgo/capacitor-navigation-bar

2. 与原生项目同步

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. 配置插件

   设置导航栏颜色：

   import { NavigationBar } from '@capgo/capacitor-navigation-bar';
   
   // Set navigation bar color
   await NavigationBar.setColor({
     color: '#FF0000', // Red color
     darkButtons: false // Use light buttons
   });

   动态主题支持：

   // Set color based on theme
   const isDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches;
   
   await NavigationBar.setColor({
     color: isDarkMode ? '#000000' : '#FFFFFF',
     darkButtons: !isDarkMode
   });

   Android

   最低要求：

   • Android 5.0（API 21 级）或更高
   • 该插件仅适用于 Android 设备

   AndroidManifest.xml 中无需进行额外设置。

   iOS

   该插件仅限 Android。 iOS 没有可自定义的导航栏。

4. 高级用法

   import { NavigationBar } from '@capgo/capacitor-navigation-bar';
   
   export class ThemeService {
     // Set transparent navigation bar
     async setTransparent() {
       await NavigationBar.setColor({
         color: '#00000000', // Transparent
         darkButtons: true
       });
     }
   
     // Match app theme
     async matchAppTheme(primaryColor: string, isLight: boolean) {
       await NavigationBar.setColor({
         color: primaryColor,
         darkButtons: isLight
       });
     }
   
     // Get current navigation bar color
     async getCurrentColor() {
       const result = await NavigationBar.getColor();
       console.log('Current color:', result.color);
       return result.color;
     }
   
     // Reset to default
     async resetToDefault() {
       await NavigationBar.setColor({
         color: '#000000',
         darkButtons: false
       });
     }
   }

5. 与应用程序生命周期集成

   import { App } from '@capacitor/app';
   import { NavigationBar } from '@capgo/capacitor-navigation-bar';
   
   // Update navigation bar on app state changes
   App.addListener('appStateChange', async ({ isActive }) => {
     if (isActive) {
       // Restore your app's navigation bar color
       await NavigationBar.setColor({
         color: '#YourAppColor',
         darkButtons: true
       });
     }
   });
   
   // Handle theme changes
   window.matchMedia('(prefers-color-scheme: dark)')
     .addEventListener('change', async (e) => {
       await NavigationBar.setColor({
         color: e.matches ? '#121212' : '#FFFFFF',
         darkButtons: !e.matches
       });
     });

API 参考

方法

setColor(options: ColorOptions)

设置导航栏颜色和按钮样式。

参数：

• options：配置对象
  • color：字符串 - 十六进制颜色代码（例如，‘#FF0000’）
  • darkButtons: 布尔值 - 使用深色按钮 (true) 或浅色按钮 (false)

返回： Promise<void>

getColor()

获取当前导航栏颜色。

返回： Promise<{ color: string }>

接口

interface ColorOptions {
  color: string;      // Hex color code
  darkButtons: boolean; // Button style
}

interface ColorResult {
  color: string;      // Current hex color
}

平台说明

Android

• 需要 Android 5.0 (API 21 级) 或更高
• 颜色变化立即发生
• 支持透明颜色（使用 Alpha 通道）
• 导航栏在具有手势导航的设备上可能不可见

iOS

• 该插件对 iOS 设备没有影响
• iOS不提供API来自定义系统导航

常见用例

1. 品牌一致性：导航栏与应用程序的主要颜色相匹配
2. 主题支持：动态适应浅色/深色主题
3. 沉浸式体验：对全屏内容使用透明导航
4. 状态指示：更改颜色以指示应用程序状态（正在录制、错误等）

最佳实践

1. 颜色对比度：确保导航栏和按钮之间有足够的对比度

   // Good contrast examples
   setColor({ color: '#FFFFFF', darkButtons: true });  // White bar, dark buttons
   setColor({ color: '#000000', darkButtons: false }); // Black bar, light buttons

2. 主题一致性：主题更改时更新导航栏

3. 辅助功能：选择颜色时考虑有视觉障碍的用户

4. 性能：避免可能分散用户注意力的频繁颜色变化

故障排除

导航栏不变：

• 验证设备正在运行 Android 5.0+
• 检查设备是否启用手势导航
• 确保颜色格式是有效的十六进制（例如“#FF0000”）

按钮不可见：

• 检查 darkButtons 参数是否与您的背景颜色匹配
• 浅色背景需要darkButtons: true
• 深色背景需要 darkButtons: false

颜色看起来不同：

• 某些 Android 版本可能会稍微修改颜色
• 使用完全不透明的颜色以获得最佳效果