ringtone（铃声服务）-ArkTS API-Ringtone Kit（铃声服务）-媒体

ringtone提供铃声设置的功能。

起始版本： 5.0.0(12)

导入模块

收起
自动换行
深色代码主题
复制
import { ringtone } from '@kit.RingtoneKit';

RingtoneType

Phone5.0.0(12)+Tablet5.0.0(12)+

描述铃声的类型枚举。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Ringtone.Core

起始版本： 5.0.0(12)

展开

名称	值	说明
CALL	0	来电铃声。
MESSAGE	1	信息铃声。
NOTIFICATION	2	通知铃声。
ALARM	3	闹钟铃声。

RingtoneErrors

Phone5.0.0(12)+Tablet5.0.0(12)+

该枚举为设置铃声，获取铃声支持类型和获取铃声支持文件类型等接口的错误码。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Ringtone.Core

起始版本： 5.0.0(12)

展开

名称	值	说明
ERROR_INVALID_PARAM	401	参数非法。
ERROR_USER_CANCELED	1011600001	用户取消。
ERROR_FILE_NOT_FOUND	1011600002	文件不存在。
ERROR_SHOW_FAILED	1011600003	铃声弹框失败。
ERROR_CALL_SYSTEM_API_FAILED	1011600004	调用系统接口失败。
ERROR_DATA_TYPE_NOT_MATCHED	1011600005	文件类型不匹配。起始版本： 26.0.0
ERROR_SYSTEM	1011699999	系统内部错误。

ringtone.getSupportedRingtoneTypes

Phone5.0.0(12)+Tablet5.0.0(12)+

getSupportedRingtoneTypes(): Array<RingtoneType>

查询当前系统支持自定义的铃声类型。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Ringtone.Core

起始版本： 5.0.0(12)

返回值：

展开

类型	说明
Array<RingtoneType>	当前系统支持自定义的铃声类型。

示例：

