# @capgo/capacitor-android-usagestatsmanager 中文文档

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

版本：8\.2\.14
npm 元数据更新时间：2026-11-02T12:46:16.621Z
中文译文更新时间：2026-11-09T06:44:59.346Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：145 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-04-11T09:50:36.811Z
- 最新版本发布：2026-11-02T12:46:16.330Z
- 近 30 天下载量：4580（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 53 个）

## 中文简介

将Android的用法Stats Manager SDK 曝光给控制器

## 安装

```sh
npm install @capgo/capacitor-android-usagestatsmanager
```

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

## README

# @capgo/ 电容- 机器人- usagestatsmanager

从您的 Capacitor app 读取 Android 应用程序使用统计 `UsageStatsManager` API:每个应用程序的屏幕时间,使用间隔和原始使用事件. 用于数字福利,家长控制和分析应用.

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

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

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

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

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

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

## 主要特点

-   **总使用**数字 : `queryAndAggregateUsageStats()` 返回时间范围的每个应用程序使用.
-   **数据间隔**数字 : `queryUsageStats()` 返回每日、每周、每月或每年间隔的数据.
-   **原始活动**数字 : `queryEvents()` 读取一个时间范围的使用事件日志.
-   **已安装的应用程序**数字 : `queryAllPackages()` 列出安装在设备上的软件包.
-   **权限助手**数字 : `isUsageStatsPermissionGranted()` 财务报告和审定财务报表 `openUsageStatsSettings()` 指导用户允许使用.
-   **平台**:Android (英语). 仅限Android. 网络方法抛出.

## 说明

将Android的用法Stats Manager SDK 曝光给控制器

## 为什么是Android UsageStats Manager?. 中国植物物种信息数据库?

唯一显示 Android 的插件 **用法Stats 管理者 API** 到 Capacitor - 此Android API 在之前没有被任何插件支持 :

-   **App 用户跟踪** - 监视哪些应用软件打开用户并持续多久
-   **屏幕时间分析** - 建立父母控制和数字福利功能
-   **确切窗口事件** - 在需要将前景时间剪接到特定范围时,查询原始生命周期事件
-   **软件包信息** - 查询设备上安装的所有应用程序
-   **时间查询** - 获取任何时间范围内的数据

适合家长控制应用程序、数字福利工具、生产力跟踪器和屏幕时间管理器.

## 使用量

需要下列权限: `AndroidManifest.xml`数字 :

