# [gallery]() Gallery模块管理系统相册,支持从相册中选择图片或视频文件、保存图片或视频文件到相册等功能。通过plus.gallery获取相册管理对象。 ### 方法: - [pick](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.pick): 从系统相册选择文件(图片或视频) - [save](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.save): 保存文件到系统相册中 ### 对象: - [GalleryOption](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryOption): JSON对象,从相册中选择文件的参数 - [GalleryFilter](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryFilter): 相册选择文件过滤类型 - [PopPosition](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.PopPosition): JSON对象,弹出拍照或摄像界面指示位置 ### 回调方法: - [GalleryPickSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryPickSuccessCallback): 选择系统相册图片成功的回调 - [GallerySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GallerySuccessCallback): 操作系统相册成功的回调 - [GalleryErrorCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryErrorCallback): 系统相册操作失败的回调 ### 权限: permissions ~~~ "Gallery": { "description": "访问系统相册" } ~~~ # [pick]() 从系统相册选择文件(图片或视频) ~~~ void plus.gallery.pick( successCB, errorCB, option ); ~~~ ### 说明: 从系统相册中选择图片或视频文件。每次仅能选择一个文件,选择后将返回选择的文件路径。 ### 参数: - succesCB: *( [GalleryPickSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryPickSuccessCallback) ) 必选 *从系统相册中选择文件完成后的回调函数 - errorCB: *( [GalleryErrorCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryErrorCallback) ) 可选 *从系统相册中选择文件操作错误的回调函数 - option: *( [GalleryOption](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryOption) ) 可选 *设置选择文件的参数 ### 返回值: void : 无 ### 平台支持: - Android - 2.2+ (支持) - iOS - 4.3+ (支持) ### 示例: ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Gallery Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 从相册中选择图片 function selectPicture() { plus.gallery.pick( function (path){ alert( "Success: " + path ); }, function ( err ) { alert( "Failed: " + err.message ); } ); } </script> </head> <body > <input type="button" value="Select picture frome Gallery" onclick="selectPicture();" ></input> </body> </html> ~~~ # [save]() 保存文件到系统相册中 ~~~ void plus.gallery.save( path, successCB, errorCB ); ~~~ ### 说明: 保存文件到系统相册中。 每次仅能保存一个文件,支持图片类型(jpg/jpeg、png、bmp等格式)和视频文件(3gp、mov等格式)。 若保存的文件系统不支持,则通过errorCB返回错误信息。 ### 参数: - path : *( DOMString ) 必选 *要保存到系统相册中的文件文件地址 仅支持本地路径,不支持网络路径。 - succesCB: *( [GallerySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GallerySuccessCallback) ) 必选 *保存文件到系统相册中成功的回调函数 - errorCB: *( [GalleryErrorCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryErrorCallback) ) 可选 *保存文件到系统相册中失败的回调函数 ### 返回值: void : 无 ### 平台支持: - Android - 2.2+ (支持) - iOS - 4.3+ (支持) ### 示例: ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Gallery Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 保存图片到相册中 function savePicture() { plus.gallery.save( "_doc/a.jpg", function () { alert( "保存图片到相册成功" ); } ); } </script> </head> <body > <input type="button" value="Save picture to Gallery" onclick="savePicture();" ></input> </body> </html> ~~~ # [GalleryOption]() JSON对象,从相册中选择文件的参数 ### 属性: - filename: *(DOMString 类型)*选择文件保存的路径 从系统相册中选择文件的保存路径,如果路径中包括文件后缀名称,则表明指定文件路径及名称,否则仅指定文件保存目录,文件名称由程序自动生成。 ### 平台支持 - Android - 2.2+ (不支持): 不支持设置文件路径。 - iOS - 4.3+ (支持): iOS会将相册中的文件拷贝到当前应用沙箱系统中,可通过此参数设置路径。 - filter: *([GalleryFilter](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryFilter) 类型)*相册中选择文件类型过滤器 可通过此参数设定相册选择器中可选择的文件类型,可设置仅可选择图片文件或视频文件,默认值为仅可选择图片文件。 - animation: *(Boolean 类型)*是否显示系统相册文件选择界面的动画 是否显示系统相册文件选择界面的动画,可取值true、false,默认值为true。 ### 平台支持 - Android - 2.2+ (不支持): 忽略此参数,无动画效果。 - iOS - 4.3+ (支持): 支持动画效果。 - popover: *([PopPosition](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.PopPosition) 类型)*相册选择界面弹出指示区域 对于大屏幕设备如iPad,相册选择界面为弹出窗口,此时可通过此参数设置弹出窗口位置。 其为JSON对象,格式如{top:"10",left:10,width:200,height:200},所有值为像素值,左上坐标相对于容器的位置,默认弹出位置为屏幕居中。 # [GalleryFilter]() 相册选择文件过滤类型 ### 属性: - "image": *(DOMString 类型)*仅可选择图片文件 - "video": *(DOMString 类型)*仅可选择视频文件 - "none": *(DOMString 类型)*不过滤,可选择图片或视频文件 # [PopPosition]() JSON对象,弹出拍照或摄像界面指示位置 ### 属性: - top: *(DOMString 类型)*指示区域距离容器顶部的距离 弹出拍照或摄像窗口指示区域距离容器顶部的距离,单位支持像素值(如100px)和百分比(如50%),如不写单位则为像素值值。 - left: *(DOMString 类型)*指示区域距离容器左侧的距离 弹出拍照或摄像窗口指示区域距离容器左侧的距离,单位支持像素值(如100px)和百分比(如50%),如不写单位则为像素值。 - width: *(DOMString 类型)*指示区域的宽度 弹出拍照或摄像窗口指示区域的宽度,单位支持像素值(如100px)和百分比(如50%),如不写单位则为像素值。 - height: *(DOMString 类型)*指示区域的高度 弹出拍照或摄像窗口指示区域的高度,单位支持像素值(如100px)和百分比(如50%),如不写单位则为像素值。 # [GalleryPickSuccessCallback]() 选择系统相册图片成功的回调 ~~~ void onSuccess( file ) { // Success code } ~~~ ### 说明: 系统相册中选择文件成功的回调函数,在选择文件操作成功时调用。 选择操作失败或取消选择不调用此方法。 ### 参数: - file: *( DOMString ) 必选 *选择的图片或视频文件路径 ### 返回值: void : 无 # [GallerySuccessCallback]() 操作系统相册成功的回调 ~~~ void onSuccess() { // Success code } ~~~ ### 说明: 系统相册操作成功的回调函数,在保存文件到系统相册操作成功时调用。 选择操作失败或取消选择不调用此方法。 ### 参数: 无 ### 返回值: void : 无 # [GalleryErrorCallback]() 系统相册操作失败的回调 ~~~ void onError( error ) { // Error code. } ~~~ ### 说明: 系统相册操作失败的回调函数,在选择或保存图片操作失败时调用。 选择图片时用户取消选择调用此方法。 ### 参数: - error: *( DOMException ) 必选 *相册操作失败的错误信息 ### 返回值: void : 无