UIScrollPicture

来自于：官方立即使用

open close show hide setCurrentIndex reloadData addEventListener clearCache

论坛示例

为帮助用户更好更快的使用模块，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。

概述

UIScrollPicture 是一个图片轮播模块，只需传入一组图片地址，即可实现图片轮播效果。

open 接口内的 rect 参数，可控制图片轮播区域的位置和大小。styles 参数可以设置轮播视图底部的标题文字大小及颜色，亦可设置底部页面控制器（几个小圆点）的位置和样式。

有些应用的头条新闻或广告轮播展示都是无限循环自动播放的，本模块亦可以实现相同的功能，可通过open 接口内的 loop 和 auto 参数控制。每张图片自动轮播时的时间间隔也可自定义，用 interval 即可。为了让原生模块真正的嵌入的网页内，让开发者像使用 js 库一样使用原生模块，APICloud 平台特开放了 fixedOn、fixed 参数。通过配置以上两个参数，可实现让轮播视图随 html 页面上下滚动的功能。

本图片轮播器是由原生代码开发，对于网络图片的展示更加人性化。模块内部会做缓存处理，第一次加载网络图片时，模块会根据其路径生成一个 md5 加密的图片名，并缓存在缓存文件夹里。当用户下次打开同路径的图片时，模块直接从缓存文件内读取该图片，从而大大节省了用户流量。开发者可以通过调用 clearCache 接口清楚本模块在本地缓存的图片资源，调用 api.clearCache 接口会清除本 APP 在本地缓存的所有文件。由于原生代码相对前端代码的高效性，本模块相对于前端实现的图片轮播功能更加流畅，内存管理更加优化。当用户需要展示多张图片时，其内存只保留三张图片的地址，然后来回切换图片内容，从而降低了整个 app 内存占用率。具体模块功能请参考模块接口。

不能同时添加的模块：fog2

UIScrollPicture 模块是 scrollPicture 模块的优化版。

UIScrollPicture - 图1

实例widget下载地址

本模块源码已经开源，详见github

模块接口

open

打开模块

open({params}, callback(ret, err))

params

rect：

  • 类型：JSON 对象
  • 描述：（可选项）模块的位置及尺寸
  • 内部字段：
  1. {
  2.     x: 0,   //（可选项）数字类型；模块左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认：0
  3.     y: 0,   //（可选项）数字类型；模块左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认：0
  4.     w: 320, //（可选项）数字类型；模块的宽度；默认：'auto'
  5.     h: 200  //（可选项）数字类型；模块的高度；默认：'auto'
  6. }

data：

  • 类型：JSON 对象
  • 描述：模块的图片路径数组，及说明文字数组
  • 内部字段：
  1. {
  2.     paths: [],      //数组类型；图片路径数组，支持http://，https://，widget://，fs://协议
  3.     captions: []    //（可选项）数组类型；说明文字数组，与 paths 数组长度一致；不传则不显示说明文字区域
  4. }

styles：

  • 类型：JSON 对象
  • 描述：（可选项）模块各部分的样式
  • 内部字段：
  1. {
  2.     caption: {                          //（可选项）JSON对象；说明文字区域样式
  3.         height: 35,                     //（可选项）数字类型；说明文字区域高度；默认：35.0
  4.         color: '#E0FFFF',               //（可选项）字符串类型；说明文字字体颜色，支持 rgb、rgba、#；默认：'#E0FFFF'
  5.         size: 13,                       //（可选项）数字类型；说明文字字体大小；默认：13.0
  6.         bgColor: '#696969',             //（可选项）字符串类型；说明文字区域的背景色，支持 rgb、rgba、#；默认：'#696969'
  7.         position: 'bottom'              //（可选项）字符串类型；说明文字区域的显示位置；默认：'bottom'
  8.                                         //取值范围：
  9.                                         //overlay（悬浮在图片上方，底部与图片底部对齐）
  10.                                         //bottom（紧跟在图片下方，顶部与图片底部对齐）
  11.         alignment: 'center'             //（可选项）字符串类型：说明文字在水平线上的位置；默认：left
  12.                                         //取值范围：
  13.                                         //right（居右限时）
  14.                                         //center（居中显示）
  15.                                         //left（居左显示）                                  
  16.     },
  17.     indicator: {                        //（可选项）JSON对象；指示器样式；不传则不显示指示器
  18.          dot:{                         // （可选项）JSON对象；指示器小圆点样式；不传则使用系统默认小圆点样式
  19.                            w:20,  //（必选项）数字类型；小圆点宽度
  20.                            h:10, //（必选项）数字类型；小圆点高度
  21.                            r:5,  //（必选项）数字类型；corner 页面控制器指示标记（矩形）的圆角大小
  22.                            margin:20  //（必选项）数字类型；小圆点间距
  23.                          },
  24.         align: 'center',                //（可选项）字符串类型；指示器位置；默认：center
  25.                                         //取值范围：
  26.                                         //center（居中）
  27.                                         //left（靠左）
  28.                                         //right（靠右）
  29.         color: '#FFFFFF',               //（可选项）指示器颜色 ，支持 rgb、rgba、#；默认：'#FFFFFF'
  30.         activeColor: '#DA70D6',          //（可选项）当前指示器颜色，支持 rgb、rgba、#；默认：'#DA70D6'
  31.         bottom:0                         //（可选项）页面控制器距离底部距离；默认：0
  32.     }
  33. }

