SDWebImage

open

close

show

hide

reset

cacheSize

clearMemory

clearDisk

download

getCachePath

imageCached

概述

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/12/2