# @capgo/capacitor-light-sensor 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-light-sensor/

版本：8\.1\.23
npm 元数据更新时间：2026-10-15T05:55:05.033Z
中文译文更新时间：2026-11-09T03:57:05.440Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-light-sensor
原文对照：https://npmcn.com/package/%40capgo/capacitor-light-sensor/?lang=original
项目主页：https://capgo.app/docs/plugins/light-sensor/
源码仓库：https://github.com/Cap-go/capacitor-light-sensor

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

- 包体积（解压后）：78.3 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core ^8\.0\.0
- 首次发布：2026-01-04T17:35:50.122Z
- 最新版本发布：2026-10-15T05:55:04.715Z
- 近 30 天下载量：41242（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

用于访问设备光传感器的电容插件( 只有Android)

## 安装

```sh
npm install @capgo/capacitor-light-sensor
```

也可以使用：`pnpm add @capgo/capacitor-light-sensor`、`yarn add @capgo/capacitor-light-sensor`、`bun add @capgo/capacitor-light-sensor`

## README

# @ capgo/ 电容- 光感应器

从您的 Capacitor app 中的设备传感器读取环境光度, 以适应主题, 亮度或相机提示到房间 .

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-light-sensor)](https://capgo.app/?ref=plugin_light_sensor)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_light_sensor)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_light_sensor) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-light-sensor` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/电容-光感应器到我的Capacitor应用上并把它接上"_ [代理设置指南](https://capgo.app/agents/?ref=plugin_light_sensor) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_light_sensor)

![@capgo/capacitor-light-sensor for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-light-sensor/main/assets/github-social-preview.png)

## 主要特点

-   **现场阅读**数字 : `start()` 流经 `lightSensorChange` 活动.
-   **取样控制**: 将更新间隔传递给 `start()`。 。 。 .
-   **可用性**数字 : `isAvailable()` 先检查光感应器.
-   **停下来**数字 : `stop()` 结束更新以保存电池.
-   **权限**数字 : `checkPermissions()` 财务报告和审定财务报表 `requestPermissions()` aPI 均等。 两人总是报告 `highSamplingRate` 已经同意.
-   **平台**:Android (英语). 仅限Android. iOS没有公共环境光传感器API,也没有网络.

## 为什么是光传感器?

-   **真实环境光数据**: 在豪华中获取准确的光等值读取
-   **高效传感器访问**: 使用原生Android传感器 API进行最佳性能
-   **可配置的更新间隔**: 控制多久收到传感器更新
-   **电池意识**: 启动和停止用于保存电池的传感器
-   **类型脚本支持**: 大型开发者经验的完整类型定义

## 平台支持

| 平台 | 支助 |
| --- | --- |
| 机器人 | 通过 TYPE LightT 传感器提供充分支持 |
| iOS系统 | 不适用(没有公开的API) |
| 网页 | 不详 |

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-light-sensor` plugin in my project.
```

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

```bash
npm install @capgo/capacitor-light-sensor
npx cap sync
```

## 所需资源

### 机器人

-   最低SDK: 24 (Android 7.0) (中文(简体) )
-   目标SDK:36
-   设备必须有一个光感应器(大多数Android手机都是这样)

### 高采样率(Android 12+)

对于在Android 12和以上200ms以下的更新间隔,请在您 `AndroidManifest.xml`数字 :

```xml
<uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />
```

## 使用量

```typescript
import { LightSensor } from '@capgo/capacitor-light-sensor';

// Check if sensor is available
const { available } = await LightSensor.isAvailable();

if (available) {
  // Start listening with 500ms update interval
  await LightSensor.start({ updateInterval: 500 });

  // Add listener for sensor data
  const handle = await LightSensor.addListener('lightSensorChange', (data) => {
    console.log(`Light level: ${data.illuminance} lux`);
    console.log(`Timestamp: ${data.timestamp}`);
  });

  // Later, stop the sensor
  await LightSensor.stop();
  await handle.remove();
}
```

## 轻等参考

| 吕克值 | 条件 |
| --- | --- |
| 0.0001 亿 | 无月,被覆盖的夜晚 |
| 0.27-1 (中文(简体) ) | 清晨满月 |
| 3.4 国家 | 民用黄昏的黑暗界限 |
| 第50条 | 家庭客厅 |
| 80个 | 办公室走廊 |
| 100个 | 非常黑暗的播报日 |
| 400个 | 日出/日出时间清晨 |
| 1 000个 | 广播日 |
| 10 000-25 000人 | 全天(间接) |
| 32 000-100 000美元 | 直接阳光 |

## API 密码

-   [`isAvailable()`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-isavailable)
-   [`start(...)`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-start)
-   [`stop()`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-stop)
-   [`addListener('lightSensorChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-addlistenerlightsensorchange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-removealllisteners)
-   [`checkPermissions()`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-checkpermissions)
-   [`requestPermissions()`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-requestpermissions)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-type-aliases)

用于访问设备环境光传感器的电容插件.

### 易读 ()

```typescript
isAvailable() => Promise<IsAvailableResult>
```

检查当前设备是否有光传感器可用 . 在尝试使用之前,你应该先检查传感器的可用性.

**回返情况:** `Promise<[IsAvailableResult](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-isavailableresult)>`

**自:** 0.0.1 资源

* * *

### 启动(...)

```typescript
start(options?: StartOptions | undefined) => Promise<void>
```

开始听光传感器的更新. 这将在指定的间隔开始传感器测量. 使用 `addListener` 接收传感器数据.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[StartOptions](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-startoptions)` | \- 传感器的配置选项 |

**自:** 0.0.1 资源

* * *

### 停止( )

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

停止听光传感器更新. 这将停止传感器 并保存电池.

**自:** 0.0.1 资源

* * *

### 添加Listener('LightSensor Change', ...) 输入器

```typescript
addListener(eventName: 'lightSensorChange', listenerFunc: LightSensorCallback) => Promise<PluginListenerHandle>
```

为光传感器变化事件添加一个收听器. 只要有新的传感器数据,就会调用听众.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'lightSensorChange'` | \- 一定是"光传感器变" |
| **`listenerFunc`** | `[LightSensorCallback](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-lightsensorcallback)` | \- 接收传感器数据的回调功能 |

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

**自:** 0.0.1 资源

* * *

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

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

清除所有用于光感应事件的听众.

**自:** 0.0.1 资源

* * *

### 检查( )

```typescript
checkPermissions() => Promise<PermissionStatus>
```

请检查access-date=中的日期值 (帮助) 高采样率传感器当前许可状态. 在Android 12+上,需要High SAMPLING RATE SENSERS许可 用于传感器更新间隔在200米以下.

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-permissionstatus)>`

**自:** 0.0.1 资源

* * *

### 请求( )

```typescript
requestPermissions() => Promise<PermissionStatus>
```

申请高采样率传感器许可. 在Android 12+上,这需要High SAMPLING RATE SENOS授权.

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-permissionstatus)>`

**自:** 0.0.1 资源

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<VersionResult>
```

获取当前版本的插件 .

**回返情况:** `Promise<[VersionResult](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-versionresult)>`

**自:** 0.0.1 资源

* * *

### 接口

#### 易伤性结果

结果表明传感器是否可用.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`available`** | `boolean` | 此设备是否有光感应器 。 总是在iOS上作假,因为光传感器API不可用. | 0.0.1 资源 |

#### 开始选项

启动光感应听器的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`updateInterval`** | `number` | 以毫秒计的传感器更新之间的理想间隔 。 在Android 12+上,最低间隔为200ms,除非该app有High SAMPLING RATE SENOS授权. | `200` | 0.0.1 资源 |

#### 插件听筒

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

#### 灯光传感器计量

单光感应测量.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`illuminance`** | `number` | 奢侈品中的安平光度 (lx). | 0.0.1 资源 |
| **`timestamp`** | `number` | 时间戳 从时代开始的几秒钟. | 0.0.1 资源 |

#### 权限状态

许可请求或检查的结果.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`highSamplingRate`** | `'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'` | 高采样率传感器是否获得许可 。 在Android 12+上,更新间隔为200ms以下需要此许可. | 0.0.1 资源 |

#### 版本结果

插件版本信息 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`version`** | `string` | 插件的当前版本 . | 0.0.1 资源 |

### 类型异名

#### 灯感应器回叫

用于光传感器更新的回调功能.

`(measurement: [LightSensorMeasurement](https://npmcn.com/package/%40capgo/capacitor-light-sensor/#readme-lightsensormeasurement)): void`

## 捐款

见 [捐款额](https://npmcn.com/package/%40capgo/capacitor-light-sensor/CONTRIBUTING.md) 关于如何为此插件贡献的详细信息.

## 许可证

[MPL - 2.0 导弹](https://npmcn.com/package/%40capgo/capacitor-light-sensor/LICENSE)

## 贷项

这个SDK的灵感来自 [曝光光传感器](https://docs.expo.dev/versions/latest/sdk/light-sensor/)。 。 。 .

## 常见问题

### @capgo/capacitor-light-sensor 是什么？

用于访问设备光传感器的电容插件\( 只有Android\)

### 如何安装 @capgo/capacitor-light-sensor？

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

### @capgo/capacitor-light-sensor 支持 TypeScript 吗？

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

### @capgo/capacitor-light-sensor 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-light-sensor 可以商用吗？

@capgo/capacitor-light-sensor 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-light-sensor 的下载量有多少？

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

### @capgo/capacitor-light-sensor 还在维护吗？

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