> 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/quan-xian.md).

# 权限

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

### API 列表

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

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

### withPermission

#### 功能说明

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

返回的函数还附带用于查询同一权限的 `getPermission()`和重新请求权限的 `openPermissionDialog()`作为静态方法附加。框架内部的 `Clipboard.getText`, `Device.getPhotos` 像这样的 API 由这个函数生成，因此 `Clipboard.getText.getPermission()` 可以以该形式检查权限。

#### 类型

**参数**

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

**响应**

```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` `` 格式。

#### 类型

**参数**

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

**响应**

```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`附加在由其包装的函数上的 `getPermission` 静态方法的签名。

#### 类型

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

### PermissionDialogFunction

#### 功能说明

`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/quan-xian.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.