插件权限

• 查询权限状态：hasPermission
• 申请权限：requestPermission

​

权限类型

​

如何声明权限

​

如何申请权限

1. 调用 hasPermission(permission) 查询当前状态：返回 1 表示已授权，可直接调用相关接口
2. 若返回 0（未授权），调用 requestPermission(permission, desc?) 发起申请：该权限还没有被设为”不允许”时，会弹出第 3 步的授权对话框；已经被设为”不允许”时，只会弹出第 4 步的前往设置提示
3. 用户在弹框中选择（默认选中”仅本次允许”）：
   • 仅本次允许：返回 1
   • 始终允许：返回 2
   • 不允许：返回 0
   • 点击 Cancel（未做选择）：本次没有任何授权，返回 -1，不会记成「不允许」。下次调用 requestPermission 会重新弹出三选一授权对话框
4. 如果用户此前已经选择过”不允许”，再次调用 requestPermission 会弹出提示框，引导用户前往系统设置修改；该提示框关闭后仍返回 0，不会重新触发三选一的授权流程

​

默认可访问范围

• 插件私有目录（/data/data/com.ratta.supernote.pluginhost/files/plugins/<pluginID>）：唯一默认免申请的路径，读取、写入、删除都不需要申请权限
• sdcard 下 Document/EXPORT/INBOX/MyStyle/Note/SCREENSHOT 这 6 个目录：默认不具备任何权限，读/写/删要分别申请 FILE:READ/FILE:WRITE/FILE:DELETE 后才能使用
• 外接 SD 卡、OTG 等外部存储设备：访问同样受 FILE:READ/FILE:WRITE/FILE:DELETE 权限管控，插件侧调用的是同一套 hasPermission/requestPermission 接口，不需要额外区分
• 除上述范围外的其他路径：无法通过申请权限获得访问能力

​

权限依赖一览

​

常见错误码

​

权限申请规范

• 每次进入插件或使用相关功能前，先调用 hasPermission。返回 1 表示已授予，直接调用相关接口，不需要再申请
• 返回 0 再调用 requestPermission，具体流程和返回值见如何申请权限

import { PluginManager, PluginFileAPI } from 'sn-plugin-lib';

/**
 * 读取指定笔记页内容前，确保插件已拥有 FILE:READ 权限：
 * 已授权则直接读取；未授权先申请，用户同意后再重试。
 */
export async function readPageElementsWithPermission(notePath: string, page: number) {
  const permission = 'plugin.permission.FILE:READ';

  const status = await PluginManager.hasPermission(permission);
  if (status !== 1) {
    const result = await PluginManager.requestPermission(permission, '需要读取权限来加载文件内容。');
    if (result !== 1 && result !== 2) {
      throw new Error('用户未授予读取权限');
    }
  }

  const res = await PluginFileAPI.getElements(page, notePath);
  if (!res?.success) {
    throw new Error(res?.error?.message ?? '读取文件失败');
  }
  return res.result ?? [];
}

• 仅本次允许：失效时机见上文如何申请权限中的说明。下次进入插件，或再次使用该功能时，如果没有再次调用 requestPermission，就不会弹出授权框，读取、写入会失败（错误码 1503、1501，见常见错误码），网络请求也会失败
• 始终允许：这个状态只能在设置里的插件管理中修改。已授予时 hasPermission 返回 1，不需要再调用 requestPermission，所以每次都检查不会重复弹框（本次进入内已经选了”仅本次允许”时同样如此）
• 不允许：只会弹出前往设置修改的提示框，不会再出现三选一，见如何申请权限第 4 步