收起
自动换行
深色代码主题
复制
import { ringtone } from '@kit.RingtoneKit';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('查询当前系统支持自定义的铃声类型')
          .width(200)
          .height(50)
          .onClick(() => {
            let typeList: ringtone.RingtoneType[] = ringtone.getSupportedRingtoneTypes()
            hilog.info(DOMAIN, APP_TAG, `getSupportedRingtoneTypes: ${JSON.stringify(typeList)}`);
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedRingtoneTypes

Phone26.0.0+Tablet26.0.0+

getSupportedRingtoneTypes(mediaType: uniformTypeDescriptor.UniformDataType): Array<RingtoneType>

查询当前系统支持自定义的铃声类型。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Ringtone.Core

起始版本： 26.0.0

参数：

展开

参数名	类型	必填	说明
mediaType	uniformTypeDescriptor.UniformDataType	是	待查询的文件类型。

返回值：

展开

类型	说明
Array<RingtoneType>	当前系统支持自定义的铃声类型。

示例：

收起
自动换行
深色代码主题
复制
import { ringtone } from '@kit.RingtoneKit';
import { JSON } from '@kit.ArkTS';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('查询当前系统支持自定义的铃声类型')
          .width(200)
          .height(50)
          .onClick(() => {
            let typeList: ringtone.RingtoneType[] = ringtone.getSupportedRingtoneTypes(uniformTypeDescriptor.UniformDataType.AUDIO)
            hilog.info(DOMAIN, APP_TAG, `getSupportedRingtoneTypes: ${JSON.stringify(typeList)}`);
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedDataTypes

Phone5.0.0(12)+Tablet5.0.0(12)+

getSupportedDataTypes(ringtoneType: RingtoneType): Array<uniformTypeDescriptor.UniformDataType>

查询对应铃声类型支持的文件类型。

模型约束： 此接口仅可在Stage模型下使用。

系统能力：SystemCapability.Ringtone.Core

起始版本： 5.0.0(12)

参数：

展开

参数名	类型	必填	说明
ringtoneType	RingtoneType	是	待查询的铃声类型。

返回值：

展开

类型	说明
Array<uniformTypeDescriptor.UniformDataType>	返回对应铃声类型支持的文件类型。

错误码：

以下错误码的详细介绍请参见通用错误码。

展开

错误码ID	错误信息
401	Parameter error. Possible causes:ringtoneType is invalid.

示例：

收起
自动换行
深色代码主题
复制
import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('查询支持的文件类型')
          .width(200)
          .height(50)
          .onClick(() => {
            try {
              let typeList: uniformTypeDescriptor.UniformDataType[] =
                ringtone.getSupportedDataTypes(ringtone.RingtoneType.NOTIFICATION)
              hilog.info(DOMAIN, APP_TAG, `getSupportedDataType: ${JSON.stringify(typeList)}`);
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `getSupportedDataType error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedMaxDuration

Phone5.0.0(12)+Tablet5.0.0(12)+

getSupportedMaxDuration(ringtoneType: RingtoneType, dataType: uniformTypeDescriptor.UniformDataType): number

查询不同铃声类型和文件类型对应的文件时长上限。

模型约束： 此接口仅可在Stage模型下使用。

系统能力：SystemCapability.Ringtone.Core

起始版本： 5.0.0(12)

参数：

展开

参数名	类型	必填	说明
ringtoneType	RingtoneType	是	待查询的铃声类型。
dataType	uniformTypeDescriptor.UniformDataType	是	待查询的文件类型。

返回值：

展开

类型	说明
number	返回对应类型的铃声和文件支持的最大时长（单位：s），其中闹钟铃声时长为300s，短信铃声和通知铃声时长为7s，来电铃声时长为60s。

错误码：

以下错误码的详细介绍请参见通用错误码。

展开

错误码ID	错误信息
401	Parameter error. Possible causes:data type does not match the ringtone type.

示例：

收起
自动换行
深色代码主题
复制
import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('查询最大时长')
          .width(200)
          .height(50)
          .onClick(() => {
            try {
              let maxDuration: number =
                ringtone.getSupportedMaxDuration(ringtone.RingtoneType.MESSAGE,
                  uniformTypeDescriptor.UniformDataType.MP3)
              hilog.info(DOMAIN, APP_TAG, `getSupportedMaxDuration: ${maxDuration}`);
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `getSupportedMaxDuration error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.getSupportedMaxSize

Phone26.0.0+Tablet26.0.0+

getSupportedMaxSize(ringtoneType: RingtoneType, dataType: uniformTypeDescriptor.UniformDataType): number

查询不同铃声类型和文件类型对应的文件大小上限。

模型约束： 此接口仅可在Stage模型下使用。

系统能力：SystemCapability.Ringtone.Core

起始版本： 26.0.0

参数：

展开

参数名	类型	必填	说明
ringtoneType	RingtoneType	是	待查询的铃声类型。
dataType	uniformTypeDescriptor.UniformDataType	是	待查询的文件类型。

返回值：

展开

类型	说明
number	返回对应类型的铃声和文件支持的最大文件大小（单位：kb），其中视频大小限制200MB及以下，音频大小无限制返回-1。

错误码：

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

展开

错误码ID	错误信息
1011600005	The data type does not match the ringtone type.

示例：

收起
自动换行
深色代码主题
复制
import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { uniformTypeDescriptor } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  build() {
    Stack() {
      Column() {
        Button('查询文件大小限制')
          .width(200)
          .height(50)
          .onClick(() => {
            try {
              let maxSize: number =
                ringtone.getSupportedMaxSize(ringtone.RingtoneType.CALL,
                  uniformTypeDescriptor.UniformDataType.MP3)
              hilog.info(DOMAIN, APP_TAG, `getSupportedMaxSize: ${maxSize}`);
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `getSupportedMaxSize error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.startRingtoneSetting

Phone5.0.0(12)+Tablet5.0.0(12)+

startRingtoneSetting(context: common.UIAbilityContext, path: string, name: string, callback: AsyncCallback<RingtoneType>): void

拉起设置铃声弹窗，并返回点击的铃声类型，使用Callback异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力：SystemCapability.Ringtone.Core

起始版本： 5.0.0(12)

参数：

展开

参数名	类型	必填	说明
context	common.UIAbilityContext	是	UIAbility上下文。
path	string	是	具有访问权限的文件路径。
name	string	是	文件名，限制长度1000字符。
callback	AsyncCallback<RingtoneType>	是	回调函数。返回用户选择设置的铃声类型。

错误码：

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

展开

错误码ID	错误信息
401	Parameter error. Possible causes: context is invalid.
1011600001	User canceled.
1011600002	The media file is not found.
1011600003	Failed to show the dialog box.
1011600004	Failed to call the system API.
1011699999	System exception.

示例：

收起
自动换行
深色代码主题
复制
import { common } from '@kit.AbilityKit';
import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Stack() {
      Column() {
        Button('设为铃声OGG格式')
          .width(200)
          .height(50)
          .onClick(() => {
            let audioPath: string = this.context.filesDir + '/test.ogg'
            let splitList = audioPath.split('/')
            let fileName = splitList[splitList.length - 1]
            hilog.info(DOMAIN, APP_TAG, `audioPath: ${audioPath}`)
            hilog.info(DOMAIN, APP_TAG, `fileName: ${fileName}`)

            try {
              ringtone.startRingtoneSetting(this.context, audioPath, fileName, (err, res) => {
                hilog.info(DOMAIN, APP_TAG, `返回值：${JSON.stringify(res)}`)
              })
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `accessSync failed with error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}

ringtone.startRingtoneSetting

Phone5.0.0(12)+Tablet5.0.0(12)+

startRingtoneSetting(context: common.UIAbilityContext, path: string, name: string): Promise<RingtoneType>

拉起设置铃声弹窗，并返回点击的铃声类型，使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力：SystemCapability.Ringtone.Core

起始版本： 5.0.0(12)

参数：

展开

参数名	类型	必填	说明
context	common.UIAbilityContext	是	UIAbility上下文。
path	string	是	具有访问权限的文件路径。
name	string	是	文件名，限制长度1000字符。

返回值：

展开

类型	说明
Promise<RingtoneType>	Promise对象。返回用户选择设置的铃声类型。

错误码：

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

展开

错误码ID	错误信息
401	Parameter error. Possible causes: context is invalid.
1011600001	User canceled.
1011600002	The media file is not found.
1011600003	Failed to show the dialog box.
1011600004	Failed to call the system API.
1011699999	System exception.

示例：

收起
自动换行
深色代码主题
复制
import { common } from '@kit.AbilityKit';
import { ringtone } from '@kit.RingtoneKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { JSON } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

const APP_TAG = 'Msc_Demo'
const DOMAIN = 0x0001

@Entry
@Component
struct Index {
  private context = this.getUIContext().getHostContext() as common.UIAbilityContext;

  build() {
    Stack() {
      Column() {
        Button('设为铃声OGG格式')
          .width(200)
          .height(50)
          .onClick(() => {
            let audioPath: string = this.context.filesDir + '/test.ogg'
            let splitList = audioPath.split('/')
            let fileName = splitList[splitList.length - 1]
            hilog.info(DOMAIN, APP_TAG, `audioPath: ${audioPath}`)
            hilog.info(DOMAIN, APP_TAG, `fileName: ${fileName}`)

            try {
              ringtone.startRingtoneSetting(this.context, audioPath, fileName).then(res => {
                hilog.info(DOMAIN, APP_TAG, `返回值：${JSON.stringify(res)}`)
              })
            } catch (error) {
              let err: BusinessError = error as BusinessError;
              hilog.error(DOMAIN, APP_TAG,
                `accessSync failed with error message: ${err.message}, error code: ${err.code}`);
            }
          })
      }
      .width('100%')
      .height('100%')
      .backgroundColor(Color.Pink)
    }
    .height('100%')
    .width('100%')
  }
}