【小程序】基础API之系统API接口汇总

ty.env

环境变量

属性

USER_DATA_PATH string

文件系统中的用户目录路径 (本地路径)，当操作文件时需使用此目录。

// 写入一个文件
const fileManager = await ty.getFileSystemManager();
const fileRoot = ty.env.USER_DATA_PATH;
const filePath = `${fileRoot}/test.json`
await fileManager.writeFile({
  filePath: filePath,
  data: `{"test": "test"}`,
});
 
// 分享该文件
ty.share({
  title: '分享一个文件',
  message: '这是一个 JSON 文件，调用系统分享',
  type: 'More',
  filePath: filePath,
  contentType: 'file',
  success() {
    console.log('分享成功');
  },
  fail(err) {
    console.log('分享失败', err);
  },
});

其他文件操作方法请参考 FileSystemManager。

ty.getSystemInfo

获取系统信息

需引入BaseKit，且在>=1.2.10版本才可使用

参数

Object object

属性	类型	默认值	必填	说明
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

object.success 回调参数

参数

Object res

属性	类型	说明
is24Hour	boolean
system	string
brand	string
model	string
platform	string
timezoneId	string
pixelRatio	number
screenWidth	number
screenHeight	number
windowWidth	number
windowHeight	number
statusBarHeight	number
language	string
safeArea	SafeArea
albumAuthorized	boolean
cameraAuthorized	boolean
locationAuthorized	boolean
microphoneAuthorized	boolean
notificationAuthorized	boolean
notificationAlertAuthorized	boolean
notificationBadgeAuthorized	boolean
notificationSoundAuthorized	boolean
bluetoothEnabled	boolean
locationEnabled	boolean
wifiEnabled	boolean
theme	Themes
deviceOrientation	Orientation

SafeArea

属性	类型	说明
left	number	安全区域左上角横坐标
right	number	安全区域右下角横坐标
top	number	安全区域左上角纵坐标
bottom	number	安全区域右下角纵坐标
width	number	安全区域的宽度，单位逻辑像素
height	number	安全区域的高度，单位逻辑像素

object.fail 回调参数

参数

Object res

属性	类型	说明
errorMsg	string	插件错误信息
errorCode	string	错误码
innerError	object	插件外部依赖错误信息 {errorMsg: string, errorCode: string }

函数定义示例

/**
 * 获取系统信息
 */
