UIScrollPicture

close hide reloadData clearCache

论坛示例

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

概述

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

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

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

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

不能同时添加的模块：fog2

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

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

模块接口

open

打开模块

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

params

rect：

  • 类型：JSON 对象
  • 描述：（可选项）模块的位置及尺寸
  • 内部字段：

data：

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

placeholderImg：

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

contentMode：

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

cornerRadius：

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

scrollerCorner：

  • 类型：数字
  • 描述：（可选项）滑动视图的圆角半径
  • 默认值：0
  • 类型：数字
  • 描述：（可选项）图片轮换时间间隔，单位是秒（s）
  • 默认值：3

auto:

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

loop:

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

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                       //数字类型；当前图片的索引

示例代码

可用性

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系统

setCurrentIndex

指定当前项

setCurrentIndex({params})

params

index：

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

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reloadData

更新模块数据

reloadData({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. }

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearCache

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

clearCache()

  1. UIScrollPicture.clearCache();

可用性

iOS系统，Android系统