<!DOCTYPE HTML>
|
<html>
|
<head>
|
<meta charset="utf-8">
|
<meta name="viewport" content="initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
|
<meta name="HandheldFriendly" content="true">
|
<meta name="MobileOptimized" content="320">
|
<title>Gallery Document</title>
|
<link rel="stylesheet" type="text/css" href="res/doc.css" charset="utf-8">
|
<link rel="stylesheet" type="text/css" href="res/prettify.sons.css" charset="utf-8">
|
<script type="text/javascript" src="res/doc.js" charset="utf-8"></script><script type="text/javascript" src="res/prettify.js" charset="utf-8"></script>
|
</head>
|
<body><div id="content" class="content">
|
<h1><a name="plus.gallery">gallery</a></h1>
|
<p>Gallery模块管理系统相册，支持从相册中选择图片或视频文件、保存图片或视频文件到相册等功能。通过plus.gallery获取相册管理对象。</p>
|
<h2>方法：</h2>
|
<ul>
|
<li>
|
<a href="#plus.gallery.pick">pick</a>: 从系统相册选择文件（图片或视频）</li>
|
<li>
|
<a href="#plus.gallery.save">save</a>: 保存文件到系统相册中</li>
|
</ul>
|
<h2>对象：</h2>
|
<ul>
|
<li>
|
<a href="#plus.gallery.GalleryOptions">GalleryOptions</a>: JSON对象，从相册中选择文件的参数</li>
|
<li>
|
<a href="#plus.gallery.GalleryFilter">GalleryFilter</a>: 相册选择文件过滤类型</li>
|
<li>
|
<a href="#plus.gallery.GallerySaveEvent">GallerySaveEvent</a>: 保存图片到相册成功事件</li>
|
<li>
|
<a href="#plus.gallery.PopPosition">PopPosition</a>: JSON对象，弹出拍照或摄像界面指示位置</li>
|
</ul>
|
<h2>回调方法：</h2>
|
<ul>
|
<li>
|
<a href="#plus.gallery.GalleryPickSuccessCallback">GalleryPickSuccessCallback</a>: 单选系统相册图片成功的回调</li>
|
<li>
|
<a href="#plus.gallery.GalleryMultiplePickSuccessCallback">GalleryMultiplePickSuccessCallback</a>: 多选系统相册图片成功的回调</li>
|
<li>
|
<a href="#plus.gallery.GallerySuccessCallback">GallerySuccessCallback</a>: 操作系统相册成功的回调</li>
|
<li>
|
<a href="#plus.gallery.GalleryErrorCallback">GalleryErrorCallback</a>: 系统相册操作失败的回调</li>
|
</ul>
|
<h2>权限：</h2>
|
<p>5+功能模块（permissions）</p>
|
<pre class="prettyprint linenums">
|
{
|
// ...
|
"permissions":{
|
// ...
|
"Gallery": {
|
"description": "系统相册"
|
}
|
}
|
}
|
</pre>
|
<h1><a name="plus.gallery.GalleryOptions">GalleryOptions</a></h1>
|
<p>JSON对象，从相册中选择文件的参数</p>
|
<pre class="prettyprint linenums">
|
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;
|
}
|
</pre>
|
<h2>属性：</h2>
|
<ul>
|
<li>animation: <em>(<font class="type">Boolean</font>
|
类型
|
)</em>是否显示系统相册文件选择界面的动画<br><p>
|
可取值true、false，默认值为true。
|
</p>
|
</li>
|
<li>filename: <em>(<font class="type">String</font>
|
类型
|
)</em>选择文件保存的路径<br><p>
|
某些系统不能直接使用系统相册的路径，这时需要将选择的文件保存到应用可访问的目录中，可通过此参数设置保存文件的路径。
|
如果路径中包括文件后缀名称，则表明指定文件路径及名称，否则仅指定文件保存目录，文件名称自动生成。
|
</p>
|
</li>
|
<li>filter: <em>(<a href="#plus.gallery.GalleryFilter">GalleryFilter</a>
|
类型
|
)</em>相册中选择文件类型过滤器<br><p>
|
系统相册选择器中可选择的文件类型，可设置为仅选择图片文件（“image”）、视频文件（“video”）或所有文件（“none”），默认值为“image”。
|
</p>
|
</li>
|
<li>maximum: <em>(<font class="type">Number</font>
|
类型
|
)</em>最多选择的图片数量<br><p>
|
仅在支持多选时有效，取值范围为1到Infinity，默认值为Infinity，即不限制选择的图片数。
|
如果设置的值非法则使用默认值Infinity。
|
</p>
|
</li>
|
<li>multiple: <em>(<font class="type">Boolean</font>
|
类型
|
)</em>是否支持多选图片<br><p>
|
可从系统相册中选择多张图片，选择图片后通过GalleryMultiplePickSuccessCallback回调返回选择的图片。
|
</p>
|
</li>
|
<li>onmaxed: <em>(<font class="type">Function</font>
|
类型
|
)</em>超过最多选择图片数量事件<br><p>
|
使用相册多选图片时，可通过maximum属性设置最多选择的图片数量，当用户操作选择的数量大于此时触发此事件。
|
</p>
|
</li>
|
<li>popover: <em>(<a href="#plus.gallery.PopPosition">PopPosition</a>
|
类型
|
)</em>相册选择界面弹出指示区域<br><p>
|
对于大屏幕设备如iPad，相册选择界面为弹出窗口，此时可通过此参数设置弹出窗口位置。
|
其为JSON对象，格式如{top:"10px",left:"10px",width:"200px",height:"200px"}，所有值为像素值，左上坐标相对于容器的位置，默认弹出位置为屏幕居中。
|
</p>
|
</li>
|
<li>selected: <em>(<font class="type">Array</font>[
|
<font class="type">String</font>
|
]
|
|
类型
|
)</em>已选择的图片路径列表<br><p>
|
仅在多图片选择时生效，相册选择界面将选中指定的图片路径列表。
|
如果指定的路径无效，则忽略此项；如果指定的路径数超过maximum属性指定的最大选择数目则超出的图片不选中。
|
</p>
|
</li>
|
<li>system: <em>(<font class="type">Boolean</font>
|
类型
|
)</em>是否使用系统相册文件选择界面<br><p>
|
multiple属性设置为true时，如果系统自带相册选择控件时则优先使用，否则使用5+统一相册选择控件；设置为false则不使用系统自带相册选择控件，直接使用5+统一相册选择界面。
|
默认值为true。
|
</p>
|
</li>
|
</ul>
|
<h1><a name="plus.gallery.GalleryFilter">GalleryFilter</a></h1>
|
<p>相册选择文件过滤类型</p>
|
<h2>属性：</h2>
|
<ul>
|
<li>"image": <em>(<font class="type">String</font>
|
类型
|
)</em>仅可选择图片文件<br>
|
</li>
|
<li>"video": <em>(<font class="type">String</font>
|
类型
|
)</em>仅可选择视频文件<br>
|
</li>
|
<li>"none": <em>(<font class="type">String</font>
|
类型
|
)</em>不过滤，可选择图片或视频文件<br>
|
</li>
|
</ul>
|
<h1><a name="plus.gallery.GallerySaveEvent">GallerySaveEvent</a></h1>
|
<p>保存图片到相册成功事件</p>
|
<h2>属性：</h2>
|
<ul><li>path: <em>(<font class="type">String</font>
|
类型
|
)</em>保存到相册的图片路径<br>
|
</li></ul>
|
<h1><a name="plus.gallery.PopPosition">PopPosition</a></h1>
|
<p>JSON对象，弹出拍照或摄像界面指示位置</p>
|
<h2>属性：</h2>
|
<ul>
|
<li>top: <em>(<font class="type">String</font>
|
类型
|
)</em>指示区域距离容器顶部的距离<br><p>
|
弹出拍照或摄像窗口指示区域距离容器顶部的距离，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值值。</p>
|
</li>
|
<li>left: <em>(<font class="type">String</font>
|
类型
|
)</em>指示区域距离容器左侧的距离<br><p>
|
弹出拍照或摄像窗口指示区域距离容器左侧的距离，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值。</p>
|
</li>
|
<li>width: <em>(<font class="type">String</font>
|
类型
|
)</em>指示区域的宽度<br><p>
|
弹出拍照或摄像窗口指示区域的宽度，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值。</p>
|
</li>
|
<li>height: <em>(<font class="type">String</font>
|
类型
|
)</em>指示区域的高度<br><p>
|
弹出拍照或摄像窗口指示区域的高度，单位支持像素值（如"100px"）和百分比（如"50%"），如不写单位则为像素值。</p>
|
</li>
|
</ul>
|
<h1><a name="plus.gallery.GalleryPickSuccessCallback">GalleryPickSuccessCallback</a></h1>
|
<p>单选系统相册图片成功的回调</p>
|
<pre class="prettyprint linenums">
|
void onSuccess( file ) {
|
// Success code
|
}
|
</pre>
|
<h2>说明：</h2>
|
<p class="des">
|
系统相册中单选图片或视频文件成功的回调函数，在选择文件操作成功时调用。
|
</p>
|
<h2>参数：</h2>
|
<ul><li>file:
|
<em>(
|
<font class="type">String</font>
|
)
|
必选 </em>选择的图片或视频文件路径<br>
|
</li></ul>
|
<h2>返回值：</h2>
|
<font class="type">void</font>
|
: 无<h1><a name="plus.gallery.GalleryMultiplePickSuccessCallback">GalleryMultiplePickSuccessCallback</a></h1>
|
<p>多选系统相册图片成功的回调</p>
|
<pre class="prettyprint linenums">
|
void onSuccess( event ) {
|
// Pick success
|
var files = event.files; // 保存多选的图片或视频文件路径
|
}
|
</pre>
|
<h2>说明：</h2>
|
<p class="des">
|
系统相册中多选图片或视频文件成功的回调函数，在多选择文件操作成功时调用。
|
</p>
|
<h2>参数：</h2>
|
<ul><li>event:
|
<em>(
|
<font class="type">Event</font>
|
)
|
必选 </em>多选系统相册返回数据<br>
|
Event对象包含以下属性：
|
files - 字符串数组，保存多选的图片或视频文件路径。
|
</li></ul>
|
<h2>返回值：</h2>
|
<font class="type">void</font>
|
: 无<h1><a name="plus.gallery.GallerySuccessCallback">GallerySuccessCallback</a></h1>
|
<p>操作系统相册成功的回调</p>
|
<pre class="prettyprint linenums">
|
void onSuccess(GallerySaveEvent event) {
|
// Success code
|
}
|
</pre>
|
<h2>说明：</h2>
|
<p class="des">
|
系统相册操作成功的回调函数，在保存文件到系统相册操作成功时调用。
|
</p>
|
<h2>参数：</h2>
|
<ul><li>event:
|
<em>(
|
<a href="#plus.gallery.GallerySaveEvent">GallerySaveEvent</a>
|
)
|
必选 </em>保存文件到系统相册成功事件对象<br>
|
可通过其path属性获取保存文件的路径。
|
</li></ul>
|
<h2>返回值：</h2>
|
<font class="type">void</font>
|
: 无<h1><a name="plus.gallery.GalleryErrorCallback">GalleryErrorCallback</a></h1>
|
<p>系统相册操作失败的回调</p>
|
<pre class="prettyprint linenums">
|
void onError( error ) {
|
// Handle error
|
var code = error.code; // 错误编码
|
var message = error.message; // 错误描述信息
|
}
|
</pre>
|
<h2>说明：</h2>
|
<p class="des">
|
系统相册操作失败的回调函数，在选择或保存图片操作失败时调用。
|
</p>
|
<h2>参数：</h2>
|
<ul><li>error:
|
<em>(
|
<font class="type">Exception</font>
|
)
|
必选 </em>相册操作失败的错误信息<br>
|
可通过error.code（Number类型）获取错误编码；
|
可通过error.message（String类型）获取错误描述信息。
|
</li></ul>
|
<h2>返回值：</h2>
|
<font class="type">void</font>
|
: 无<br><br>
|
</div></body>
|
</html>
|