export function getSystemInfo(params?: {
  complete?: () => void;
  success?: (params: {
    is24Hour: boolean;
    system: string;
    brand: string;
    model: string;
    platform: string;
    timezoneId: string;
    pixelRatio: number;
    screenWidth: number;
    screenHeight: number;
    windowWidth: number;
    windowHeight: number;
    statusBarHeight: number;
    language: string;
    safeArea: SafeArea;
    albumAuthorized: boolean;
    cameraAuthorized: boolean;
    locationAuthorized: boolean;
    microphoneAuthorized: boolean;
    notificationAuthorized: boolean;
    notificationAlertAuthorized: boolean;
    notificationBadgeAuthorized: boolean;
    notificationSoundAuthorized: boolean;
    bluetoothEnabled: boolean;
    locationEnabled: boolean;
    wifiEnabled: boolean;
    theme?: Themes;
    deviceOrientation?: Orientation;
  }) => void;
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

ty.getSystemInfoSync

获取系统信息同步方法

需引入BaseKit，且在>=1.2.10版本才可使用

ty.getSystemInfo 的同步版本

返回值

属性	类型	说明
is24Hour	boolean
system	string
brand	string
model	string
platform	string
timezoneId	string
pixelRatio	number
screenWidth	number
screenHeight	number
windowWidth	number
windowHeight	number
statusBarHeight	number
language	string
safeArea	SafeArea
albumAuthorized	boolean
cameraAuthorized	boolean
locationAuthorized	boolean
microphoneAuthorized	boolean
notificationAuthorized	boolean
notificationAlertAuthorized	boolean
notificationBadgeAuthorized	boolean
notificationSoundAuthorized	boolean
bluetoothEnabled	boolean
locationEnabled	boolean
wifiEnabled	boolean
theme	Themes
deviceOrientation	Orientation

SafeArea

属性	类型	说明
left	number	安全区域左上角横坐标
right	number	安全区域右下角横坐标
top	number	安全区域左上角纵坐标
bottom	number	安全区域右下角纵坐标
width	number	安全区域的宽度，单位逻辑像素
height	number	安全区域的高度，单位逻辑像素

函数定义示例

/**
 * 获取系统信息
 */
export function getSystemInfoSync(): {
  is24Hour: boolean;
  system: string;
  brand: string;
  model: string;
  platform: string;
  timezoneId: string;
  pixelRatio: number;
  screenWidth: number;
  screenHeight: number;
  windowWidth: number;
  windowHeight: number;
  statusBarHeight: number;
  language: string;
  safeArea: SafeArea;
  albumAuthorized: boolean;
  cameraAuthorized: boolean;
  locationAuthorized: boolean;
  microphoneAuthorized: boolean;
  notificationAuthorized: boolean;
  notificationAlertAuthorized: boolean;
  notificationBadgeAuthorized: boolean;
  notificationSoundAuthorized: boolean;
  bluetoothEnabled: boolean;
  locationEnabled: boolean;
  wifiEnabled: boolean;
  theme?: Themes;
  deviceOrientation?: Orientation;
};

ty.getSystemSetting

获取设备设置

需引入BaseKit，且在>=2.5.0版本才可使用

参数

Object object

属性	类型	默认值	必填	说明
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

object.success 回调参数

参数

Object res

属性	类型	说明
bluetoothEnabled	boolean	蓝牙的系统开关，默认 false
locationEnabled	boolean	地理位置的系统开关，默认 false
wifiEnabled	boolean	Wi-Fi 的系统开关，默认 false
deviceOrientation	string	设备方向, 默认竖屏 竖屏 = "portrait"， 横屏 = "landscape"

object.fail 回调参数

参数

Object res

属性	类型	说明
errorMsg	string	插件错误信息
errorCode	string	错误码
innerError	object	插件外部依赖错误信息 {errorMsg: string, errorCode: string }

函数定义示例

/**
 * 获取设备设置
 */
export function getSystemSetting(params?: {
  complete?: () => void;
  success?: (params: {
    /** 蓝牙的系统开关，默认false */
    bluetoothEnabled?: boolean;
    /** 地理位置的系统开关，默认false */
    locationEnabled?: boolean;
    /** Wi-Fi 的系统开关，默认false */
    wifiEnabled?: boolean;
    /**
     * 设备方向, 默认竖屏
     * 竖屏 = "portrait"， 横屏 = "landscape"
     */
    deviceOrientation?: string;
  }) => void;
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

ty.getDeviceInfo

获取设备基础信息

需引入BaseKit，且在>=2.4.3版本才可使用

参数

Object object

属性	类型	默认值	必填	说明
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

object.success 回调参数

参数

Object res

属性	类型	说明
abi	string	应用二进制接口类型（仅 Android 支持）
brand	string	设备品牌
model	string	设备型号。新机型刚推出一段时间会显示 unknown。
system	string	操作系统及版本
platform	string	客户端平台

object.fail 回调参数

参数

Object res

属性	类型	说明
errorMsg	string	插件错误信息
errorCode	string	错误码
innerError	object	插件外部依赖错误信息 {errorMsg: string, errorCode: string }

函数定义示例

/**
 * 获取设备基础信息
 */
export function getDeviceInfo(params?: {
  complete?: () => void;
  success?: (params: {
    /** 应用二进制接口类型（仅 Android 支持） */
    abi: string;
    /** 设备品牌 */
    brand: string;
    /** 设备型号。新机型刚推出一段时间会显示unknown。 */
    model: string;
    /** 操作系统及版本 */
    system: string;
    /** 客户端平台 */
    platform: string;
  }) => void;
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

ty.openSystemBluetoothSetting

跳转系统蓝牙设置页 (仅 Android)

需引入BaseKit，且在>=2.4.3版本才可使用

参数

Object object

属性	类型	默认值	必填	说明
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

函数定义示例

/**
 * 跳转系统蓝牙设置页 (仅Android)
 */
export function openSystemBluetoothSetting(params?: {
  complete?: () => void;
  success?: (params: null) => void;
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

ty.updateVolume

设置系统音量

错误码标注 入参值范围超出 errorCode = 6， The volume value is invalid, it should be [0 - 1]

需引入BaseKit，且在>=2.4.3版本才可使用

参数

Object object

属性	类型	默认值	必填	说明
value	number		是	音量，阈值【0 - 1】
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

函数定义示例

/**
 * 设置系统音量
 *
 *错误码标注
 *入参值范围超出 errorCode = 6， The volume value is invalid, it should be [0 - 1]
 */
export function updateVolume(params: {
  /** 音量，阈值【0 - 1】 */
  value: number;
  complete?: () => void;
  success?: (params: null) => void;
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

ty.handleShortcut

操作快捷方式，包括添加和移除, 仅 iOS

需引入BizKit，且在>=3.1.1版本才可使用。

参数

Object object

属性	类型	默认值	必填	说明
type	number		是	操作类型。0-添加、1-移除
sceneId	string		是	场景 ID
name	string		是	场景名称
iconUrl	string		否	场景 Logo
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

object.success 回调参数

参数

Object res

属性	类型	说明
operationStep	number	操作步骤，0-添加、1-移除、2-更新、3-取消
operationStatus	boolean	操作状态，YES，表示成功；NO，表示失败

object.fail 回调参数

参数

Object res

属性	类型	说明
errorMsg	string	插件错误信息
errorCode	string	错误码
innerError	object	插件外部依赖错误信息 {errorMsg: string, errorCode: string }

函数定义示例

/**
 * 操作快捷方式，包括添加和移除, 仅 iOS
 */
export function handleShortcut(params: {
  /** 操作类型。0-添加、1-移除 */
  type: number;
  /** 场景 ID */
  sceneId: string;
  /** 场景名称 */
  name: string;
  /** 场景 Logo */
  iconUrl?: string;
  /** 接口调用结束的回调函数（调用成功、失败都会执行） */
  complete?: () => void;
  /** 接口调用成功的回调函数 */
  success?: (params: {
    /** 操作步骤，0-添加、1-移除、2-更新、3-取消 */
    operationStep: number;
    /** 操作状态，YES，表示成功；NO，表示失败 */
    operationStatus: boolean;
  }) => void;
  /** 接口调用失败的回调函数 */
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

ty.isAssociatedShortcut

获取是否关联 siri 状态, 仅 iOS

需引入BizKit，且在>=3.1.1版本才可使用。

参数

Object object

属性	类型	默认值	必填	说明
sceneId	string		是	场景 ID
name	string		否	场景名称
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

object.success 回调参数

参数

Object res

属性	类型	说明
isAssociated	boolean	是否已关联

object.fail 回调参数

参数

Object res

属性	类型	说明
errorMsg	string	插件错误信息
errorCode	string	错误码
innerError	object	插件外部依赖错误信息 {errorMsg: string, errorCode: string }

函数定义示例

/**
 * 获取是否关联 Siri 状态, 仅 iOS
 */
export function isAssociatedShortcut(params: {
  /** 场景 ID */
  sceneId: string;
  /** 场景名称 */
  name?: string;
  /** 接口调用结束的回调函数（调用成功、失败都会执行） */
  complete?: () => void;
  /** 接口调用成功的回调函数 */
  success?: (params: {
    /** 是否已关联 */
    isAssociated: boolean;
  }) => void;
  /** 接口调用失败的回调函数 */
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

ty.isSupportedShortcut

是否支持 Siri, 仅 iOS

需引入BizKit，且在>=3.1.1版本才可使用。

参数

Object object

属性	类型	默认值	必填	说明
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数

object.success 回调参数

参数

Object res

属性	类型	说明
isSupported	boolean	是否支持

object.fail 回调参数

参数

Object res

属性	类型	说明
errorMsg	string	插件错误信息
errorCode	string	错误码
innerError	object	插件外部依赖错误信息 {errorMsg: string, errorCode: string }

函数定义示例

/**
 * 是否支持 Siri, 仅 iOS
 */
export function isSupportedShortcut(params?: {
  /** 接口调用结束的回调函数（调用成功、失败都会执行） */
  complete?: () => void;
  /** 接口调用成功的回调函数 */
  success?: (params: {
    /** 是否支持 */
    isSupported: boolean;
  }) => void;
  /** 接口调用失败的回调函数 */
  fail?: (params: {
    errorMsg: string;
    errorCode: string | number;
    innerError: {
      errorCode: string | number;
      errorMsg: string;
    };
  }) => void;
}): void;

  立即开发。