# gallery

Gallery模块管理系统相册，支持从相册中选择图片或视频文件、保存图片或视频文件到相册等功能。通过plus.gallery获取相册管理对象。

## 方法：

- pick: 从系统相册选择文件（图片或视频）
- save: 保存文件到系统相册中

## 对象：

- GalleryOptions: JSON对象，从相册中选择文件的参数
- GalleryFilter: 相册选择文件过滤类型
- GallerySaveEvent: 保存图片到相册成功事件
- PopPosition: JSON对象，弹出拍照或摄像界面指示位置

## 回调方法：

- GalleryPickSuccessCallback: 单选系统相册图片成功的回调
- GalleryMultiplePickSuccessCallback: 多选系统相册图片成功的回调
- GallerySuccessCallback: 操作系统相册成功的回调
- GalleryErrorCallback: 系统相册操作失败的回调

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"Gallery": {
    		"description": "系统相册"
    	}
    }
    }

# GalleryOptions

JSON对象，从相册中选择文件的参数

    interface plus.gallery.GalleryOptions {
    	readonly attribute Boolean animation;
    	readonly attribute String filename;
    	readonly attribute GalleryFilter filter;
    	readonly attribute Number maximum;
    	readonly attribute Boolean multiple;
    	readonly attribute PopPosition popover;
    	readonly attribute Array<String> selected;
    	readonly attribute Boolean system;
    	attribute Function onmaxed;
    }

## 属性：

- animation: (Boolean 类型 )是否显示系统相册文件选择界面的动画

  可取值true、false，默认值为true。

- filename: (String 类型 )选择文件保存的路径

  某些系统不能直接使用系统相册的路径，这时需要将选择的文件保存到应用可访问的目录中，可通过此参数设置保存文件的路径。 如果路径中包括文件后缀名称，则表明指定文件路径及名称，否则仅指定文件保存目录，文件名称自动生成。

- filter: (GalleryFilter 类型 )相册中选择文件类型过滤器

  系统相册选择器中可选择的文件类型，可设置为仅选择图片文件（“image”）、视频文件（“video”）或所有文件（“none”），默认值为“image”。

- maximum: (Number 类型 )最多选择的图片数量

  仅在支持多选时有效，取值范围为1到Infinity，默认值为Infinity，即不限制选择的图片数。 如果设置的值非法则使用默认值Infinity。

- multiple: (Boolean 类型 )是否支持多选图片

  可从系统相册中选择多张图片，选择图片后通过GalleryMultiplePickSuccessCallback回调返回选择的图片。

- onmaxed: (Function 类型 )超过最多选择图片数量事件

  使用相册多选图片时，可通过maximum属性设置最多选择的图片数量，当用户操作选择的数量大于此时触发此事件。

- popover: (PopPosition 类型 )相册选择界面弹出指示区域

  对于大屏幕设备如iPad，相册选择界面为弹出窗口，此时可通过此参数设置弹出窗口位置。 其为JSON对象，格式如{top:"10px",left:"10px",width:"200px",height:"200px"}，所有值为像素值，左上坐标相对于容器的位置，默认弹出位置为屏幕居中。

- selected: (Array[ String ] 类型 )已选择的图片路径列表

  仅在多图片选择时生效，相册选择界面将选中指定的图片路径列表。 如果指定的路径无效，则忽略此项；如果指定的路径数超过maximum属性指定的最大选择数目则超出的图片不选中。

- system: (Boolean 类型 )是否使用系统相册文件选择界面

  multiple属性设置为true时，如果系统自带相册选择控件时则优先使用，否则使用5+统一相册选择控件；设置为false则不使用系统自带相册选择控件，直接使用5+统一相册选择界面。 默认值为true。

# GalleryFilter

相册选择文件过滤类型

## 属性：

- "image": (String 类型 )仅可选择图片文件
- "video": (String 类型 )仅可选择视频文件
- "none": (String 类型 )不过滤，可选择图片或视频文件

# GallerySaveEvent

保存图片到相册成功事件

## 属性：

- path: (String 类型 )保存到相册的图片路径

# PopPosition

JSON对象，弹出拍照或摄像界面指示位置

## 属性：

- top: (String 类型 )指示区域距离容器顶部的距离

  弹出拍照或摄像窗口指示区域距离容器顶部的距离，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值值。

- left: (String 类型 )指示区域距离容器左侧的距离

  弹出拍照或摄像窗口指示区域距离容器左侧的距离，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值。

- width: (String 类型 )指示区域的宽度

  弹出拍照或摄像窗口指示区域的宽度，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值。

- height: (String 类型 )指示区域的高度

  弹出拍照或摄像窗口指示区域的高度，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值。

# GalleryPickSuccessCallback

单选系统相册图片成功的回调

    void onSuccess( file ) {
    	// Success code
    }

## 说明：

系统相册中单选图片或视频文件成功的回调函数，在选择文件操作成功时调用。

## 参数：

- file: ( String ) 必选 选择的图片或视频文件路径

## 返回值：

void : 无

# GalleryMultiplePickSuccessCallback

多选系统相册图片成功的回调

    void onSuccess( event ) {
    	// Pick success
    	var files = event.files; // 保存多选的图片或视频文件路径
    }

## 说明：

系统相册中多选图片或视频文件成功的回调函数，在多选择文件操作成功时调用。

## 参数：

- event: ( Event ) 必选 多选系统相册返回数据
  Event对象包含以下属性： files - 字符串数组，保存多选的图片或视频文件路径。

## 返回值：

void : 无

# GallerySuccessCallback

操作系统相册成功的回调

    void onSuccess(GallerySaveEvent event) {
    	// Success code
    }

## 说明：

系统相册操作成功的回调函数，在保存文件到系统相册操作成功时调用。

## 参数：

- event: ( GallerySaveEvent ) 必选 保存文件到系统相册成功事件对象
  可通过其path属性获取保存文件的路径。

## 返回值：

void : 无

# GalleryErrorCallback

系统相册操作失败的回调

    void onError( error ) {
    	// Handle error
    	var code = error.code; // 错误编码
    	var message = error.message; // 错误描述信息
    }

## 说明：

系统相册操作失败的回调函数，在选择或保存图片操作失败时调用。

## 参数：

- error: ( Exception ) 必选 相册操作失败的错误信息
  可通过error.code（Number类型）获取错误编码； 可通过error.message（String类型）获取错误描述信息。

## 返回值：

void : 无