APICloudUIScrollPicture 模块

Posted 2020-11-29 aaabingbing

UIScrollPicture 模块

概述

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

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

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

模块接口

open

打开模块

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

params

rect:

类型：JSON 对象

描述：（可选项）模块的位置及尺寸

内部字段：

{
    x: 0,   //（可选项）数字类型；模块左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认：0
    y: 0,   //（可选项）数字类型；模块左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认：0
    w: 320, //（可选项）数字类型；模块的宽度；默认：‘auto‘
    h: 200  //（可选项）数字类型；模块的高度；默认：‘auto‘
}

data

类型：JSON 对象

描述：模块的图片路径数组，及说明文字数组

内部字段：

{
    paths: [],      //数组类型；图片路径数组，支持http://，https://，widget://，fs://协议
    captions: []    //（可选项）数组类型；说明文字数组，与 paths 数组长度一致；不传则不显示说明文字区域
}

style

类型：JSON 对象

描述：（可选项）模块各部分的样式

内部字段：

{
    caption: {                          //（可选项）JSON对象；说明文字区域样式
        height: 35,                     //（可选项）数字类型；说明文字区域高度；默认35.0
        color: ‘#E0FFFF‘,               //（可选项）字符串类型；说明文字字体颜色，支持 rgb、rgba、#；默认：‘#E0FFFF‘
        size: 13,                       //（可选项）数字类型；说明文字字体大小；默认：13.0
        bgColor: ‘#696969‘,             //（可选项）字符串类型；说明文字区域的背景色，支持 rgb、rgba、#；默认：‘#696969‘
        position: ‘bottom‘              //（可选项）字符串类型；说明文字区域的显示位置；默认：‘bottom‘
                                        //取值范围：
                                        //overlay（悬浮在图片上方，底部与图片底部对齐）
                                        //bottom（紧跟在图片下方，顶部与图片底部对齐）
        alignment: ‘center‘             //（可选项）字符串类型：说明文字在水平线上的位置；默认：left
                                        //取值范围：
                                        //right（居右限时）
                                        //center（居中显示）
                                        //left（居左显示）
    },
    indicator: {                        //（可选项）JSON对象；指示器样式；不传则不显示指示器
         dot:{                         // （可选项）JSON对象；指示器小圆点样式；不传则使用系统默认小圆点样式
                           w:20,  //（必选项）数字类型；小圆点宽度
                           h:10, //（必选项）数字类型；小圆点高度
                           r:5,  //（必选项）数字类型；corner 页面控制器指示标记（矩形）的圆角大小
                           margin:20  //（必选项）数字类型；小圆点间距
                         },
        align: ‘center‘,                //（可选项）字符串类型；指示器位置；默认：center
                                        //取值范围：
                                        //center（居中）
                                        //left（靠左）
                                        //right（靠右）
        color: ‘#FFFFFF‘,               //（可选项）指示器颜色 ，支持 rgb、rgba、#；默认：‘#FFFFFF‘
        activeColor: ‘#DA70D6‘,          //（可选项）当前指示器颜色，支持 rgb、rgba、#；默认：‘#DA70D6‘
        bottom:0                         //（可选项）页面控制器距离底部距离；默认：0
    }
}

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 对象

内部字段：

{
    status: true,                  //布尔型；true||false
    eventType: ‘click‘||‘show‘,    //字符串类型；交互事件类型，
                                   //取值范围：
                                   //click（用户点击）
                                   //show（模块打开成功）
    index：0                       //数字类型；当前图片的索引
}

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.open({
    rect: {
        x: 0,
        y: 0,
        w: api.winWidth,
        h: api.winHeight / 2
    },
    data: {
        paths: [
            ‘widget://res/img/apicloud.png‘,
            ‘widget://res/img/apicloud-gray.png‘,
            ‘widget://res/img/apicloud.png‘,
            ‘widget://res/img/apicloud-gray.png‘
        ],
        captions: [‘apicloud‘, ‘apicloud‘, ‘apicloud‘, ‘apicloud‘]
    },
    styles: {
        caption: {
            height: 35,
            color: ‘#E0FFFF‘,
            size: 13,
            bgColor: ‘#696969‘,
            position: ‘bottom‘
        },
        indicator: {
           dot:{
             w:20,
             h:10,
             r:5,
             margin:20
          },
            align: ‘center‘,
            color: ‘#FFFFFF‘,
            activeColor: ‘#DA70D6‘
        }
    },
    placeholderImg: ‘widget://res/slide1.jpg‘,
    contentMode: ‘scaleToFill‘,
    interval: 3,
    fixedOn: api.frameName,
    loop: true,
    fixed: false
}, function(ret, err) {
    if (ret) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性：ios 系统，android 系统，可提供的 1.0.0 及更高版本

close

关闭模块

close()

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.close();

可用性：iOS 系统，Android 系统，可提供的 1.0.0 及更高版本

show

显示模块

show()

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.show();

可用性：iOS 系统，Android 系统，可提供的 1.0.0 及更高版本

hide

隐藏模块

hide()

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.hide();

可用性：iOS 系统，Android 系统，可提供的 1.0.0 及更高版本

setCurrentIndex

指定当前项

setCurrentIndex({params})

params

index:

类型：数字

描述：（可选项）索引值

默认值：0

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.setCurrentIndex({
    index: 2
});

可用性：iOS 系统，Android 系统，可提供的 1.0.0 及更高版本

reloadData

更新模块数据

reloadData({params})

params

data:

类型：JSON 对象

描述：模块的图片路径数组，及说明文字数组

内部字段：

{
    paths: [],      //（可选项）数组类型；图片路径数组；默认：原 paths 数组
    captions: []    //（可选项）数组类型；说明文字数组，默认：原 captions 数组
}

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.reloadData({
    data: {
        paths: [‘widget://res/img/ic/slide1.jpg‘, ‘widget://res/img/ic/slide2.jpg‘, ‘widget://res/img/ic/slide5.jpg‘],
        captions: [‘title1‘, ‘title2‘, ‘title3‘]
    }
});

可用性：iOS 系统，Android 系统，可提供的 1.0.0 及更高版本

addEventListener

事件监听

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

params

name:

类型：字符串

描述：监听的事件名称，取值范围：‘scroll‘（图片滚动事件）

callback(ret,err)

ret：

类型：JSON 对象

描述：事件触发时回调的参数，可能为空

内部字段：

{
    status：true,    //布尔型；true||false
    index：0         //数字类型；当前图片的索引
}

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.addEventListener({
    name: ‘scroll‘
}, function(ret, err) {
    if (ret) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性：iOS 系统，Android 系统，可提供的 1.0.0 及更高版本

clearCache

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

clearCache()

示例代码

var UIScrollPicture = api.require(‘UIScrollPicture‘);
UIScrollPicture.clearCache();

可用性：iOS 系统，Android 系统，可提供的 1.0.0 及更高版本