# @capgo/capacitor-permissions 中文文档

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

版本：8\.2\.8
npm 元数据更新时间：2026-10-15T02:17:16.349Z
中文译文更新时间：2026-11-09T04:12:07.061Z
软件包许可：MPL-2\.0

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

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

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

- 包体积（解压后）：154 kB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-10-01T14:18:11.149Z
- 最新版本发布：2026-10-15T02:17:15.236Z
- 近 30 天下载量：39796（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

用于检查和请求应用权限的电容插件.

## 安装

```sh
npm install @capgo/capacitor-permissions
```

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

## README

# @ capgo/ 电容- 许可

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

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

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

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

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

**@ capgo/ 电容- 许可** 给予Capacitor Apps一个TypeScript API,以检查和请求iOS,Android,和web上的运行时间权限. 与其单独布线每个特性插件或猜测平台特定状态代码,不如使用单一的一组权限名称和规范状态(`granted`, (中文(简体) ), `denied`, (中文(简体) ), `blocked`, (中文(简体) ), `limited`, (中文(简体) ), `unavailable`) (中文(简体) ). 本地运单保持倾斜: 插件船没有 `uses-permission` 条目或强制的Info.plist字符串,所以存储审查只查看您的应用程序声明的内容.

### 特征

-   一个 `PermissionName` 用于相机、位置、通知、媒体、联系人和更多跨平台的信息
-   `check`, (中文(简体) ), `request`, (中文(简体) ), `checkMultiple`,以及 `requestMultiple` 与共享 `AppPermissionState` 结果
-   机器人 `shouldShowRationale` 拒绝后重发警告
-   `openSettings` 当访问被屏蔽时用于应用程序或通知设置
-   `requestPreciseLocation` iOS和 `ACCESS_FINE_LOCATION` 安卓号
-   通过浏览器实现所支持类型的 Web 执行权限 API
-   可选 `scripts/apply-permissions.mjs` 只添加您需要的 Android 和 iOS 声明

### 使用大小写

-   在允许相机或麦克风访问之前打开屏幕
-   运行启动审计 `checkMultiple` 并显示缺失权限的单个登机流程
-   状态时将用户发送到系统设置 `blocked` 之后 `openSettings`
-   在登记出推码前请求通知许可
-   当地图特性需要时, 由缩小位置升级到精确位置

## 文档