```xml
<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS"
    tools:ignore="ProtectedPermissions" />
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"
    tools:ignore="QueryAllPackagesPermission" />
```

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/android-usagestatsmanager/ 互联网档案馆的存檔,存档日期2013-12-20](https://capgo.app/docs/plugins/android-usagestatsmanager/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页: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-android-usagestatsmanager` plugin in my project.
```

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

```bash
npm install @capgo/capacitor-android-usagestatsmanager
npx cap sync
```

## API 密码

-   [`queryAndAggregateUsageStats(...)`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryandaggregateusagestats)
-   [`queryUsageStats(...)`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryusagestats)
-   [`queryEvents(...)`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryevents)
-   [`isUsageStatsPermissionGranted()`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-isusagestatspermissiongranted)
-   [`openUsageStatsSettings()`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-openusagestatssettings)
-   [`queryAllPackages(...)`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryallpackages)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-type-aliases)

用于访问Android UsageStatsManager API的电容插件.

### 查询AggregateUsageStats(...)

```typescript
queryAndAggregateUsageStats(options: UsageStatsOptions) => Promise<Record<string, UsageStats>>
```

为给定时间范围查询和汇总使用数据.

Android每日/每周/每月/每年读取预先汇总的桶和款项 每个相交的桶 `[beginTime, endTime)`没有剪辑它. `totalTimeInForeground` 因此可以包括窗口外的用法. 使用 `queryUsageStats` 用于未浮出水面的每桶,或 `queryEvents` 用于在请求范围内进行时间标记的生命周期事件.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[UsageStatsOptions](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-usagestatsoptions)` | \- 查询的时间范围选项 |

**回返情况:** `Promise<[Record](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-record)<string, [UsageStats](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-usagestats)>>`

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

* * *

### 查询UsageStats(...)

```typescript
queryUsageStats(options: QueryUsageStatsOptions) => Promise<QueryUsageStatsResult>
```

查询给定间隔类型和时间范围的用法统计.

环绕Android `UsageStatsManager.queryUsageStats`不同 `queryAndAggregateUsageStats`,不合并桶:结果为 一个 [`UsageStats`](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-usagestats) 对象每包每相重叠间隔。 Android 可能会 扩展 `[beginTime, endTime)` 到最近的整个间隔期,所以 `totalTimeInForeground` 可包括窗口外的用法.

在Android R(API 30)及以上上,OS在用户为时不返回数据 锁定; 此插件随后解析 `{ stats: [] }`,不能对其进行处理 以0 为前景用法.

这个用同一种 `PACKAGE_USAGE_STATS` 允许为 `queryAndAggregateUsageStats`。 。 。 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[QueryUsageStatsOptions](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryusagestatsoptions)` | \- 间隔类型、时间范围和可选软件包过滤器 |

**回返情况:** `Promise<[QueryUsageStatsResult](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryusagestatsresult)>`

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

* * *

### 查询事件(...)

```typescript
queryEvents(options: QueryEventsOptions) => Promise<QueryEventsResult>
```

查询指定时间范围的原始使用事件日志.

返回时间戳入的生命周期事件 `[beginTime, endTime)`。 。 。 . Android没有发出一个合成事件 用于"已经出现在前方 开始时间"或"在结束时间仍然处于前景". 衡量跨度 这些界限,通过一个较早的 `beginTime` 作为本地回首和剪接: 将未匹配的暂停作为窗口启动时开始, 和未匹配 恢复为结束于窗口端.

Android只保留了几天的事件. 长距离可能返回 不完整或为空的列表; 与 0 前置使用不相同 . 在Android R(API 30)及以上时,OS也会在Android R(API 30)及以上时不返回事件 用户被锁定;然后此插件解析 `{ events: [] }`,同样 不得作为零前台使用.

呼叫者可以将返回的事件恢复到暂停的间隔相加. 不要治疗 `DEVICE_SHUTDOWN` 作为暂停:它是一个重设的标记,而不是一个 间隔接近 。 这个用同一种 `PACKAGE_USAGE_STATS` 允许为 `queryAndAggregateUsageStats`。 。 。 .

只有生命周期事件才能返回,以保持桥载荷的小型:

-   `1` 活动/活动
-   `2` ——活动 提供/移动 TO BACKGRUND
-   `23` 活动
-   `26` —— DEVICE SHUTDOWN( 设备宽重置标记; 仍然返回时 `packageName` 已经设定。 Android 通常报告软件包 `"android"`。 。 。 . `packageName` 如果操作系统不附加一个,则省略。 时间戳 是最后一个 [使用数据](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-usagestats) 关闭前持续,而非实际 电源关闭。 打开恢复事件而不匹配此间暂停 标记和下一个靴子的期限不明,必须被忽略。 )

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[QueryEventsOptions](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryeventsoptions)` | \- 时间范围和可选软件包过滤器 |

**回返情况:** `Promise<[QueryEventsResult](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryeventsresult)>`

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

* * *

### 是UsageStats 授权加兰特 ()

```typescript
isUsageStatsPermissionGranted() => Promise<UsageStatsPermissionResult>
```

检查是否允许使用数据 .

**回返情况:** `Promise<[UsageStatsPermissionResult](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-usagestatspermissionresult)>`

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

* * *

### 打开用户定义

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

打开使用 STAS 设置屏幕 . 这将打开使用 STATs 设置屏幕, 允许用户批准使用 STATs 权限 . 这将总是打开设置屏幕, 即使已经获得许可 .

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

* * *

### 查询 AllPackages (...)

```typescript
queryAllPackages(options?: QueryAllPackagesOptions | undefined) => Promise<{ packages: PackageInfo[]; }>
```

查询设备上安装的所有软件包. 需要QUERY ALL PACKAGES许可.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[QueryAllPackagesOptions](https://npmcn.com/package/%40capgo/capacitor-android-usagestatsmanager/#readme-queryallpackagesoptions)` | \- 可选查询设置 |

**回返情况:** `Promise<{ packages: PackageInfo[]; }>`

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

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本 .

**回返情况:** `Promise<{ version: string; }>`

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

* * *

### 接口

#### 使用数据

Android应用软件的使用统计.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`firstTimeStamp`** | `number` | 使用统计的首个时间戳. |
| **`lastTimeStamp`** | `number` | 使用统计表的最后印记 . |
| **`lastTimeForegroundServiceUsed`** | `number` | 仅在Android Q(API 第29级)及以上可用. 将在下Android版本上未定义. |
| **`lastTimeUsed`** | `number` | 上回应用. |
| **`lastTimeVisible`** | `number` | 仅在Android Q(API 第29级)及以上可用. 将在下Android版本上未定义. |
| **`packageName`** | `string` | 包裹名. |
| **`totalForegroundServiceUsed`** | `number` | 仅在Android Q(API 第29级)及以上可用. 将在下Android版本上未定义. |
| **`totalTimeInForeground`** | `number` | 应用程序的总时间在前方. |
| **`totalTimeVisible`** | `number` | 仅在Android Q(API 第29级)及以上可用. 将在下Android版本上未定义. |

#### 用法Stats 选项

查询使用统计的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`beginTime`** | `number` | 包含在结果中的统计范围的包容性开始. 定义为"Unix时间" |  |
| **`endTime`** | `number` | 包含在结果中的统计范围的专属结束. 定义为"Unix时间" |  |
| **`packageName`** | `string` | 可选包名. 设定时,仅返回此软件包的数据 。 关闭返回每个软件包的数据( 先前的行为) 。 空字符串被拒绝 . | 8.1.3 (中文(简体) ) |

#### 查询UsageStats Result 数据

其结果a `queryUsageStats` 电话.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`stats`** | `UsageStats[]` | 在请求范围内使用数据桶,由操作系统返回命令。 当多个间隔重叠时,同一个包可以不止出现一次. |

#### 查询UsageStats 选项

按间用统计查询选项.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`intervalType`** | `number` | 中间类型从 `android.app.usage.UsageStatsManager`:- `0` - INTERVALTAL DAILY - - 时间轴: `1` - 时间轴: `2` 月间休息时间 `3` 间歇时间 `4` - INTERVAL BEST(国际空间站) |
| **`beginTime`** | `number` | 包含在结果中的统计范围的包容性开始. 定义为"Unix时间" |
| **`endTime`** | `number` | 包含在结果中的统计范围的专属结束. 定义为"Unix时间" |
| **`packageName`** | `string` | 可选包名. 设定时, 只返回此软件包的数据 。 空字符串被拒绝 . |

#### 查询事件结果

其结果a `queryEvents` 电话.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`events`** | `UsageEvent[]` | 请求范围内的生命周期使用事件,由OS返回命令. |

#### 用法活动

代表单一使用事件.

`queryEvents` 当前分布 `className`, (中文(简体) ), `timeStamp`,以及 `eventType`。 。 。 . `packageName` 当Android附加一个时设定(DEVICE SHUTDOWN 通常使用 `"android"`)而省略了其他内容。 其他字段仍然可选 兼容性.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`packageName`** | `string` | 软件包名称 。 当Android不附加一个包时,即发出通知. DEVICE SHUTDOWN 一般使用 `"android"`。 。 。 . |
| **`className`** | `string` | 类名( 可能是无效的) |
| **`timeStamp`** | `number` | 时间戳( 毫秒) |
| **`eventType`** | `number` | 事件类型常数从 `android.app.usage.UsageEvents.Event`。 。 。 . `queryEvents` 仅返回生命周期类型: - `1` - 活动/活动 `2` - 活动/移动-BACKGROUND `23` 活动 启动 `26` —— DEVICE SHUTDOWN( 重置标记, 而不是间隔关闭) |
| **`configuration`** | `any` | 配置对象( 需要 API 28+) |
| **`shortcutId`** | `string` | 快捷码( 需要 API 28+) |
| **`standbyBucket`** | `number` | 应用备用桶( 需要 API 28+) |
| **`notificationChannelId`** | `string` | 通知通道 ID( 需要 API 29+) |
| **`instanceId`** | `number` | 实例标识( 需要 API 30+) |
| **`taskRootPackageName`** | `string` | 任务根包名称( 需要 API 31+) |
| **`taskRootClassName`** | `string` | 任务根类名( 需要 API 31+) |

#### 查询结果选项

查询原始使用事件日志的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`beginTime`** | `number` | 包含在结果中的活动范围的包容性开端. 定义为"Unix时间" |
| **`endTime`** | `number` | 包含在结果中的全程事件结束. 定义为"Unix时间" |
| **`packageName`** | `string` | 可选包名. 设定时, 只返回此软件包的事件, 外加全设备 `DEVICE_SHUTDOWN` 事件。 空字符串被拒绝 。 当您关心一个应用时, Capacitor 桥载荷会保持小. |

#### 用法Stats 任务结果

使用量统计权限检查的结果 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`granted`** | `boolean` | 是否允许使用数据 . |

#### 软件包信息

代表一个已安装软件包的基本信息.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`packageName`** | `string` | 软件包名称 |  |
| **`appName`** | `string` | 应用显示名称 |  |
| **`versionName`** | `string` | 版本名称字符串 |  |
| **`versionCode`** | `number` | 版本代码 |  |
| **`firstInstallTime`** | `number` | 以毫秒计的首次安装时间 |  |
| **`lastUpdateTime`** | `number` | 以毫秒计的上次更新时间 |  |
| **`category`** | `number` | 申请类别从 `ApplicationInfo.category`。仅可在Android 8.0(API 26级)及以上获取。 共同价值: - `0` - 未定义 - `1` 游戏 `2` - 音频 `3` - 视频 `4` 图像 `5` 社会 `6` -新闻 `7` 地图 `8` 生产率 | 8.0.33 (中文(简体) ) |
| **`icon`** | `string` | App 图标作为基础64数据 URL(`data:image/png;base64,...`) (中文(简体) ). 只在 `queryAllPackages({ includeIcon: true })` 已使用. | 8.0.33 (中文(简体) ) |

#### 查询所有套件选项

查询已安装软件包的选项 .

| Prop | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| **`includeIcon`** | `boolean` | 当真实时,包括每个app的启动器图标作为基数64数据URL. 默认为虚假,因为图标会大大增加响应大小. | `false` |

### 类型异名

#### 记录

构造 T 类型 K 的一组属性类型

`{ [P in K]: T; }`

## 常见问题

### @capgo/capacitor-android-usagestatsmanager 是什么？

将Android的用法Stats Manager SDK 曝光给控制器

### 如何安装 @capgo/capacitor-android-usagestatsmanager？

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

### @capgo/capacitor-android-usagestatsmanager 支持 TypeScript 吗？

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

### @capgo/capacitor-android-usagestatsmanager 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-android-usagestatsmanager 可以商用吗？

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

### @capgo/capacitor-android-usagestatsmanager 的下载量有多少？

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

### @capgo/capacitor-android-usagestatsmanager 还在维护吗？

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