# [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 : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS