> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/permissions.md).

# 权限

提供设备权限（剪贴板·联系人·相册·摄像头·麦克风·位置）的查询·请求功能和权限错误类。

### API 列表

| API                                                                                                         | 说明        |
| ----------------------------------------------------------------------------------------------------------- | --------- |
| [`getPermission`](/documentation/api-and-sdk-zh/sdk/domains-api/permissions/getpermission.md)               | 查询权限的当前状态 |
| [`requestPermission`](/documentation/api-and-sdk-zh/sdk/domains-api/permissions/requestpermission.md)       | 请求权限并返回结果 |
| [`openPermissionDialog`](/documentation/api-and-sdk-zh/sdk/domains-api/permissions/openpermissiondialog.md) | 弹出权限设置对话框 |

权限错误类 7 种（`OpenCameraPermissionError` 等也一并提供——当需要权限的 API 被拒绝时，这些类的实例会被抛出。

### withPermission

#### 功能说明

包装需要权限的函数。调用被包装的函数时会先请求对应权限，若被拒绝则 `errorClass`传入的错误被抛出，允许时执行原函数。

返回的函数还会附带查询同一权限的 `getPermission()`和再次请求权限的 `openPermissionDialog()`作为静态方法。框架内部的 `Clipboard.getText`, `Device.getPhotos` 同样 API 是通过这个函数创建的，因此可以以 `Clipboard.getText.getPermission()` 这种形式检查权限。

#### 类型

**Params**

```ts
function withPermission<T extends (...args: any[]) => any>(
  fn: T, // 要在权限被允许后执行的函数
  name: PermissionName, // 要请求的权限名称
  access: PermissionAccess, // 要请求的访问类型
  errorClass: new () => PermissionErrorType, // 权限被拒绝时要抛出的错误类
): PermissionFunctionWithDialog<T>;
```

**Response**

```ts
type PermissionFunctionWithDialog<T extends (...args: any[]) => any> = T & {
  getPermission: GetPermissionFunction;
  openPermissionDialog: PermissionDialogFunction;
};
```

#### 错误

| 代码                | 说明                   |
| ----------------- | -------------------- |
| `errorClass`传入的错误 | 权限请求结果为 `denied`的情况。 |

#### 示例代码

```js
import {
  withPermission,
  OpenCameraPermissionError,
} from "@apps-in-toss/web-framework";

const captureWithCamera = withPermission(
  () => {
    // 摄像头权限被允许后执行的逻辑
  },
  "camera",
  "access",
  OpenCameraPermissionError,
);

try {
  await captureWithCamera();
} catch (error) {
  if (error instanceof OpenCameraPermissionError) {
    // 你也可以打开权限对话框重新请求。
    const status = await captureWithCamera.openPermissionDialog();
    console.log(status); // 'allowed' | 'denied'
    return;
  }
  console.error(error);
}
```

### PermissionError

#### 功能说明

权限错误的公共父类。需要一次处理多个权限错误时 `error instanceof PermissionError`即可确认。 `name`在 `` `${methodName} permission error` `` 格式。

#### 类型

**Params**

```ts
interface PermissionErrorConstructorParams {
  methodName: PermissionFunctionName;
  message: string;
}
```

**Response**

```ts
class PermissionError extends Error {
  name: string; // `${methodName} permission error`
  message: string;
}
```

#### 示例代码

```js
import { Clipboard, PermissionError } from "@apps-in-toss/web-framework";

try {
  const text = await Clipboard.getText();
  console.log(text);
} catch (error) {
  if (error instanceof PermissionError) {
    console.warn("权限被拒绝了：", error.message);
    return;
  }
  console.error(error);
}
```

### GetClipboardTextPermissionError

#### 功能说明

在读取剪贴板权限被拒绝时发生的错误。 `error instanceof GetClipboardTextPermissionError`即可确认。 `PermissionError`继承自

#### 类型

```ts
class GetClipboardTextPermissionError extends PermissionError {
  name: "getClipboardText permission error";
  message: "剪贴板读取权限被拒绝了。";
}
```

#### 示例代码

```js
import {
  Clipboard,
  GetClipboardTextPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const text = await Clipboard.getText();
  console.log(text);
} catch (error) {
  if (error instanceof GetClipboardTextPermissionError) {
    console.warn("没有剪贴板读取权限。");
  }
}
```

### SetClipboardTextPermissionError

#### 功能说明

在剪贴板写入权限被拒绝时发生的错误。 `error instanceof SetClipboardTextPermissionError`即可确认。 `PermissionError`继承自

#### 类型

```ts
class SetClipboardTextPermissionError extends PermissionError {
  name: "setClipboardText permission error";
  message: "剪贴板写入权限被拒绝了。";
}
```

#### 示例代码

```js
import {
  Clipboard,
  SetClipboardTextPermissionError,
} from "@apps-in-toss/web-framework";

try {
  await Clipboard.setText("要复制的文本");
} catch (error) {
  if (error instanceof SetClipboardTextPermissionError) {
    console.warn("没有剪贴板写入权限。");
  }
}
```

### FetchContactsPermissionError

#### 功能说明

在联系人权限被拒绝时发生的错误。 `error instanceof FetchContactsPermissionError`即可确认。 `PermissionError`继承自

#### 类型

```ts
class FetchContactsPermissionError extends PermissionError {
  name: "fetchContacts permission error";
  message: "联系人权限被拒绝了。";
}
```

#### 示例代码

```js
import {
  Device,
  FetchContactsPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const contacts = await Device.getContacts({ size: 10, offset: 0 });
  console.log(contacts);
} catch (error) {
  if (error instanceof FetchContactsPermissionError) {
    console.warn("没有联系人权限。");
  }
}
```

### FetchAlbumPhotosPermissionError

#### 功能说明

在相册权限被拒绝时发生的错误。 `error instanceof FetchAlbumPhotosPermissionError`即可确认。 `PermissionError`继承自

#### 类型

```ts
class FetchAlbumPhotosPermissionError extends PermissionError {
  name: "fetchAlbumPhotos permission error";
  message: "相册权限被拒绝了。";
}
```

#### 示例代码

```js
import {
  Device,
  FetchAlbumPhotosPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const photos = await Device.getPhotos();
  console.log(photos);
} catch (error) {
  if (error instanceof FetchAlbumPhotosPermissionError) {
    console.warn("没有相册权限。");
  }
}
```

### GetCurrentLocationPermissionError

#### 功能说明

在位置权限被拒绝时发生的错误。 `error instanceof GetCurrentLocationPermissionError`即可确认。 `PermissionError`继承自

#### 类型

```ts
class GetCurrentLocationPermissionError extends PermissionError {
  name: "getCurrentLocation permission error";
  message: "位置权限被拒绝了。";
}
```

#### 示例代码

```js
import {
  Accuracy,
  Device,
  GetCurrentLocationPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const location = await Device.getLocation({ accuracy: Accuracy.Balanced });
  console.log(location);
} catch (error) {
  if (error instanceof GetCurrentLocationPermissionError) {
    console.warn("没有位置权限。");
  }
}
```

### StartUpdateLocationPermissionError

#### 功能说明

在位置更新权限被拒绝时发生的错误。 `GetCurrentLocationPermissionError`因为它是指向相同类的别名， `error instanceof StartUpdateLocationPermissionError`是 `GetCurrentLocationPermissionError` 在实例上也 `true`。

#### 类型

```ts
const StartUpdateLocationPermissionError = GetCurrentLocationPermissionError;
```

#### 示例代码

```js
import {
  Accuracy,
  Device,
  StartUpdateLocationPermissionError,
} from "@apps-in-toss/web-framework";

const cleanup = Device.subscribeLocation({
  options: {
    accuracy: Accuracy.Balanced,
    timeInterval: 3000,
    distanceInterval: 10,
  },
  onEvent: (location) => {
    console.log(location);
  },
  onError: (error) => {
    if (error instanceof StartUpdateLocationPermissionError) {
      console.warn("没有位置权限。");
    }
    cleanup();
  },
});
```

### OpenCameraPermissionError

#### 功能说明

在摄像头权限被拒绝时发生的错误。 `error instanceof OpenCameraPermissionError`即可确认。 `PermissionError`继承自

#### 类型

```ts
class OpenCameraPermissionError extends PermissionError {
  name: "openCamera permission error";
  message: "摄像头权限被拒绝了。";
}
```

#### 示例代码

```js
import { Device, OpenCameraPermissionError } from "@apps-in-toss/web-framework";

try {
  const image = await Device.openCamera();
  console.log(image);
} catch (error) {
  if (error instanceof OpenCameraPermissionError) {
    console.warn("没有摄像头权限。");
  }
}
```

### PermissionName

#### 功能说明

用于识别权限的名称类型。

#### 类型

```ts
type PermissionName =
  | "clipboard" // 剪贴板
  | "contacts" // 联系人
  | "photos" // 相册
  | "geolocation" // 位置
  | "camera" // 摄像头
  | "microphone"; // 麦克风
```

### PermissionAccess

#### 功能说明

权限的访问类型。 `read`/`write`用于剪贴板·联系人·相册这类区分读/写的权限， `access`用于位置·摄像头·麦克风这类没有区分的权限。

#### 类型

```ts
type PermissionAccess = "read" | "write" | "access";
```

### PermissionStatus

#### 功能说明

权限状态类型。 `notDetermined`是用户尚未对权限请求作出回应的状态。

#### 类型

```ts
type PermissionStatus = "notDetermined" | "denied" | "allowed";
```

### PermissionFunctionName

#### 功能说明

发生权限错误的函数名称类型。 `PermissionError`中 `name`用于构成时。

#### 类型

```ts
type PermissionFunctionName =
  | "getClipboardText"
  | "setClipboardText"
  | "fetchContacts"
  | "fetchAlbumPhotos"
  | "getCurrentLocation"
  | "openCamera";
```

### PermissionErrorConstructorParams

#### 功能说明

`PermissionError` 传入构造函数的参数类型。

#### 类型

```ts
interface PermissionErrorConstructorParams {
  methodName: PermissionFunctionName;
  message: string;
}
```

### PermissionErrorType

#### 功能说明

`withPermission`中 `errorClass` 参数生成的错误实例的形态。

#### 类型

```ts
interface PermissionErrorType extends Error {
  name: string;
  message: string;
}
```

### GetPermissionFunction

#### 功能说明

`withPermission`被 \`withPermission\` 包装的函数上附带的 `getPermission` 静态方法签名。

#### 类型

```ts
type GetPermissionFunction = () => Promise<PermissionStatus>;
```

### PermissionDialogFunction

#### 功能说明

`withPermission`被 \`withPermission\` 包装的函数上附带的 `openPermissionDialog` 静态方法签名。

#### 类型

```ts
type PermissionDialogFunction = () => Promise<
  Exclude<PermissionStatus, "notDetermined">
>;
```

### PermissionFunctionWithDialog

#### 功能说明

`withPermission`所返回的函数类型。是原函数签名上 `getPermission`/`openPermissionDialog` 加上静态方法的形式。

#### 类型

```ts
type PermissionFunctionWithDialog<T extends (...args: any[]) => any> = T & {
  getPermission: GetPermissionFunction;
  openPermissionDialog: PermissionDialogFunction;
};
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/permissions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.