【小程序】基础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;立即开发。