chrome.mediaGalleries

描述：	使用 `chrome.mediaGalleries` API （在用户允许的前提下）访问用户本地磁盘中的媒体文件（音频、图片、视频）。
可用版本：	从 Chrome 23 开始支持。
权限：	{"mediaGalleries": ["accessType1", "accessType2", ...]} {"mediaGalleries": ["accessType1", "accessType2", ..., "allAutoDetected"]} 有关更多信息，请参见下面的清单文件部分。
了解更多：	Chrome 浏览器办公时间：媒体库 API

用法

媒体库 API 让您提示用户，请求访问用户计算机上媒体库的权限。权限对话框包含当前平台上常用的媒体位置，并允许用户指定其他位置。在这些位置中，只有媒体文件才会在文件系统对象中出现。

清单文件

媒体库 API 有两种权限参数：

可以访问的位置
访问类型

这两种类型以及每一种类型的权限参数如下表所述：

类型	参数	效果
位置	无	如果您不指定位置权限参数，只有在运行时用户使用媒体库权限对话框授予访问指定媒体库的权限后，才能访问媒体库。
位置	"allAutoDetected"	授予您的应用访问用户计算机上所有自动检测到的媒体库的权限，该权限使得应用安装时显示提示，表示应用可以访问用户的媒体文件。
访问类型	"read"	授予您的应用读取媒体库文件的权限。
	"delete"	授予您的应用从媒体库删除文件的权限，"read" 权限是 "delete" 的前提条件，同时指定 "read" 与 "delete" 获得这两种访问媒体库的权限。
	"copyTo"	授予您的应用向媒体库复制文件的权限，只允许 Chrome 浏览器能够播放或显示的有效媒体文件，复制 Chrome 浏览器无法验证的文件将导致安全错误。"read" 与 "delete" 权限是 "copyTo" 的前提条件，同时指定 "read"、"delete" 和 "copyTo" 获得媒体库的所有访问权限。

注意：

媒体库权限对话框可以以编程方式触发。用户可能还有其他媒体位置，所以即使您指定了 "allAutoDetected" 权限，您也应当在您的应用中提供某种方式打开权限对话框。
由于文件验证的要求，没有对媒体库的写入权限。然而，您可以将文件写入另一个文件系统，如临时文件系统，然后将这些文件复制到期望的媒体库中。
访问类型权限本身不会触发安装时的提示，但是访问类型会在媒体库权限对话框和安装时的提示（如果请求了 "allAutoDetected" 权限）中反映出来

如下是指定媒体库权限的清单文件的例子：

      {
        "name": "我的应用",
        ...
        "permissions": [
          { "mediaGalleries": ["read", "allAutoDetected"] }
        ],
        ...
      }

这一清单文件的例子在安装时会触发权限提示，让应用读取用户计算机上所有自动检测到的媒体库。用户可以使用媒体库权限对话框添加或删除库，之后应用就能够读取用户选择的库中的所有媒体文件。

iTunes

如果存在，用户的 iTunes 库可以作为媒体库访问。除了库中的媒体文件，“iTunes Music Library.xml”文件也会存在。

无论音乐文件在磁盘上的什么位置（以及 XML 文件中包含的位置），默认情况下它们都会被映射至艺术家/唱片集/音轨这样的结构。这种映射方式有时候并不完美，所以如果应用需要将 XML 文件与媒体库中的文件配对的话，需要注意两点。

如果唱片集中的音轨文件名不唯一，在扩展名之前会加上包含括号的音轨号，使它们唯一。如果艺术家、唱片集或音轨名称中包含冒号或斜杠，它们会变成下划线。

Picasa

如果存在的话，用户的 Picasa 库也可以作为媒体库访问。Picasa 扫描的文件系统目录呈现在 folders/ 中，Picasa 相册呈现在 albums/ 中。

如果相册和文件夹具有相同的名称与日期，在扩展名前会加上包含括号的增量整数，使它们唯一。

同一相册中如果有相同的文件名，也会在扩展名前加上包含括号的增量整数使之唯一。

iPhoto

如果存在的话，用户的 iPhoto 库也可以作为媒体库访问。这些文件存放在名为“Albums/”的子目录中。在这一子目录中，用户 iPhoto 库中的每一个相册都按照各自的名称以子目录形式呈现，并且包含相册中的照片对应的文件项。

如果相册名重复或相册中图片文件名重复，在文件名后就会附加不重复的后缀，如“(NN)”，其中 NN 是唯一的数值。

在 iPhoto 的多个相册中出现的项目也会在媒体库中对应相册中出现。

如果用户修改了相册中的图片，相册目录中就会有另外一个名为“originals/”的子目录，它包含原始的图片，与上级相册目录中的文件名相同，而出现在上级相册目录中的文件则是用户进行裁剪、旋转等编辑操作之后的图片。

