多媒体 media

接口声明

{ "name": "system.media" }

导入模块

import media from '@system.media' 或 const media = require('@system.media')

接口定义

media.takePhoto(OBJECT)

拍摄照片

权限要求

使用相机

参数：

success 返回值：

fail 返回错误代码：

示例：

media.takePhoto({
  success: function(data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  }
})

media.takeVideo(OBJECT)

拍摄视频

权限要求

使用相机

参数：

success 返回值：

fail 返回错误代码

示例：

media.takeVideo({
  success: function(data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  }
})

media.pickImage(OBJECT)

选择图片

权限要求

读手机存储

参数：

success 返回值：

示例：

media.pickImage({
  success: function(data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

media.pickImages(OBJECT) 1040+

选择多张图片

权限要求

读手机存储

参数：

success 返回值：

file 对象如下：

示例：

media.pickImages({
  success: function(data) {
    console.log(`handling success: ${data.uris}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

media.pickVideo(OBJECT)

选择视频

权限要求

读手机存储

参数：

success 返回值：

示例：

media.pickVideo({
  success: function(data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

media.pickVideos(OBJECT) 1040+

选择多个视频

权限要求

读手机存储

参数：

success 返回值：

file 对象如下：

示例：

media.pickVideos({
  success: function(data) {
    console.log(`handling success: ${data.uris}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

media.pickFile(OBJECT)1010+

选择文件

权限要求

读手机存储

参数：

success 返回值：

示例：

media.pickFile({
  success: function(data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

media.saveToPhotosAlbum(OBJECT)1010+

将图片/视频保存到相册中

注：从1080版本开始，图片和视频的保存路径发生了改变，以图片为例，规则如下：（视频场景下 Pictures 目录改为 Movies 即可）

快应用包名：manifest.json 的package属性值

快应用的应用名： manifest.json 的name属性值

1.没有设置 folderName

图片保存地址格式：sdcard/Pictures/"快应用包名"/"快应用的应用名"/xxx.jpg

2.手动设置了 folderName

图片保存地址格式：sdcard/Pictures/"快应用包名"/"folderName"/yyy.jpg

另外，从1090版本开始，Android 10+系统且硬件能力支持的机器，可以保存HEIF/HEIC类照片

权限要求

写手机存储

参数：

fail 返回错误代码：

示例：

media.pickImage({
  success: data => {
    const imagePath = data.uri
    if (imagePath && imagePath.length > 0) {
      media.saveToPhotosAlbum({
        uri: imagePath,
        folderName: 'custom-folder',
        success: function() {
          console.log(`已保存图片于自定义目录：custom-folder`)
        },
        fail: function(data, code) {
          console.log(`保存图片失败, 错误码：${code}`)
        }
      })
    }
  },
  fail: function(data, code) {
    console.log(`选择图片失败, 错误码：${code}`)
  }
})

media.previewImage(OBJECT)1040+

预览图片，调用之后会在新打开的页面中全屏预览传入的图片，预览的过程中用户可以左右滑动浏览，可以通过双指缩放图片，可以保存图片到相册。

权限要求

写手机存储

参数：

示例：

media.previewImage({
  current: 'http://www.xxx.com/a.jpg',
  uris: [
    'http://www.xxx.com/a.jpg',
    'http://www.xxx.com/b.jpg',
    'http://www.xxx.com/c.jpg'
  ],
  success: function() {
    console.log('preview success')
  },
  fail: function(data, code) {
    console.log('preview fail, code = ${code}')
  }
})

media.getRingtone(OBJECT) 1040+

获取系统铃声。如果是获取来电铃声，双卡情况下，获取的是卡 1 对应的铃声。

权限要求

读手机存储

参数：

success 返回值：

fail 返回错误代码：

示例：

media.getRingtone({
  type: 'ringtone',
  success: function(data) {
    console.log(`get ringtone success title: ${data.title}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

media.setRingtone(OBJECT) 1040+

设置系统铃声，目前只支持本地文件。如果是设置来电铃声，双卡情况下，卡 1 卡 2 对应的铃声都会设置。

权限要求

写手机存储。而且每次设置铃声时，都有弹框来让用户选择是否同意设置铃声。

参数：

fail 返回错误代码：

示例：

media.setRingtone({
  type: 'ringtone',
  uri: 'internal://mass/test/test.mp3',
  title: 'test',
  success: function() {
    console.log(`set ringtone success`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  }
})

后台运行限制

1090版本之前，所有system.meida接口的方法均无法后台运行。

从1090版本开始，system.meida的saveToPhotosAlbum方法支持后台运行，且不需要与其他后台运行接口一样，在 manifest.json 里配置 background 参数。

其他方法仍不支持后台运行。