返回介绍

gallery

发布于 2021-10-21 18:08:11 字数 14042 浏览 1099 评论 0 收藏 0

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

方法:

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

对象:

回调方法:

权限:

5+功能模块(permissions)


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

pick

从系统相册选择文件(图片或视频)


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

说明:

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

参数:

  • 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”。

示例:


// 从相册中选择图片 
function galleryImg() {
	// 从相册中选择图片
	console.log("从相册中选择图片:");
    plus.gallery.pick( function(path){
    	console.log(path);
    }, function ( e ) {
    	console.log( "取消选择图片" );
    }, {filter:"image"} );
}
// 从相册中选择多张图片 
function galleryImgs(){
	// 从相册中选择图片
	console.log("从相册中选择多张图片:");
    plus.gallery.pick( function(e){
    	for(var i in e.files){
	    	console.log(e.files[i]);
    	}
    }, function ( e ) {
    	console.log( "取消选择图片" );
    },{filter:"image",multiple:true});
}
				

uni-app使用plus注意事项

save

保存文件到系统相册中


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

说明:

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

参数:

  • path :
    (
    String
    )
    必选
    要保存到系统相册中的文件文件地址

  • succesCB:
    (
    GallerySuccessCallback
    )
    必选
    保存文件到系统相册中成功的回调函数

  • errorCB:
    (
    GalleryErrorCallback
    )
    可选
    保存文件到系统相册中失败的回调函数

返回值:

void
: 无

平台支持:

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

示例:


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

uni-app使用plus注意事项

GalleryOptions

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


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

属性:

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

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

    平台支持

    • Android - 2.2+ (不支持)
      :

      忽略此参数,无动画效果。

    • iOS - 4.3+ (支持)
      :

      支持动画效果。

  • confirmText: (String
    类型
    )
    确认按钮文字

    不传入此参数时,使用默认确认按钮文字“确定”。
    注意:HBuilderX3.1.5+版本支持。

  • crop: (GalleryCropStyles
    类型
    )
    配置裁剪图片

    设置裁剪图片项后,在相册中选择图片一定会进入裁剪编辑界面,确认后返回裁剪后的图片。
    设置此值后只能选择一张图片。
    注意:HBuilderX3.1.19及以上版本支持。

  • editable: (Boolean
    类型
    )
    是否支持编辑图片

    可取值true、false,默认值为true。
    注意:HBuilderX3.1.5+版本支持。

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

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

    平台支持

    • Android - 2.2+ (不支持)
      :

      直接返回系统相册中的文件路径,忽略此参数。

    • iOS - 4.3+ (支持)
      :

      如果未设置则默认使用应用临时目录(系统在磁盘控件不足时自动清理)。
      如果希望将文件拷贝到应用沙箱目录中,可通过此参数配置目标路径(如"_doc/gallery/")。

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

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

    
    // 从相册中选择图片 
    function galleryImg() {
    	// 从相册中选择图片
    	console.log("从相册中选择图片:");
        plus.gallery.pick( function(path){
        	console.log(path);
        }, function ( e ) {
        	console.log( "取消选择图片" );
        }, {filter:"image"} );
    }
    						
  • maximum: (Number
    类型
    )
    最多选择的图片数量

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

    
    // 从相册中选择多张图片 
    function galleryMaximum(){
    	// 从相册中选择图片
    	console.log("从相册中选择多张图片:");
        plus.gallery.pick( function(e){
        	for(var i in e.files){
    	    	console.log(e.files[i]);
        	}
        }, function ( e ) {
        	console.log( "取消选择图片" );
        },{filter:"image",multiple:true,maximum:3,system:false});// 最多选择3张图片
    }
    						
  • multiple: (Boolean
    类型
    )
    是否支持多选图片

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

    
    // 从相册中选择多张图片 
    function galleryImgs(){
    	// 从相册中选择图片
    	console.log("从相册中选择多张图片:");
        plus.gallery.pick( function(e){
        	for(var i in e.files){
    	    	console.log(e.files[i]);
        	}
        }, function ( e ) {
        	console.log( "取消选择图片" );
        },{filter:"image",multiple:true});
    }
    						
  • onmaxed: (Function
    类型
    )
    超过最多选择图片数量事件

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

    平台支持

    • Android - ALL (支持)
      :

      系统相册文件选择界面不支持设置选择的图片数量,只有当用户选择的图片数量超过最多图片数是触发,为了确保此功能可正常使用,应该设置system属性值为false强制使用5+统一相册选择界面。
      注意:此时显示的相册文件选择界面,需要使用plus.nativeUI.*弹出提示框,否则可能无法正常显示。

    • iOS - ALL (支持)
    
    // 从相册中选择多张图片 
    function galleryOnmaxed(){
    	// 从相册中选择图片
    	console.log("从相册中选择多张图片:");
        plus.gallery.pick( function(e){
        	for(var i in e.files){
    	    	console.log(e.files[i]);
        	}
        }, function ( e ) {
        	console.log( "取消选择图片" );
        },{filter:"image",multiple:true,maximum:3,system:false,onmaxed:function(){
    		plus.nativeUI.alert('最多只能选择3张图片');
        }});// 最多选择3张图片
    }
    						
  • permissionAlert: (Boolean
    类型
    )
    是否检测权限

    可取值:

    • true - 检测到用户没有授权访问相册,将会弹出提示框引导用户授权
    • false - 检测到用户没有授权访问相册,触发错误回调,无界面提示

    默认值为false。

    平台支持

    • Android - ALL (不支持)
    • iOS - 8.0+ (支持)
      :

      HBuilderX2.9.5+版本支持,iOS14上如果设置为访问`选中的照片`权限时引导修改为访问`所有照片`

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

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

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

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

    平台支持

    • Android - ALL (支持)
      :

      系统相册文件选择界面不支持设置已选择的图片列表,为了确保此功能可正常使用,应该设置system属性值为false强制使用5+统一相册选择界面。

    • iOS - ALL (支持)
    
    var lfs=null;// 保留上次选择图片列表
    // 从相册中选择多张图片 
    function gallerySelected(){
    	// 从相册中选择图片
    	console.log("从相册中选择多张图片:");
        plus.gallery.pick( function(e){
        	for(var i in e.files){
    			lfs=e.files;
    	    	console.log(e.files[i]);
        	}
        }, function ( e ) {
        	console.log( "取消选择图片" );
        },{filter:"image",multiple:true,selected:lfs,maximum:3,system:false});// 最多选择3张图片
    }
    						
  • system: (Boolean
    类型
    )
    是否使用系统相册文件选择界面

    废弃,HBuilderX2.9.6+版本不再使用系统自带相册选择控件。

