photoBrowserTouTiao

来自于:开发者立即使用

概述

随着 APP 的使用,越来越多的图文信息出现在了移动网络中,用户对图文信息的查看也提出了更高的要求。而如何更好的将图文信息在用户面前呈现也成为了困扰很多 APP 的难题。

同时,仅仅图文信息的展示并不足以留住挑剔的用户,我们还需要提供炫酷的交互体验、分享、评论、关注、点赞等功能。

photoBrowserTouTiao 模块封装了今日头条客户端内相册浏览器功能,是由原生代码开发,为开发者封装了图文信息的最新主流展示界面,开发者只需要简单设置图片、颜色等即可让 APP 拥有完整的、高体验的图文信息展示界面,大大降低开发难度,节约开发成本,提高用户体验。

模块特点:

  • 点击主界面在纯图模式/功能模式之间切换

  • 双击主界面在大图模式/小图模式之间切换

  • 长按主界面弹出保存图片相关菜单

图片优化说明

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

示例图片如下:

图片说明

open

打开图文信息模块

open({params},callback(ret))

params

hidden:

  • 类型:JSON 对象
  • 描述:(可选项)界面元素的隐藏显示属性配置,默认值见内部字段
  • 内部字段:
{
      menu: ,           //布尔类型;是否显示菜单按钮;默认:true
      input: ,          //布尔类型;是否显示输入框;默认:true
      comment: ,        //布尔类型;是否显示评论按钮;默认:true
      favorite: ,       //布尔类型;是否显示收藏按钮;默认:true
      share: ,          //布尔类型;是否弹显示分享按钮;默认:true
      save:             //布尔类型;用户长按是否弹出保存图片按钮;默认:true
}

textStyles:

  • 类型:JSON 对象
  • 描述:(可选项)图片描述样式配置,若不传则描述文字按照1.0.0方式显示
  • 内部字段:
{
      min: 20,          //数字类型;描述文字显示最小区域占比;默认:20
      max: 40           //数字类型;描述文字显示最大区域占比;默认:40
}

说明:

描述文字显示区域占比是指:显示区域/允许显示区域(当前设备屏幕的高度减去顶部导航条和底部控制器的高度)。当用户点击图片描述区域时,描述文字显示区域会在min和max之间切换。

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    eventType: 'show',                 //字符串类型;交互事件类型,
                                       //取值范围:
                                       //show(模块打开成功)
                                       //setdata(模块数据设置完成)
                                       //back(返回按钮被点击)
                                       //publisher(发布人按钮被点击)
                                       //menu (菜单按钮被点击)
                                       //save(图片保存)
                                       //input(仿输入框被点击时触发)
                                       //comment(评论按钮被点击时触发)
                                       //favorite(收藏按钮被点击时触发)
                                       //share(分享按钮被点击时触发)

    status: true,                      //布尔类型;收藏按钮的选中状态,当收藏按钮被点击时有效                                 
    savePath: ''                       //字符串类型;图片保存到相册的路径,当 eventType 为 save 时有效
}

示例代码

var photoBS_tt = api.require('photoBrowserTouTiao');
photoBS_tt.open(function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setData

设置模块数据

setData({params})

params

images:

  • 类型:数组类型
  • 描述:图片路径数组数据,支持 fs://,以及网络路径 http://,https://
  • 内部字段:
[
    'http://www.x.com/image1.png',     //字符串类型;图片路径,支持fs://,以及网络路径 http://,https://
]

texts:

  • 类型:字符串数组类型
  • 描述:(可选项)描述数据
  • 默认:未设置时显示空描述,但依然会于显示指示器
  • 内部字段:
[
    '描述 1'                           //(可选项)字符串类型;描述内容;默认:未设置时对应索引的图片不显示描述
]

publisher:

  • 类型:字符串类型
  • 描述:(可选项)发布者按钮图标,位于头部右侧从右数第二个按钮。支持 widget://、fs://、http://、https:// 路径格式的图片。
  • 默认:未设置时不显示该按钮

comment:

  • 类型:数字类型
  • 描述:(可选项)评论角标数值,值为 0 时角标无效
  • 默认:0

favorite:

  • 类型:布尔类型
  • 描述:(可选项)收藏状态,值为 true 时显示 active 指定的图标。
  • 默认:false

示例代码

var photoBS_tt = api.require('photoBrowserTouTiao');
photoBS_tt.open(function(ret, err) {
    if (ret.eventType == 'show') {
        photoBS_tt.setData({
            images: [
                'http://www.x.com/image1.png',
                'http://www.x.com/image2.png',
                'http://www.x.com/image3.png',
                'http://www.x.com/image4.png'
            ],
            texts: [
                '描述 1', '描述2', '', '描述4'
            ],
            publisher: 'widget://photoBrowserTouTiao/publisher.png',
            comment: 520,
            favorite: false
        });
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

clearCache

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

clearCache()

示例代码

var photoBS_tt = api.require('photoBrowserTouTiao');
photoBS_tt.clearCache();

可用性

iOS系统,Android系统

refreshUI

刷新界面接口,本接口仅支持 ios 平台

使用场景:

在ios 平台上, 当适配横竖屏时,需要开发者监听当前屏幕方向,然后在屏幕旋转事件中调用本接口来刷新界面,否则会有UI错乱问题。android 平台不需调用本接口,android上会自适应横竖屏。

refreshUI()

示例代码

    var mql = window.matchMedia('(orientation: portrait)');
            console.log(mql);
            function handleOrientationChange(mql) {
                if(mql.matches) {
                     console.log('portrait');  // 竖屏
                 } else {
                     console.log('landscape'); // 横屏
                 }
                     var photoBrowserTouTiao = api.require('photoBrowserTouTiao');
                     photoBrowserTouTiao.refreshUI();
             }
   // 输出当前屏幕模式
   handleOrientationChange(mql);
   // 监听屏幕模式变化
   mql.addListener(handleOrientationChange);

可用性

iOS系统

可提供的1.0.0及更高版本