摘要

方法
getMediaFileSystems − `chrome.mediaGalleries.getMediaFileSystems(object details, function callback)`
addUserSelectedFolder − `chrome.mediaGalleries.addUserSelectedFolder(function callback)`
dropPermissionForMediaFileSystem − `chrome.mediaGalleries.dropPermissionForMediaFileSystem(string galleryId, function callback)`
startMediaScan − `chrome.mediaGalleries.startMediaScan()`
cancelMediaScan − `chrome.mediaGalleries.cancelMediaScan()`
addScanResults − `chrome.mediaGalleries.addScanResults(function callback)`
getMediaFileSystemMetadata − `object chrome.mediaGalleries.getMediaFileSystemMetadata(DOMFileSystem mediaFileSystem)`
getAllMediaFileSystemMetadata − `chrome.mediaGalleries.getAllMediaFileSystemMetadata(function callback)`
getMetadata − `chrome.mediaGalleries.getMetadata(Blob mediaFile, object options, function callback)`
事件
onGalleryChanged
onScanProgress

方法

getMediaFileSystems


              chrome.mediaGalleries.getMediaFileSystems(object details, function callback)

获取当前用户代理配置下的媒体库。如果没有配置或者没有可用的媒体库，回调函数将会接收空数组。

参数

object

（可选）
details

enum of "no", "yes", or "if_needed"

（可选）
interactive

返回允许的内容前是否提示用户访问其他媒体库的权限，默认情况下不提示。如果传递了 'yes'，或者如果应用没有被授予访问任何媒体库的权限并且传递了 'if_needed'，则会显示媒体库配置对话框。

no: 不要交互式地进行。

yes: 询问用户管理允许的媒体库。

if_needed: 只有当返回值会为空时才询问用户管理允许的媒体库。

function

callback

callback 参数应该是一个如下形式的函数：

function(array of DOMFileSystem mediaFileSystems) {...};

array of DOMFileSystem

mediaFileSystems

每一个对象的属性

addUserSelectedFolder


              chrome.mediaGalleries.addUserSelectedFolder(function callback)

从 Chrome 34 开始支持。

向用户显示选择文件夹对话框，并将选定目录添加为媒体库。如果用户取消对话框，selectedFileSystemName 为空。需要用户操作才能显示对话框，如果没有用户操作，调用回调函数时就像用户取消操作一样。

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(array of DOMFileSystem mediaFileSystems, string selectedFileSystemName) {...};

array of DOMFileSystem

mediaFileSystems

每一个对象的属性

string

selectedFileSystemName

dropPermissionForMediaFileSystem


              chrome.mediaGalleries.dropPermissionForMediaFileSystem(string galleryId, function callback)

从 Chrome 36 开始支持。

放弃指定媒体库的访问权限。

参数
string	galleryId
function	（可选） callback	如果您指定了 callback 参数，它应该是一个如下形式的函数： `function() {...};`

startMediaScan


              chrome.mediaGalleries.startMediaScan()

从 Chrome 35 开始支持。

开始扫描用户的硬盘，寻找包含媒体的目录。扫描可能需要很长时间，所以进度和完成情况通过事件的方式通知。扫描完成后不会授予任何权限，而需要调用 addScanResults。

cancelMediaScan


              chrome.mediaGalleries.cancelMediaScan()

从 Chrome 35 开始支持。

取消正在进行的媒体扫描，正常情况下应用应该提供某种方式让用户取消他们开始的扫描操作。

addScanResults


              chrome.mediaGalleries.addScanResults(function callback)

从 Chrome 35 开始支持。

向用户显示扫描的结果，并让他们将其中的一部分或者全部添加为媒体库。该方法应该在 'finish'（完成）类型的 onScanProgress 事件产生之后调用，调用后返回应用能够访问的所有媒体库，而不仅仅是新增加的媒体库。

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(array of DOMFileSystem mediaFileSystems) {...};

array of DOMFileSystem

mediaFileSystems

每一个对象的属性

getMediaFileSystemMetadata


              object
              chrome.mediaGalleries.getMediaFileSystemMetadata(DOMFileSystem mediaFileSystem)

从 Chrome 26 开始支持。

获取指定媒体文件系统的元数据。

参数
DOMFileSystem	mediaFileSystem

返回值

string	name	文件系统的名称。
string	galleryId	媒体库的唯一持久标识符。
string	（可选） deviceId	如果媒体库位于可移动设备上，并且设备在线，则为设备的唯一标识符。
boolean	isRemovable	如果媒体库在可移动设备上则为 true。
boolean	isMediaDevice	如果检测到媒体库所在的设备是媒体设备（即 PTP 或 MTP 设备，或存在 DCIM 目录）则为 true。
boolean	isAvailable	如果设备当前可用则为 true。