placeholderImg：

  • 类型：字符串
  • 描述：（可选项）网络图片未加载完毕时，模块显示的占位图片，要求本地路径（fs://、widget://）

contentMode：

  • 类型：字符串
  • 描述：（可选项）图片填充模式
  • 默认值：’scaleToFill’
  • 取值范围：
    • scaleToFill（填充）
    • scaleAspectFit（适应）
    • ScaleAspectFill(填充，超出部分会被裁减掉)

cornerRadius：

  • 类型：数字
  • 描述：（可选项）图片的圆角半径
  • 默认值：0

scrollerCorner：

  • 类型：数字
  • 描述：（可选项）滑动视图的圆角半径
  • 默认值：0

interval：

  • 类型：数字
  • 描述：（可选项）图片轮换时间间隔，单位是秒（s）
  • 默认值：3

auto:

  • 类型：布尔
  • 描述：（可选项）图片是否自动播放
  • 默认值：true

loop:

  • 类型：布尔
  • 描述：（可选项）图片是否循环播放
  • 默认值：true

touchWait:

  • 类型：布尔
  • 描述：（可选项）触摸停止自动播放
  • 默认值：false

fixedOn：

  • 类型：字符串类型
  • 描述：（可选项）模块视图添加到指定 frame 的名字（只指 frame，传 window 无效）
  • 默认：模块依附于当前 window

fixed:

  • 类型：布尔
  • 描述：（可选项）模块是否随所属 window 或 frame 滚动
  • 默认值：true（不随之滚动）

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     status: true,                  //布尔型；true||false
  3.     eventType: 'click'||'show',    //字符串类型；交互事件类型，
  4.                                    //取值范围：
  5.                                    //click（用户点击）
  6.                                    //show（模块打开成功）
  7.     index：0                       //数字类型；当前图片的索引
  8. }

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.open({
  3.     rect: {
  4.         x: 0,
  5.         y: 0,
  6.         w: api.winWidth,
  7.         h: api.winHeight / 2
  8.     },
  9.     data: {
  10.         paths: [
  11.             'widget://res/img/apicloud.png',
  12.             'widget://res/img/apicloud-gray.png',
  13.             'widget://res/img/apicloud.png',
  14.             'widget://res/img/apicloud-gray.png'
  15.         ],
  16.         captions: ['apicloud', 'apicloud', 'apicloud', 'apicloud']
  17.     },
  18.     styles: {
  19.         caption: {
  20.             height: 35,
  21.             color: '#E0FFFF',
  22.             size: 13,
  23.             bgColor: '#696969',
  24.             position: 'bottom'
  25.         },
  26.         indicator: {
  27.            dot:{
  28.              w:20,
  29.              h:10,
  30.              r:5,
  31.              margin:20
  32.           },
  33.             align: 'center',
  34.             color: '#FFFFFF',
  35.             activeColor: '#DA70D6'
  36.         }
  37.     },
  38.     placeholderImg: 'widget://res/slide1.jpg',
  39.     contentMode: 'scaleToFill',
  40.     interval: 3,
  41.     fixedOn: api.frameName,
  42.     loop: true,
  43.     fixed: false
  44. }, function(ret, err) {
  45.     if (ret) {
  46.         alert(JSON.stringify(ret));
  47.     } else {
  48.         alert(JSON.stringify(err));
  49.     }
  50. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

close

关闭模块

close()

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.close();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示模块

show()

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.show();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏模块

hide()

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.hide();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setCurrentIndex

指定当前项

setCurrentIndex({params})

params

index：

  • 类型：数字
  • 描述：（可选项）索引值
  • 默认值：0

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.setCurrentIndex({
  3.     index: 2
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reloadData

更新模块数据

reloadData({params})

params

data：

  • 类型：JSON 对象
  • 描述：模块的图片路径数组，及说明文字数组
  • 内部字段：
  1. {
  2.     paths: [],      //（可选项）数组类型；图片路径数组；默认：原 paths 数组
  3.     captions: []    //（可选项）数组类型；说明文字数组，默认：原 captions 数组
  4. }

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.reloadData({
  3.     data: {
  4.         paths: ['widget://res/img/ic/slide1.jpg', 'widget://res/img/ic/slide2.jpg', 'widget://res/img/ic/slide5.jpg'],
  5.         captions: ['title1', 'title2', 'title3']
  6.     }
  7. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addEventListener

事件监听

addEventListener({params}, callback(ret, err))

params

name：

  • 类型：字符串
  • 描述：监听的事件名称，取值范围：’scroll’（图片滚动事件）

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 描述：事件触发时回调的参数，可能为空
  • 内部字段：
  1. {
  2.     status：true,    //布尔型；true||false
  3.     index：0         //数字类型；当前图片的索引
  4. }

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.addEventListener({
  3.     name: 'scroll'
  4. }, function(ret, err) {
  5.     if (ret) {
  6.         alert(JSON.stringify(ret));
  7.     } else {
  8.         alert(JSON.stringify(err));
  9.     }
  10. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearCache

清除缓存到本地的网络图片，本接口只清除本模块缓存的数据，若要清除本 app 缓存的所有数据则调用 api.clearCache

clearCache()

示例代码

  1. var UIScrollPicture = api.require('UIScrollPicture');
  2. UIScrollPicture.clearCache();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本