-   [Capgo 上的插件文件](https://capgo.app/docs/plugins/permissions/)
-   [教学:电容器-许可](https://capgo.app/plugins/capacitor-permissions/)
-   [Capgo 实时更新](https://capgo.app/?ref=plugin_permissions)

![Android emulator showing the camera permission dialog](https://npmcn.com/package/%40capgo/capacitor-permissions/screenshots/android-request.webp) ![Example app reporting camera permission as granted](https://npmcn.com/package/%40capgo/capacitor-permissions/screenshots/android-granted.webp)

## 兼容性

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

政策:

-   新的插件从版本开始 `8.0.0` (8号电站基线).
-   对更古老的Capacitor主机的后向相容性按需支持.

## 安装

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

与 Bun 键 :

```bash
bun add @capgo/capacitor-permissions
bunx cap sync
```

## iOS 设置

该插件不会在您的应用程序中注入使用描述 。 每笔 `PermissionName` 您在运行时调用, 将匹配的密钥添加到 `ios/App/App/Info.plist` (定制用户界面字符串):

| 权限 | Info.plist 密钥 |
| --- | --- |
| `camera` | `NSCameraUsageDescription` |
| `microphone` | `NSMicrophoneUsageDescription` |
| `photoLibrary` | `NSPhotoLibraryUsageDescription` |
| `photoLibraryAddOnly` | `NSPhotoLibraryAddUsageDescription` |
| `contacts` | `NSContactsUsageDescription` |
| `calendar` | `NSCalendarsUsageDescription`, (中文(简体) ), `NSCalendarsFullAccessUsageDescription` |
| `reminders` | `NSRemindersUsageDescription`, (中文(简体) ), `NSRemindersFullAccessUsageDescription` |
| `locationWhenInUse` | `NSLocationWhenInUseUsageDescription` |
| `locationAlways` | `NSLocationWhenInUseUsageDescription`, (中文(简体) ), `NSLocationAlwaysAndWhenInUseUsageDescription` |
| `bluetooth` | `NSBluetoothAlwaysUsageDescription` |
| `motion` | `NSMotionUsageDescription` |
| `speechRecognition` | `NSSpeechRecognitionUsageDescription`, (中文(简体) ), `NSMicrophoneUsageDescription` |
| `appTrackingTransparency` | `NSUserTrackingUsageDescription` |

`notifications` iOS上使用系统通知许可流;API本身不需要额外的使用字符串. 权限, 如 `activityRecognition`, (中文(简体) ), `phone`, (中文(简体) ), `sms`,而Android风格的媒体分割不适用于iOS和报告 `unavailable` 检查时.

您可以从插件 Repo 自动应用上面的密钥 :

```bash
node node_modules/@capgo/capacitor-permissions/scripts/apply-permissions.mjs \
  --project . \
  --permissions camera,microphone,notifications,locationWhenInUse,photoLibrary
```

(点 `--project` 在您的 Capacitor 应用程序根, 包含 `ios/` 财务报告和审定财务报表 `android/`. ) (中文(简体) )

## 机器人设置

图书馆 `AndroidManifest.xml` 声明 **没有** `<uses-permission>` 条目。 只添加您的应用程序的用途 `android/app/src/main/AndroidManifest.xml`。插件目标 **分数 24** (Android 7.0) 除非你的项目超过 `minSdkVersion`。 。 。 .

| 权限 | 典型 `uses-permission` 名称 |
| --- | --- |
| `camera` | `android.permission.CAMERA` |
| `microphone`, (中文(简体) ), `speechRecognition` | `android.permission.RECORD_AUDIO` |
| `photoLibrary`, (中文(简体) ), `mediaImages` | `READ_MEDIA_IMAGES`, (中文(简体) ), `READ_MEDIA_VISUAL_USER_SELECTED`, (中文(简体) ), `READ_EXTERNAL_STORAGE` (遗产) |
| `photoLibraryAddOnly` | `WRITE_EXTERNAL_STORAGE` (遗产) |
| `contacts` | `READ_CONTACTS` |
| `calendar` | `READ_CALENDAR`, (中文(简体) ), `WRITE_CALENDAR` |
| `locationWhenInUse` | `ACCESS_COARSE_LOCATION`, (中文(简体) ), `ACCESS_FINE_LOCATION` |
| `locationAlways` | 上加号数 `ACCESS_BACKGROUND_LOCATION` |
| `bluetooth` | `BLUETOOTH`, (中文(简体) ), `BLUETOOTH_ADMIN`, (中文(简体) ), `BLUETOOTH_CONNECT`, (中文(简体) ), `BLUETOOTH_SCAN` |
| `motion`, (中文(简体) ), `activityRecognition` | `ACTIVITY_RECOGNITION` |
| `notifications` | `POST_NOTIFICATIONS` (Android 13+) (韩语) |
| `phone` | `READ_PHONE_STATE` |
| `sms` | `READ_SMS`, (中文(简体) ), `RECEIVE_SMS` |
| `mediaAudio` | `READ_MEDIA_AUDIO`, (中文(简体) ), `READ_EXTERNAL_STORAGE` |
| `mediaVideo` | `READ_MEDIA_VIDEO`, (中文(简体) ), `READ_EXTERNAL_STORAGE` |

`reminders` 财务报告和审定财务报表 `appTrackingTransparency` 在此 API 中不是 Android 运行时间权限并返回 `unavailable`。 。 。 .

用同样的 `apply-permissions.mjs` 脚本 as on iOS 将声明合并到您的应用程序列表中 .

## 网络设置

无明显变化。 支持的权限使用 `navigator.permissions` 及相关的API(`camera`, (中文(简体) ), `microphone`, (中文(简体) ), `notifications`, (中文(简体) ), `locationWhenInUse`· ; `locationAlways` 仅用于前景地理定位的地图。 其他人员返回 `unavailable`。 。 。 . `openSettings` 未在网上执行.

## 使用量

```typescript
import { Permissions } from '@capgo/capacitor-permissions';

export async function ensureCamera(): Promise<boolean> {
  const { status } = await Permissions.check({ permission: 'camera' });
  if (status === 'granted') {
    return true;
  }
  const { status: afterRequest } = await Permissions.request({ permission: 'camera' });
  return afterRequest === 'granted';
}
```

在显示登入屏幕前检查多个权限 :

```typescript
const { statuses } = await Permissions.checkMultiple({
  permissions: ['camera', 'microphone', 'notifications'],
});
const missing = Object.entries(statuses).filter(([, s]) => s !== 'granted');
```

Android 报告时 `denied`,在再次请求前显示上下文:

```typescript
const { shouldShow } = await Permissions.shouldShowRationale({ permission: 'camera' });
if (shouldShow) {
  // Show your own explanation UI, then:
  await Permissions.request({ permission: 'camera' });
}
```

如果状态是 `blocked`,将用户发送到设置 :

```typescript
await Permissions.openSettings({ type: 'application' });
```

## 示例应用程序

这个 `example-app/` 项目练习 `PermissionName`应用声明,同步本地项目,然后:

```bash
cd example-app
bun install
bun run start
```

## API 密码

-   [`check(...)`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-check)
-   [`request(...)`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-request)
-   [`checkMultiple(...)`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-checkmultiple)
-   [`requestMultiple(...)`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-requestmultiple)
-   [`shouldShowRationale(...)`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-shouldshowrationale)
-   [`openSettings(...)`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-opensettings)
-   [`requestPreciseLocation()`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-requestpreciselocation)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-type-aliases)

Capacitor apps的跨平台权限 API.

### 检查(...)

```typescript
check(options: PermissionOptions) => Promise<PermissionStatusResult>
```

检查一个权限的当前状态而不提示用户 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PermissionOptions](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-permissionoptions)` |

**回返情况:** `Promise<[PermissionStatusResult](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-permissionstatusresult)>`

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

* * *

### 请求(...)

```typescript
request(options: PermissionOptions) => Promise<PermissionStatusResult>
```

请求用户允许 。 在Android上,在需要时显示系统对话框. 在iOS上,触发了被映射能力的平台授权流.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PermissionOptions](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-permissionoptions)` |

**回返情况:** `Promise<[PermissionStatusResult](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-permissionstatusresult)>`

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

* * *

### 检查复数(...)

```typescript
checkMultiple(options: MultiplePermissionOptions) => Promise<MultiplePermissionStatusResult>
```

检查多个权限而不提示 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[MultiplePermissionOptions](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-multiplepermissionoptions)` |

**回返情况:** `Promise<[MultiplePermissionStatusResult](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-multiplepermissionstatusresult)>`

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

* * *

### 请求复数(...)

```typescript
requestMultiple(options: MultiplePermissionOptions) => Promise<MultiplePermissionStatusResult>
```

依次请求多个权限, 因此对话框不会在相上方显示 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[MultiplePermissionOptions](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-multiplepermissionoptions)` |

**回返情况:** `Promise<[MultiplePermissionStatusResult](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-multiplepermissionstatusresult)>`

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

* * *

### 应显示理由(...)

```typescript
shouldShowRationale(options: PermissionOptions) => Promise<ShouldShowRationaleResult>
```

Android在再次请求之前是否应该显示一个理由. 回返 `{ shouldShow: false }` 在iOS和网络.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[PermissionOptions](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-permissionoptions)` |

**回返情况:** `Promise<[ShouldShowRationaleResult](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-shouldshowrationaleresult)>`

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

* * *

### 打开设置(...)

```typescript
openSettings(options?: OpenSettingsOptions | undefined) => Promise<void>
```

打开应用程序或通知设置屏幕. 在网络上拒绝 `UNIMPLEMENTED`。 。 。 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[OpenSettingsOptions](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-opensettingsoptions)` |

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

* * *

### 预览( )

```typescript
requestPreciseLocation() => Promise<PermissionStatusResult>
```

问确切位置. 在iOS上,当在使用时已经得到授权时,请求临时完全准确. Android上的请求 `ACCESS_FINE_LOCATION`。 。 。 . 网络上,在可能时提示后返回地理定位权限状态 .

**回返情况:** `Promise<[PermissionStatusResult](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-permissionstatusresult)>`

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

* * *

### 获取 PluginVersion ()

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

返回平台执行版本标记 .

**回返情况:** `Promise<[PluginVersionResult](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-pluginversionresult)>`

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

* * *

### 接口

#### 权限状态

实现单一许可状态.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`status`** | `[AppPermissionState](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-apppermissionstate)` | 请求许可的现状 . | 8.0.0 (单位:千美元) |

#### 权限选项

检查或请求单一许可的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`permission`** | `[PermissionName](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-permissionname)` | 评估或请求的逻辑权限 . | 8.0.0 (单位:千美元) |

#### 多重任务状态

多个许可状态的结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`statuses`** | `[Record](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-record)<string, [AppPermissionState](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-apppermissionstate)>` | 权限名称地图到状态 。 密钥符合传入的名称 `permissions`。 。 。 . | 8.0.0 (单位:千美元) |

#### 多选项

检查或请求多个权限的选项 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`permissions`** | `PermissionName[]` | 允许按顺序评估 。 打开 `requestMultiple`,每个许可都是一个接一个请求. | 8.0.0 (单位:千美元) |

#### 应显示理由

Android原理检查的结果.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`shouldShow`** | `boolean` | 只有当Android在再次请求前显示一个原理对话框时才是正确的. 总是在iOS和网络上作假. | 8.0.0 (单位:千美元) |

#### 打开设置选项

打开系统设置的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`type`** | `[SettingsType](https://npmcn.com/package/%40capgo/capacitor-permissions/#readme-settingstype)` | 要打开的设置屏幕 . | `'application'` | 8.0.0 (单位:千美元) |

#### 插件变压器

插件版本有效载荷 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`version`** | `string` | 平台执行返回的版本标识符(`native` 移动, `web` 在浏览器中). | 8.0.0 (单位:千美元) |

### 类型异名

#### Apppermission 状态

每个平台执行返回的规范化许可状态 .

-   `granted`:用户允许完全访问.
-   `denied`:用户尚未准许访问,或者Android可以显示一个理由.
-   `blocked`:用户拒绝访问,没有设置应用程序就无法再次提示.
-   `limited`: 部分访问(例如iOS有限相片库或降低位置精确度).
-   `unavailable`:该权限不在此平台上支持,或未在app express中声明.

`'granted' | 'denied' | 'blocked' | 'limited' | 'unavailable'`

#### 权限Name

逻辑权限标识符通过iOS,Android,和Web共享.

仅限机器人名称包括 `activityRecognition`, (中文(简体) ), `phone`, (中文(简体) ), `sms`, (中文(简体) ), `mediaAudio`, (中文(简体) ), `mediaImages`,以及 `mediaVideo`。 。 。 . 只有iOS 名称包含 `reminders` 财务报告和审定财务报表 `appTrackingTransparency`。 。 。 . Web 通过浏览器API支持子集(`camera`, (中文(简体) ), `microphone`, (中文(简体) ), `notifications`, (中文(简体) ), `locationWhenInUse`) (中文(简体) ). 网上, `locationAlways` 仅是前地地理定位的同名;浏览器不显示背景位置权限.

`'camera' | 'microphone' | 'photoLibrary' | 'photoLibraryAddOnly' | 'contacts' | 'calendar' | 'reminders' | 'locationWhenInUse' | 'locationAlways' | 'bluetooth' | 'motion' | 'notifications' | 'speechRecognition' | 'appTrackingTransparency' | 'activityRecognition' | 'phone' | 'sms' | 'mediaAudio' | 'mediaImages' | 'mediaVideo'`

#### 记录

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

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

#### 设置类型

设置屏幕类型 `openSettings`。 。 。 .

`'application' | 'notifications'`

## 常见问题

### @capgo/capacitor-permissions 是什么？

用于检查和请求应用权限的电容插件\.

### 如何安装 @capgo/capacitor-permissions？

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

### @capgo/capacitor-permissions 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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