getAllMediaFileSystemMetadata


              chrome.mediaGalleries.getAllMediaFileSystemMetadata(function callback)

从 Chrome 33 开始支持。

获取所有可用媒体库的元数据。

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(array of object metadata) {...};

array of object

metadata

每一个对象的属性

string	name	文件系统的名称。
string	galleryId	媒体库的唯一持久标识符。
string	（可选） deviceId	如果媒体库位于可移动设备上，并且设备在线，则为设备的唯一标识符。
boolean	isRemovable	如果媒体库在可移动设备上则为 true。
boolean	isMediaDevice	如果检测到媒体库所在的设备是媒体设备（即 PTP 或 MTP 设备，或存在 DCIM 目录）则为 true。
boolean	isAvailable	如果设备当前可用则为 true。

getMetadata


              chrome.mediaGalleries.getMetadata(Blob mediaFile, object options, function callback)

从 Chrome 38 开始支持。警告：目前为 Dev 分支。了解更多内容

获取媒体文件特定的元数据，媒体库和其他 DOM 文件系统中的文件都可以使用该方法。

参数

Blob

mediaFile

从 Chrome 33 开始支持。

object

（可选）
options

从 Chrome 33 开始支持。

enum of "all", "mimeTypeAndTags", or "mimeTypeOnly"

（可选）
metadataType

指定要获取哪些元数据，如果省略该选项则默认为 'all'（全部）。

all: 获取 MIME 类型、元数据标签以及附带的图片。

mimeTypeAndTags: 只获取 MIME 类型和元数据标签。

mimeTypeOnly: 仅获取 MIME 类型。

function

callback

callback 参数应该是一个如下形式的函数：

function(object metadata) {...};

object

metadata

string

mimeType

浏览器检测到的 MIME 类型。

integer

（可选）
height

图片和视频会包含这些属性，以像素为单位。

integer

（可选）
width

double

（可选）
xResolution

图片会包含这些属性。

double

（可选）
yResolution

double

（可选）
duration

音频和视频会包含该属性，以秒为单位。

integer

（可选）
rotation

图片和视频会包含该属性，以度为单位。

string

（可选）
cameraMake

图片会包含这些属性。

string

（可选）
cameraModel

double

（可选）
exposureTimeSeconds

boolean

（可选）
flashFired

double

（可选）
fNumber

double

（可选）
focalLengthMm

double

（可选）
isoEquivalent

string

（可选）
album

音频和视频会包含这些属性。

string

（可选）
artist

string

（可选）
comment

string

（可选）
copyright

integer

（可选）
disc

string

（可选）
genre

string

（可选）
language

string

（可选）
title

integer

（可选）
track

array of object

rawTags

包含媒体文件中所有元数据的词典。如果文件格式包含多个媒体流，则按照媒体流的顺序表示，第一个元素是容器元数据。

每一个对象的属性

string	type	描述媒体流的容器或编解码器格式，即 "mp3"、"h264" 等。
object	tags	媒体流的标签，以未经过滤的字符串->字符串词典的形式表示。

array of Blob

attachedImages

内嵌在媒体文件元数据中的图片，通常为艺术专辑或视频缩略图。

每一个对象的属性

事件

onGalleryChanged

从 Chrome 38 开始支持。警告：目前为 Dev 分支。了解更多内容

媒体库更改时或取消媒体库监视时产生。

addListener


                    chrome.mediaGalleries.onGalleryChanged.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};

object

details

enum of "contents_changed", or "watch_dropped"

type

更改事件的类型。

contents_changed: 媒体库的内容已经更改。

watch_dropped: 监视已经取消，因为设备已经弹出、媒体库权限取消或者其他原因。

string

galleryId

标识修改的媒体库。

onScanProgress

从 Chrome 35 开始支持。

正在进行中的媒体扫描已经更改状态，有关更多信息请参见 details 参数。

addListener


                    chrome.mediaGalleries.onScanProgress.addListener(function callback)

参数

function

callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};

object

details

从 Chrome 34 开始支持。

enum of `"start"`, `"cancel"`, `"finish"`, or `"error"`	type	进度事件的类型，例如 start（开始）、finish（完成）等。 start 扫描开始。 cancel 扫描取消。 finish 扫描完成，但是结果还没添加，您必须调用 addScanResults() 得到用户的许可。 error 扫描遇到错误，不能继续进行。
integer	（可选） galleryCount	找到的媒体库数目。
integer	（可选） audioCount	找到的媒体文件的大致数目。某些文件类型既有可能是音频，也有可能是视频，在这两种类型中都会计算在内。
integer	（可选） imageCount
integer	（可选） videoCount