# ElectronPermission

**Repository Path**: scenario-samples/electron-permission

## Basic Information

- **Project Name**: ElectronPermission
- **Description**: electron如何申请权限是公共关键技术类应用的高频使用场景之一，如读写文件、截屏、录音等。 本示例使用systemPreferences.requestDirectoryPermission(path)申请目录权限、systemPreferences.requestSystemPermission(permission)申请截屏权限，还使用systemPreferences.openAppli
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Electron如何申请权限

## 介绍
electron如何申请权限是公共关键技术类应用的高频使用场景之一，如读写文件、截屏、录音等。

本示例使用[systemPreferences.requestDirectoryPermission(path)](https://gitcode.com/openharmony-sig/electron#systempreferencesrequestdirectorypermissionpath)申请目录权限、[systemPreferences.requestSystemPermission(permission)](https://gitcode.com/openharmony-sig/electron#systempreferencesrequestsystempermissionpermission)申请截屏权限，还使用[systemPreferences.openApplicationInfoEntry()](https://gitcode.com/openharmony-sig/electron#systempreferencesopenapplicationinfoentry)提供跳转到“系统设置”中应用详细信息页面方便用户开启授权。
## 效果预览
<img src="screenshots/ElectronPermission.gif" width="400">

## 约束与限制

- 本示例支持API Version 20 Release及以上版本。
- 本示例支持HarmonyOS 6.0.0 Release SDK及以上版本。
- 本示例需要使用DevEco Studio 6.0.0 Release及以上版本进行编译运行。

## 使用说明

1. 点击“申请目录权限”按钮后，会弹出“是否允许直接访问文档文件夹”授权弹窗，点击允许后会获得文档文件夹的访问权限，点击不允许则授权失败。
2. 目录授权失败后，会显示“前往设置授权”按钮，点击按钮会跳转到“系统设置”中应用详细信息页面。
3. 点击“申请截屏权限”按钮后，会弹出“是否允许截取屏幕”授权弹窗，点击允许后获得截屏权限，点击不允许则授权失败。
4. 截屏授权失败后，会显示“前往设置授权”按钮，点击按钮会跳转到“系统设置”中应用详细信息页面。

## 实现思路
**1.权限申请：**

**1.1开放权限（系统授权）：**

针对[开放权限（系统授权）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all)只需要在`ohos_hap\web_engine\src\main\module.json5`配置文件的requestPermissions标签中声明权限。如下申请网络权限。
```
"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
  // ...
]
```

**1.2开放权限（用户授权）：**

[开放权限（用户授权）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all-user)主要分为两类：系统能力权限和目录访问类权限。
1. 对于截屏、麦克风、蓝牙、位置、剪贴板、相机等系统能力权限，使用[systemPreferences.requestSystemPermission(permission)](https://gitcode.com/openharmony-sig/electron#systempreferencesrequestsystempermissionpermission)申请相应权限。
   - 申请权限前，注意在module.json5文件中声明对应权限。对于HarmonyOS PC electron样例工程，须在`ohos_hap\web_engine\src\main\module.json5`文件的requestPermissions段声明。
     ```
     "requestPermissions": [
       {
         "name": "ohos.permission.CUSTOM_SCREEN_CAPTURE",
         "reason": "$string:screen_capture",
         "usedScene": {
           "abilities": [
             "FormAbility"
           ],
           "when":"always"
         }
       }
       // ...
     ]
     ```
   - 声明后，通过[systemPreferences.requestSystemPermission](https://gitcode.com/openharmony-sig/electron/blob/master/README.md#systempreferencesrequestsystempermissionpermission)方法可获得screen-capture等权限。
     ```
     const granted = await systemPreferences.requestSystemPermission('screen-capture');
     ```

1. 对于目录类访问权限，首先同样在`ohos_hap\web_engine\src\main\module.json5`文件的requestPermissions段声明对应权限。然后使用[systemPreferences.requestDirectoryPermission(path)](https://gitcode.com/openharmony-sig/electron#systempreferencesrequestdirectorypermissionpath)申请用户桌面、用户文档、下载目录访问权限。如果传入的path为空，则同时对请求三个目录权限。如下申请用户文档访问权限。

    ```
    const documentsPath = app.getPath('documents');
    let result = await systemPreferences.requestDirectoryPermission(documentsPath);
    ```

   下表列出了electron常用目录在HarmonyOS PC上对应的实际目录，以及对应的读写权限情况和是否可以通过[systemPreferences.requestDirectoryPermission(path)](https://gitcode.com/openharmony-sig/electron#systempreferencesrequestdirectorypermissionpath)获取读写权限。

   | API | 真实路径 | 目录作用 | 读写权限 |   
   |--|--| --| -- |
   |app.getAppPath()|/data/storage/el1/bundle/electron/resources/resfile/resources/app| electron代码运行时所在目录，即index.html/main.js所在目录 | 拥有读权限，没有写权限 |
   |app.getPath(home)|/storage/Users/currentUser| 当前用户家目录 | 应用无法通过权限申请获取读写权限 |
   |app.getPath(appData)|/data/storage/el2/base/files| 应用沙箱目录 | 无需用户手动同意授权，默认拥有读写权限 |
   |app.getPath(userData)|/data/storage/el2/base/files| 应用沙箱目录| 无需用户手动同意授权，默认拥有读写权限 |
   |app.getPath(sessionData)|/data/storage/el2/base/files| 应用沙箱目录| 无需用户手动同意授权，默认拥有读写权限 |
   |app.getPath(exe)|/data/storage/el1/bundle/electron/resources/resfile/electron| 执行文件目录，暂未发现用途 | 应用无法通过权限申请获取读写权限 |
   |app.getPath(desktop)|/storage/Users/currentUser/Desktop| 用户桌面 | 需要开发者主动申请用户授权并且用户同意后才拥有读写权限  |
   |app.getPath(documents)|/storage/Users/currentUser/Documents| 用户文档 | 需要开发者主动申请用户授权并且用户同意后才拥有读写权限 |
   |app.getPath(downloads)|/storage/Users/currentUser/Download| 下载目录| 需要开发者主动申请用户授权并且用户同意后才拥有读写权限。渲染进程中运行的下载逻辑，部分场景可自动触发弹框向用户申请下载目录读写权限  |
   |app.getPath(music)|/storage/Users/currentUser/Music| 音乐目录 |应用无法通过权限申请获取读写权限 |
   |app.getPath(pictures)|/storage/Users/currentUser/Pictures| 图片目录 |应用无法通过权限申请获取读写权限 |
   |app.getPath(videos)|/storage/Users/currentUser/Videos| 视频目录 | 应用无法通过权限申请获取读写权限 |
   |app.getPath(logs)|/data/storage/el2/base/files/logs| 沙箱中的日志目录，HarmonyOS Electron上未发现该目录 | 目录可自行创建，无需用户手动同意授权，默认拥有读写权限 |
   |app.getPath(crashDumps)|/data/storage/el2/base/files/Crashpad| 沙箱中的崩溃报告目录 | 无需用户手动同意授权，默认拥有读写权限 |

   此外还可以通过[dialog](https://www.electronjs.org/zh/docs/latest/api/dialog)拉起一个文件选择picker，获取相应文件/文件夹的读写权限。详情请参考[Harmony Electron如何进行读取、保存及持久化文件](https://developer.huawei.com/consumer/cn/forum/topic/0202203101204121705?fid=0109140870620153026)。

**1.3受限开放权限：**

针对悬浮窗（ohos.permission.SYSTEM_FLOAT_WINDOW）、读取联系人数据（ohos.permission.READ_CONTACTS）等[受限开放权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/restricted-permissions)，需要[申请受限权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/declare-permissions-in-acl)提供相关申请材料到应用市场（AppGallery Connect，简称为AGC）申请相应权限证书。

**2.权限管理：**

由于系统授权弹窗仅会弹出一次，为了便于用户开启或者取消授权，可以使用[systemPreferences.openApplicationInfoEntry()](https://gitcode.com/openharmony-sig/electron#systempreferencesopenapplicationinfoentry)跳转到“系统设置”中应用详细信息页面。或者用户前往“设置>应用和元服务”的应用详情页面中开启或者取消授权。
  ```
  await systemPreferences.openApplicationInfoEntry();
  ```

## 工程目录
```
ElectronPermission
├──module.json5           // 模块配置文件
└──app
    ├──preload            // 预加载模块
    │  └──preload.js      // 主窗口的预加载模块
    ├──renderer           // 渲染进程模块
    │  ├──renderer.js      
    │  └──index.html      // 主窗口加载的页面
    ├──main.js            // 主进程    
    ├──electron_white.png // 应用图标
    └──package.json       // 配置程序入口
```

## 参考文档
[systemPreferences.requestDirectoryPermission(path)](https://gitcode.com/openharmony-sig/electron#systempreferencesrequestdirectorypermissionpath)

[systemPreferences.requestSystemPermission(permission)](https://gitcode.com/openharmony-sig/electron#systempreferencesrequestsystempermissionpermission)

[systemPreferences.openApplicationInfoEntry()](https://gitcode.com/openharmony-sig/electron#systempreferencesopenapplicationinfoentry)

[开放权限（系统授权）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all)

[开放权限（用户授权）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all-user)

[受限开放权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/restricted-permissions)

[申请受限权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/declare-permissions-in-acl)

[dialog](https://www.electronjs.org/zh/docs/latest/api/dialog)