权限

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

API 列表

API	说明
getPermission	查询权限的当前状态
requestPermission	请求权限并返回结果
openPermissionDialog	弹出权限设置对话框

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

withPermission

功能说明

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

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

类型

Params

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

Response

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

错误

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

示例代码

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

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

Response

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

示例代码

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继承自

类型

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

示例代码

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继承自

类型

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

示例代码

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继承自

类型

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

示例代码

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继承自

类型

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

示例代码

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继承自

类型

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

示例代码

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。

类型

const StartUpdateLocationPermissionError = GetCurrentLocationPermissionError;

示例代码

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继承自

类型

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

示例代码

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

功能说明

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

类型

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

PermissionAccess

功能说明

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

类型

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

PermissionStatus

功能说明

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

类型

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

PermissionFunctionName

功能说明

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

类型

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

PermissionErrorConstructorParams

功能说明

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

类型

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

PermissionErrorType

功能说明

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

类型

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

GetPermissionFunction

功能说明

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

类型

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

PermissionDialogFunction

功能说明

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

类型

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

PermissionFunctionWithDialog

功能说明

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

类型

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