---
title: "request"
description: "请求一个已注册权限，并返回本次是否授权成功。"
---


> 请求一个已注册权限，并返回本次是否授权成功。

## 签名

```ts
KSM.permission.request(permission: string): Promise<{ granted: boolean }>
```

参数是位置字符串，不是 `{ permission }` 对象。

## 平台与权限

| Windows | Android |权限 |
| --- | --- | --- |
|支持 |支持 |无 |

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `permission` | `string` |是 | `KSM_PERMISSIONS` 中的权限名 |

## 返回值

|字段 |类型 |说明 |
| --- | --- | --- |
| `granted` | `boolean` |本次请求后权限是否可用 |

## 行为

- Windows 对已知权限直接返回 `true`，并写入当前路由器的权限集合。
- Android 的 `notification.show` 在 Android13 及以上请求 `POST_NOTIFICATIONS`。
- Android 其他已注册权限当前直接返回 `true`。
- Android 用户拒绝时，对应命令返回 `PERMISSION_DENIED`。
- 同一时间已有 Android 权限请求未完成时，新请求返回 `{ granted: false }`。
- Android 宿主内部最多等待 60 秒，但前端默认 10 秒请求超时会先拒绝为 `TIMEOUT`；
系统权限对话框可能仍然存在，宿主会抑制迟到结果。
- 请求不会自动刷新 `capabilities()` 缓存。

## 示例

```ts
const { granted } = await KSM.permission.request('notification.show');

if (granted) {
  await KSM.notification.show({
    title: 'Kasumi',
    body: '通知权限已就绪'
  });
}
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` | `permission` 不是字符串 |
| `INVALID_ARGS` |权限名未注册 |
| `NOT_SUPPORTED` |宿主没有配置权限服务 |
| `TIMEOUT` |宿主未在默认时间内响应 |

## 相关

- [notification.show](/docs/kasumi/api/notification/show)
- [permission 模块](/docs/kasumi/api/permission)