gallery

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

方法：

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

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Gallery": {
  7.         "description": "系统相册"
  8.     }
  9. }
  10. }
  11.

pick

从系统相册选择文件（图片或视频）

  2. void plus.gallery.pick(successCB, errorCB, options);
  3.

说明：

从系统相册中选择图片或视频文件。每次仅能选择一个文件，选择后将返回选择的文件路径。

参数：

  • succesCB: (GalleryPickSuccessCallback|GalleryMultiplePickSuccessCallback)必选 从系统相册中选择文件完成后的回调函数单选时通过GalleryPickSuccessCallback回调函数返回选择的图片或视频文件路径，多选时通过GalleryMultiplePickSuccessCallback回调函数返回图片或视频文件路径。
  • errorCB: (GalleryErrorCallback)可选 从系统相册中选择文件操作错误的回调函数
  • options: (GalleryOptions)可选 设置选择文件的参数

返回值：

void: 无

平台支持：

  • Android- 2.2+(支持): 返回的是系统相册路径，如“file:///storage/sdcard0/DCIM/Camera/1428841301674.jpg”。
  • iOS- 5.1+(支持): 受系统相册路径的访问限制，选择后图片会先拷贝到应用沙盒下的"_doc"目录中，如“file:///var/mobile/Applications/0373DFBF-6AA7-4C9B-AE1F-766469117C94/Library/Pandora/apps/HBuilder/doc/IMG_0005.jpg”。

示例：

  2. // 从相册中选择图片 
  3. function galleryImg() {
  4.     // 从相册中选择图片
  5.     console.log("从相册中选择图片:");
  6.     plus.gallery.pick( function(path){
  7.         console.log(path);
  8.     }, function ( e ) {
  9.         console.log( "取消选择图片" );
  10.     }, {filter:"image"} );
  11. }
  12. // 从相册中选择多张图片 
  13. function galleryImgs(){
  14.     // 从相册中选择图片
  15.     console.log("从相册中选择多张图片:");
  16.     plus.gallery.pick( function(e){
  17.         for(var i in e.files){
  18.             console.log(e.files[i]);
  19.         }
  20.     }, function ( e ) {
  21.         console.log( "取消选择图片" );
  22.     },{filter:"image",multiple:true});
  23. }
  24.

uni-app使用plus注意事项

save

保存文件到系统相册中

  2. void plus.gallery.save( path, successCB, errorCB );
  3.

说明：

保存文件到系统相册中。每次仅能保存一个文件，支持图片类型（jpg/jpeg、png、bmp等格式）和视频文件（3gp、mov等格式）。若保存的文件系统不支持，则通过errorCB返回错误信息。

参数：

  • path : (String)必选 要保存到系统相册中的文件文件地址
  • succesCB: (GallerySuccessCallback)必选 保存文件到系统相册中成功的回调函数
  • errorCB: (GalleryErrorCallback)可选 保存文件到系统相册中失败的回调函数

返回值：

void: 无

平台支持：

  • Android - 2.2+ (支持)
  • iOS - 4.3+ (支持)

示例：

  2. // 保存图片到相册中 
  3. function savePicture() {
  4.     plus.gallery.save( "_doc/a.jpg", function () {
  5.         alert( "保存图片到相册成功" );
  6.     } );
  7. }
  8.

uni-app使用plus注意事项

GalleryOptions

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

  2. interface plus.gallery.GalleryOptions {
  3.     readonly attribute Boolean animation;
  4.     readonly attribute String filename;
  5.     readonly attribute GalleryFilter filter;
  6.     readonly attribute Number maximum;
  7.     readonly attribute Boolean multiple;
  8.     readonly attribute PopPosition popover;
  9.     readonly attribute Array<String> selected;
  10.     readonly attribute Boolean system;
  11.     attribute Function onmaxed;
  12. }
  13.

属性：

  • animation: (Boolean类型)是否显示系统相册文件选择界面的动画可取值true、false，默认值为true。

平台支持

  • Android - 2.2+ (不支持): 忽略此参数，无动画效果。
  • iOS - 4.3+ (支持): 支持动画效果。
    • filename: (String类型)选择文件保存的路径某些系统不能直接使用系统相册的路径，这时需要将选择的文件保存到应用可访问的目录中，可通过此参数设置保存文件的路径。如果路径中包括文件后缀名称，则表明指定文件路径及名称，否则仅指定文件保存目录，文件名称自动生成。

平台支持

  • Android - 2.2+ (不支持): 直接返回系统相册中的文件路径，忽略此参数。
  • iOS - 4.3+ (支持): 如果未设置则默认使用应用临时目录（系统在磁盘控件不足时自动清理）。如果希望将文件拷贝到应用沙箱目录中，可通过此参数配置目标路径（如"_doc/gallery/"）。
    • filter: (GalleryFilter类型)相册中选择文件类型过滤器系统相册选择器中可选择的文件类型，可设置为仅选择图片文件（“image”）、视频文件（“video”）或所有文件（“none”），默认值为“image”。
  2. // 从相册中选择图片 
  3. function galleryImg() {
  4.     // 从相册中选择图片
  5.     console.log("从相册中选择图片:");
  6.     plus.gallery.pick( function(path){
  7.         console.log(path);
  8.     }, function ( e ) {
  9.         console.log( "取消选择图片" );
  10.     }, {filter:"image"} );
  11. }
  12.
  • maximum: (Number类型)最多选择的图片数量仅在支持多选时有效，取值范围为1到Infinity，默认值为Infinity，即不限制选择的图片数。如果设置的值非法则使用默认值Infinity。