GalleryCropStyles

裁剪图片设置项

说明:

注意:HBuilderX3.1.19及以上版本支持。

属性:

  • quality: (Number
    类型
    )
    裁剪后保存图片的质量

    取值范围为1-100,数值越小,质量越低(仅对jpg格式有效)。
    默认值为80。

  • width: (Number
    类型
    )
    裁剪的宽度

    单位为px,用于计算裁剪宽高比。
    必须设置此值。

  • height: (Number
    类型
    )
    裁剪的高度

    单位为px,用于计算裁剪宽高比。
    必须设置此值。

  • resize: (Boolean
    类型
    )
    是否将图片保存为指定的宽高像素

    true表示将width和height作为裁剪保存图片的像素值,false表示使用图片编辑操作的真实像素值。
    默认值为true。
    设置为false时在裁剪编辑界面显示图片的像素值,设置为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
: 无

示例:


// 从相册中选择单张图片 
function galleryImg() {
	// 从相册中选择图片
	console.log("从相册中选择图片:");
    plus.gallery.pick( function(path){
    	console.log(path);
    }, function ( e ) {
    	console.log( "取消选择图片" );
    }, {filter:"image"} );
}
				

uni-app使用plus注意事项

GalleryMultiplePickSuccessCallback

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


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

说明:

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

参数:

  • event:
    (
    Event
    )
    必选
    多选系统相册返回数据

    Event对象包含以下属性:
    files - 字符串数组,保存多选的图片或视频文件路径。

返回值:

void
: 无

示例:


// 从相册中选择多张图片 
function galleryImgs(){
	// 从相册中选择图片
	console.log("从相册中选择多张图片:");
    plus.gallery.pick( function(e){
    	for(var i in e.files){
	    	console.log(e.files[i]);
    	}
    }, function ( e ) {
    	console.log( "取消选择图片" );
    },{filter:"image",multiple:true});
}
				

uni-app使用plus注意事项

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
: 无

如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

列表为空,暂无数据
我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击“接受”或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。