UIScrollPromptView

来自于：官方立即使用

open close show hide setCurrentIndex reloadData addEventListener clearCache

概述

UIScrollPromptView 是一个图片轮播模块，只需传入一组图片地址，即可实现图片轮播效果。本模块与 UIScrollPicture 模块类似，不同的是，开发者可在图片轮播区域内自定义一个按钮，用户点击该按钮弹出相应的提示框。

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

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

图片说明

模块接口

open

打开模块

open({params}, callback(ret))

params

rect：

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

data：

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

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.         align: 'center',                //（可选项）字符串类型；指示器位置；默认：center
  19.                                         //取值范围：
  20.                                         //center（居中）
  21.                                         //left（靠左）
  22.                                         //right（靠右）
  23.         color: '#FFFFFF',               //（可选项）字符串类型；指示器颜色 ，支持rgb、rgba、#；默认：'#FFFFFF'
  24.         activeColor: '#DA70D6'          //（可选项）字符串类型；当前指示器颜色，支持rgb、rgba、#；默认：'#DA70D6'
  25.     },
  26.     prompt: {                           // (可选项) JSON对象；提示框样式配置，若不传则不显示提示框及其触发按钮
  27.         button: {                       //（可选项）JSON对象；提示框触发按钮样式配置
  28.            normal: 'fs://srlBtBg.png',  // 字符串类型；触发提示框按钮的背景图片路径，支持本地图片（fs://、widget://）
  29.            x: 0,                        //（可选项）数字类型；按钮左上角的 x 坐标（相对于图片联播区域）；默认：0
  30.            y: 0,                        //（可选项）数字类型；按钮左上角的 y 坐标（相对于图片联播区域）；默认：按钮上下居中显示的位置
  31.            w: 60,                       //（可选项）数字类型；按钮的宽度；默认：60 
  32.            h: 40                        //（可选项）数字类型；按钮的高度；默认：40
  33.         },
  34.         x: 0,                           //（可选项）数字类型；提示框左上角的 x 坐标（相对于图片联播区域）；默认：0
  35.         y: 0,                           //（可选项）数字类型；提示框左上角的 y 坐标（相对于图片联播区域）；默认：提示框上下居中显示的位置
  36.         w: 160,                         //（可选项）数字类型；提示框的宽度；默认：160
  37.         h: 90,                          //（可选项）数字类型；提示框的高度；默认：90
  38.         contentMode: 'scaleToFill',     //（可选项）字符串类型；提示框内图片显示模式；默认值：'scaleToFill'，
  39.                                         // 取值范围如下：
  40.                                         // scaleToFill（填充）
  41.                                         // scaleAspectFit（适应）
  42.         animation: true                 //（可选项）布尔类型；弹出提示框时是否添加动画效果
  43.     }
  44. }

placeholderImg：

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

contentMode：

  • 类型：字符串
  • 描述：（可选项）图片填充模式
  • 默认值：’scaleToFill’
  • 取值范围：
    • scaleToFill（填充）
    • scaleAspectFit（适应）

interval：

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

auto:

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

loop:

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

fixedOn：

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

fixed:

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

callback(ret)

ret：

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

示例代码

  1. var UIScrollPromptView = api.require('UIScrollPromptView');
  2. UIScrollPromptView.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.         prompts: [
  18.             'widget://res/img/apicloud.png',
  19.             'widget://res/img/apicloud-gray.png',
  20.             'widget://res/img/apicloud.png',
  21.             'widget://res/img/apicloud-gray.png'
  22.         ]
  23.     },
  24.     styles: {
  25.         caption: {
  26.             height: 35,
  27.             color: '#E0FFFF',
  28.             size: 13,
  29.             bgColor: '#696969',
  30.             position: 'bottom'
  31.         },
  32.         indicator: {
  33.             align: 'center',
  34.             color: '#FFFFFF',
  35.             activeColor: '#DA70D6'
  36.         },
  37.         prompt: {
  38.             button: {
  39.                 normal: 'widget://image/btn_normal.png',
  40.                 highlight: 'widget://image/btn_highlight.png',
  41.                 x: 0,
  42.                 y: 100,
  43.                 w: 60,
  44.                 h: 40
  45.             },
  46.             x: 0,
  47.             y: 50,
  48.             w: 160,
  49.             h: 90,
  50.             contentMode: 'scaleToFill',
  51.             animation: true
  52.         }
  53.     },
  54.     placeholderImg: 'widget://res/slide1.jpg',
  55.     contentMode: 'scaleToFill',
  56.     interval: 3,
  57.     fixedOn: api.frameName,
  58.     loop: true,
  59.     fixed: false
  60. }, function(ret) {
  61.     if (ret) {
  62.         alert(JSON.stringify(ret));
  63.     }
  64. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

close

关闭模块

close()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示模块

show()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏模块

hide()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setCurrentIndex

指定当前项

setCurrentIndex({params})

params

index：

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

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reloadData

更新模块数据

reloadData({params})

params

data：

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

示例代码

  1. var UIScrollPromptView = api.require('UIScrollPromptView');
  2. UIScrollPromptView.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.         prompts: ['widget://res/img/ic/slide1.jpg', 'widget://res/img/ic/slide2.jpg', 'widget://res/img/ic/slide5.jpg']
  7.     }
  8. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addEventListener

事件监听

addEventListener({params}, callback(ret))

params

name：

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

callback(ret)

ret：

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

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearCache

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

clearCache()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本