入门

1. 安装软件包

   npm

   npm i @capgo/capacitor-brightness

   pnpm

   pnpm add @capgo/capacitor-brightness

   yarn

   yarn add @capgo/capacitor-brightness

   bun

   bun add @capgo/capacitor-brightness

2. 与原生项目同步

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Android 配置

要修改 Android 上的系统范围亮度，请将 WRITE_SETTINGS 权限添加到 AndroidManifest.xml：

<uses-permission android:name="android.permission.WRITE_SETTINGS" />

用法

导入插件并使用其方法来控制亮度：

import { CapgoBrightness } from '@capgo/capacitor-brightness';

// Get current brightness
const getBrightness = async () => {
  const { brightness } = await CapgoBrightness.getBrightness();
  console.log('Current brightness:', brightness);
};

// Set brightness (0 to 1)
const setBrightness = async (level: number) => {
  await CapgoBrightness.setBrightness({ brightness: level });
};

// Check if API is available
const checkAvailable = async () => {
  const { available } = await CapgoBrightness.isAvailable();
  console.log('Brightness API available:', available);
};

API 参考

获取亮度()

获取设备主屏幕的当前亮度级别。

const { brightness } = await CapgoBrightness.getBrightness();
// Returns: { brightness: number } (0 to 1)

设置亮度（选项）

设置设备主屏幕的亮度级别。

interface SetBrightnessOptions {
  brightness: number; // 0.0 to 1.0
}

await CapgoBrightness.setBrightness({ brightness: 0.75 });

getSystemBrightness() （仅限 Android）

获取系统范围的屏幕亮度。

const { brightness } = await CapgoBrightness.getSystemBrightness();

setSystemBrightness(options)（仅Android）

设置系统范围的屏幕亮度。需要 WRITE_SETTINGS 权限。

await CapgoBrightness.setSystemBrightness({ brightness: 0.5 });

getSystemBrightnessMode() （仅限 Android）

获取当前系统亮度模式（自动或手动）。

import { BrightnessMode } from '@capgo/capacitor-brightness';

const { mode } = await CapgoBrightness.getSystemBrightnessMode();
if (mode === BrightnessMode.AUTOMATIC) {
  console.log('Auto-brightness is enabled');
}

setSystemBrightnessMode(options)（仅限 Android）

设置系统亮度模式。

import { BrightnessMode } from '@capgo/capacitor-brightness';

// Enable automatic brightness
await CapgoBrightness.setSystemBrightnessMode({ mode: BrightnessMode.AUTOMATIC });

// Enable manual brightness
await CapgoBrightness.setSystemBrightnessMode({ mode: BrightnessMode.MANUAL });

isUsingSystemBrightness() （仅限 Android）

检查当前活动是否使用系统范围的亮度。

const { isUsing } = await CapgoBrightness.isUsingSystemBrightness();

RestoreSystemBrightness()（仅限 Android）

重置亮度以使用系统范围的值。

await CapgoBrightness.restoreSystemBrightness();

isAvailable()

检查亮度 API 是否可用。

const { available } = await CapgoBrightness.isAvailable();

检查权限()

检查系统亮度访问权限。

const status = await CapgoBrightness.checkPermissions();
// Returns: { brightness: 'granted' | 'denied' | 'prompt' | 'prompt-with-rationale' }

请求权限()

请求系统亮度权限。打开 Android 上的系统设置。

const status = await CapgoBrightness.requestPermissions();

完整示例

import { CapgoBrightness, BrightnessMode } from '@capgo/capacitor-brightness';

export class BrightnessService {
  private originalBrightness: number | null = null;

  async init() {
    const { available } = await CapgoBrightness.isAvailable();
    if (!available) {
      throw new Error('Brightness API not available');
    }

    // Store original brightness
    const { brightness } = await CapgoBrightness.getBrightness();
    this.originalBrightness = brightness;
  }

  async setMaxBrightness() {
    await CapgoBrightness.setBrightness({ brightness: 1.0 });
  }

  async setMinBrightness() {
    await CapgoBrightness.setBrightness({ brightness: 0.0 });
  }

  async restore() {
    if (this.originalBrightness !== null) {
      await CapgoBrightness.setBrightness({
        brightness: this.originalBrightness
      });
    }
  }

  // Android-specific: Enable auto-brightness
  async enableAutoBrightness() {
    const status = await CapgoBrightness.checkPermissions();
    if (status.brightness !== 'granted') {
      await CapgoBrightness.requestPermissions();
    }

    await CapgoBrightness.setSystemBrightnessMode({
      mode: BrightnessMode.AUTOMATIC
    });
  }
}

最佳实践

1. 首先检查可用性

   const { available } = await CapgoBrightness.isAvailable();
   if (!available) {
     // Show fallback UI or disable brightness features
   }

2. 退出时恢复亮度 当您的应用程序进入后台或不再需要该功能时，请始终恢复原始亮度。

3. 请求 Android 的权限 对于系统范围的亮度控制，请在调用系统方法之前请求 WRITE_SETTINGS 权限。

4. 优雅地处理错误

   try {
     await CapgoBrightness.setBrightness({ brightness: 0.8 });
   } catch (error) {
     console.error('Failed to set brightness:', error);
   }

平台说明

iOS

• 亮度变化持续到设备锁定为止
• 仅支持应用程序特定的亮度
• 使用 UIScreen.main.brightness API

Android

• 应用程序特定的亮度仅适用于当前活动
• 系统范围的亮度需要 WRITE_SETTINGS 权限
• 支持自动亮度模式切换
• 使用 WindowManager 来调节应用程序亮度，使用 Settings.System 来调节系统亮度

网络

• 有限支持取决于浏览器功能
• 某些浏览器可能需要用户交互

要求

• Capacitor 8.0.0 或更高版本