SDWebImage

概述

SDWebImage 具有缓存支持的异步映像下载程序。原生实现异步下载功能,子线程操作从而保证不会阻塞主线程。先用 open 接口(或者AVM方式)打开一个图片插件,同时设置图片的网络路径和本地占位图路径。即可自动下载图片,下载完成后会自动显示并隐藏占位图。下载的图片会被自动保存在硬盘(可通过 getCachePath 接口可获取其绝对路径),短期内也会被缓存在运行内存里(可通过 clearMemory 接口清除运行内存中的缓存)。再次使用同一张图片时,插件会自动从运行内存里获取并渲染出来。若此时运行内存内的缓存已被清除,则直接去缓存的硬盘读取,当然得保证这时候硬盘上的缓存并没有被清除(clearDisk 接口)。如果硬盘缓存也被清除则重新从网络下载。

插件存储图片时,是先把图片的 URL 签名生产一个 key,然后以此为 ID对图片进行存储、查询。所以 getCachePath 接口必须传入正确的图片 URL,若图片 URL 改变则会被认为是一张新的图片,此时需要走新图片下载的逻辑。如果你只是想下载网络图片,并不需要把图片展示出来,那么可以直接用 download 接口下载,此时图片缓存逻辑同 open 一致。

关于AVM方式

本插件支持 AVM 方式打开。通过 AVM 标签方式打开的插件,在 js 代码中需要通过 document.getElementById 的形式获取该插件实例对象然后进行其它逻辑的操作(hide、show)。否则会产生莫名其妙的问题。

示例:

<mo-gifimage id="engine3GifImage"></mo-sdwebimage>

该插件同时也支持 api.require 方式调用,通过 open 接口相当于 AVM 的标签打开了一个图片显示区域的 frame(view)插件。

插件接口

open

打开自带缓存功能的图片

open({params},callback(ret))

params

imgURL:

  • 类型:字符串
  • 描述:网络图片路径

placeholder:

  • 类型:字符串
  • 描述:占位图图片片路径,要求本地路径fs://、widget://

rect:

  • 类型:JSON 类型
  • 描述:(可选项)GIF 图片显示区域的位置及大小
  • 内部字段:
{
    x: 0,        //(可选项)数字类型;插件左上角的 x 坐标(相对于所属的 Window 或 Frame);默认值:0
    y: 0,        //(可选项)数字类型;插件左上角的 y 坐标(相对于所属的 Window 或 Frame);默认值:0
    w:300,       //(可选项)数字类型;插件宽度(相对于所属的 Window 或 Frame;默认:100%
    h:600        //(可选项)数字类型;插件高度(相对于所属的 Window 或 Frame;默认:100%
}

fixedOn:

  • 类型:字符串类型
  • 描述:(可选项)插件添加到指定 frame 的名字(只指 frame,传 window 无效)
  • 默认:预览窗口依附于当前 window

fixed:

  • 类型:布尔
  • 描述:(可选项)预览窗口是否随所属 window 或 frame 滚动
  • 默认值:true(不随之滚动)

callback(ret)

  • 类型:JSON对象
  • 描述:回调插件ID
  • 内部字段:
{
     eventType:'',  //字符串类型;交互事件类型;取值范围:
                    //show:显示
                    //finished:加载完成
                    //loading:正在加载
     ID:            //字符串类型;打开的图片的 ID
}

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.open({
  imgURL:'',
  rect:{
    x:,
    y:,
    w:,
    h:
  },
  fixedOn:'',
  fixed:false
},function(ret){
    if(ret.eventType == 'loading') {
        console.log(JSON.stringify(ret));
    } else {
        api.alert({msg:JSON.stringify(ret)});
    }
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

close

关闭 open 接口打开的图片

close({params},callback(ret))

params

ID:

  • 类型:字符串
  • 描述:图片的 ID

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.close({
  ID:
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

show

显示 open 接口打开的图片

show({params},callback(ret))

params

ID:

  • 类型:字符串
  • 描述:图片的 ID

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.show({
  ID:
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

hide

隐藏 open 接口打开的图片

hide({params},callback(ret))

params

ID:

  • 类型:字符串
  • 描述:图片的 ID

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.hide{
  ID:
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

reset

重设指定图片的位置和大小

reset({params},callback(ret))

params

ID:

  • 类型:字符串
  • 描述:重设的图片的 ID

rect:

  • 类型:JSON 类型
  • 描述:(可选项)图片显示区域的位置及大小
  • 内部字段:
{
    x: 0,        //(可选项)数字类型;插件左上角的 x 坐标(相对于所属的 Window 或 Frame);默认值:0
    y: 0,        //(可选项)数字类型;插件左上角的 y 坐标(相对于所属的 Window 或 Frame);默认值:0
    w:300,       //(可选项)数字类型;插件宽度(相对于所属的 Window 或 Frame;默认:100%
    h:600        //(可选项)数字类型;插件高度(相对于所属的 Window 或 Frame;默认:100%
}

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.reset({
  rect:{
    x:,
    y:,
    w:,
    h:
  }
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

cacheSize

获取已经缓存的图片的大小

cacheSize(callback(ret))

callback(ret)

  • 类型:JSON对象
  • 描述:回调插件ID
  • 内部字段:
{
     size:'',  //数字类型;缓存大小
     count:    //数字类型;缓存的图片个数
}

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.cacheSize(function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

clearMemory

清除内存缓存

clearMemory()

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.clearMemory()

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

clearDisk

清除硬盘缓存

clearDisk()

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.clearDisk()

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

download

下载图片 (Android 不支持该方法)

download({params},callback(ret))

params

imgURL:

  • 类型:字符串
  • 描述:网络图片路径

callback(ret)

  • 类型:JSON对象
  • 描述:回调插件
  • 内部字段:
{
     eventType:'',  //字符串类型;交互事件类型;取值范围:
                    //show:显示
                    //finished:加载完成
                    //loading:正在加载
                    //saved:已成功保存到硬盘
     cachePath:'',  //字符串类型;缓存到本地的路径,仅当 eventType 为 saved 时有值
     receivedSize:  //数字类型;已接受的大小,仅当 eventType 为 loading 时有值
     expectedSize:  //数字类型;剩余大小,仅当 eventType 为 loading 时有值
}

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.download({
  imgURL:''
},function(ret){
    if(ret.eventType == 'loading') {
        console.log(JSON.stringify(ret));
    } else {
        api.alert({msg:JSON.stringify(ret)});
    }
})

可用性

iOS 系统

可提供的 1.0.0 及更高版本

getCachePath

获取本地缓存图片的路径

getCachePath({params},callback(ret))

params

imgURL:

  • 类型:字符串
  • 描述:网络图片路径

callback(ret)

  • 类型:JSON对象
  • 描述:回调插件
  • 内部字段:
{
     cachePath:'',  //字符串类型;图片路径
}

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.getCachePath({
  imgURL:''
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

imageCached

是否已缓存

imageCached({params},callback(ret))

params

imgURL:

  • 类型:字符串
  • 描述:网络图片路径

callback(ret)

  • 类型:JSON对象
  • 描述:回调插件
  • 内部字段:
{
     isInCache:'',  //布尔类型;是否已缓存
}

示例代码

var SDWebImage = api.require('SDWebImage');
SDWebImage.imageCached({
  imgURL:''
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

是否仍需要帮助? 请保持联络!
最后更新于 2024/07/10