平台支持

  • Android - ALL (支持): 系统相册文件选择界面不支持设置选择的图片数量，为了确保此功能可正常使用，应该设置system属性值为false强制使用5+统一相册选择界面。
  • iOS - ALL (支持)
  2. // 从相册中选择多张图片 
  3. function galleryMaximum(){
  4.     // 从相册中选择图片
  5.     console.log("从相册中选择多张图片:");
  6.     plus.gallery.pick( function(e){
  7.         for(var i in e.files){
  8.             console.log(e.files[i]);
  9.         }
  10.     }, function ( e ) {
  11.         console.log( "取消选择图片" );
  12.     },{filter:"image",multiple:true,maximum:3,system:false});// 最多选择3张图片
  13. }
  14.
  • multiple: (Boolean类型)是否支持多选图片可从系统相册中选择多张图片，选择图片后通过GalleryMultiplePickSuccessCallback回调返回选择的图片。
  2. // 从相册中选择多张图片 
  3. function galleryImgs(){
  4.     // 从相册中选择图片
  5.     console.log("从相册中选择多张图片:");
  6.     plus.gallery.pick( function(e){
  7.         for(var i in e.files){
  8.             console.log(e.files[i]);
  9.         }
  10.     }, function ( e ) {
  11.         console.log( "取消选择图片" );
  12.     },{filter:"image",multiple:true});
  13. }
  14.
  • onmaxed: (Function类型)超过最多选择图片数量事件使用相册多选图片时，可通过maximum属性设置最多选择的图片数量，当用户操作选择的数量大于此时触发此事件。

平台支持

  • Android - ALL (支持): 系统相册文件选择界面不支持设置选择的图片数量，只有当用户选择的图片数量超过最多图片数是触发，为了确保此功能可正常使用，应该设置system属性值为false强制使用5+统一相册选择界面。注意：此时显示的相册文件选择界面，需要使用plus.nativeUI.*弹出提示框，否则可能无法正常显示。
  • iOS - ALL (支持)
  2. // 从相册中选择多张图片 
  3. function galleryOnmaxed(){
  4.     // 从相册中选择图片
  5.     console.log("从相册中选择多张图片:");
  6.     plus.gallery.pick( function(e){
  7.         for(var i in e.files){
  8.             console.log(e.files[i]);
  9.         }
  10.     }, function ( e ) {
  11.         console.log( "取消选择图片" );
  12.     },{filter:"image",multiple:true,maximum:3,system:false,onmaxed:function(){
  13.         plus.nativeUI.alert('最多只能选择3张图片');
  14.     }});// 最多选择3张图片
  15. }
  16.

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

  • selected: (Array[String]类型)已选择的图片路径列表仅在多图片选择时生效，相册选择界面将选中指定的图片路径列表。如果指定的路径无效，则忽略此项；如果指定的路径数超过maximum属性指定的最大选择数目则超出的图片不选中。

平台支持

  • Android - ALL (支持): 系统相册文件选择界面不支持设置已选择的图片列表，为了确保此功能可正常使用，应该设置system属性值为false强制使用5+统一相册选择界面。
  • iOS - ALL (支持)
  2. var lfs=null;// 保留上次选择图片列表
  3. // 从相册中选择多张图片 
  4. function gallerySelected(){
  5.     // 从相册中选择图片
  6.     console.log("从相册中选择多张图片:");
  7.     plus.gallery.pick( function(e){
  8.         for(var i in e.files){
  9.             lfs=e.files;
  10.             console.log(e.files[i]);
  11.         }
  12.     }, function ( e ) {
  13.         console.log( "取消选择图片" );
  14.     },{filter:"image",multiple:true,selected:lfs,maximum:3,system:false});// 最多选择3张图片
  15. }
  16.
  • system: (Boolean类型)是否使用系统相册文件选择界面multiple属性设置为true时，如果系统自带相册选择控件时则优先使用，否则使用5+统一相册选择控件；设置为false则不使用系统自带相册选择控件，直接使用5+统一相册选择界面。默认值为true。

平台支持

  • Android - 2.3+ (支持): Android4.0以上系统支持自带相册选择控件。
  • iOS - 5.1+ (不支持): 不支持系统自带相册选择控件，忽略此参数。

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

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

  2. void onSuccess( file ) {
  3.     // Success code
  4. }
  5.

说明：

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

参数：

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

返回值：

void: 无

示例：

  2. // 从相册中选择单张图片 
  3. function galleryImg() {
  4.     // 从相册中选择图片
  5.     console.log("从相册中选择图片:");
  6.     plus.gallery.pick( function(path){
  7.         console.log(path);
  8.     }, function ( e ) {
  9.         console.log( "取消选择图片" );
  10.     }, {filter:"image"} );
  11. }
  12.

uni-app使用plus注意事项

GalleryMultiplePickSuccessCallback

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

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

说明：

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

参数：

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

返回值：

void: 无

示例：

  2. // 从相册中选择多张图片 
  3. function galleryImgs(){
  4.     // 从相册中选择图片
  5.     console.log("从相册中选择多张图片:");
  6.     plus.gallery.pick( function(e){
  7.         for(var i in e.files){
  8.             console.log(e.files[i]);
  9.         }
  10.     }, function ( e ) {
  11.         console.log( "取消选择图片" );
  12.     },{filter:"image",multiple:true});
  13. }
  14.

uni-app使用plus注意事项

GallerySuccessCallback

操作系统相册成功的回调

  2. void onSuccess(GallerySaveEvent event) {
  3.     // Success code
  4. }
  5.

说明：

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

参数：

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

返回值：

void: 无

GalleryErrorCallback

系统相册操作失败的回调

  2. void onError( error ) {
  3.     // Handle error
  4.     var code = error.code; // 错误编码
  5.     var message = error.message; // 错误描述信息
  6. }
  7.

说明：

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

参数：

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

返回值：

void: 无