1.README.md update

2.README.OpenSource update

Signed-off-by: zhoulisheng <635547767@qq.com>
This commit is contained in:
zhoulisheng 2022-04-13 19:42:16 +08:00
parent ddfdfc3d0d
commit 8ef13c94f8
2 changed files with 230 additions and 245 deletions

475
README.md
View File

@ -1,35 +1,244 @@
# ImageKnife
**专门为OpenHarmony打造的一款图像加载缓存库致力于更高效、更轻便、更简单**
**专门为OpenHarmony打造的一款图像加载缓存库致力于更高效、更轻便、更简单**
## 简介
本项目基于开源库 [Glide](https://github.com/bumptech/glide) 进行OpenHarmony的自研版本
本项目基于开源库 [Glide](https://github.com/bumptech/glide) 进行OpenHarmony的自研版本
- 支持内存缓存使用LRUCache算法对图片数据进行内存缓存
- 支持磁盘缓存,对于下载图片会保存一份至磁盘当中
- 支持进行图片变换
- 支持用户配置参数使用:(例如:配置是否开启第一级内存缓存,配置磁盘缓存策略,配置仅使用缓存加载数据,配置图片变换效果,配置占位图,配置加载失败占位图等)
- 推荐使用ImageKnifeComponent组件配合ImageKnifeOption参数来实现功能
- 支持用户自定义配置实现能力参考ImageKnifeComponent组件中对于入参ImageKnifeOption的处理
- 支持内存缓存使用LRUCache算法对图片数据进行内存缓存。
- 支持磁盘缓存,对于下载图片会保存一份至磁盘当中。
- 支持进行图片变换。
- 支持用户配置参数使用:(例如:配置是否开启第一级内存缓存,配置磁盘缓存策略,配置仅使用缓存加载数据,配置图片变换效果,配置占位图,配置加载失败占位图等)。
- 推荐使用ImageKnifeComponent组件配合ImageKnifeOption参数来实现功能。
- 支持用户自定义配置实现能力参考ImageKnifeComponent组件中对于入参ImageKnifeOption的处理。
<img src="screenshot/g3.gif" width="100%"/>
## 下载安装
1.参考安装教程 [如何安装OpenHarmony npm包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_npm_usage.md)
2.安装命令如下:
```
```typescript
npm install @ohos/imageknife --save
```
OpenHarmony npm环境配置等更多内容参考安装教程 [如何安装OpenHarmony npm包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_npm_usage.md)。
## 使用说明
[跳转至代码示例](##'代码示例')
1.首先初始化全局ImageKnife实例在app.ets中调用ImageKnife.with()进行初始化。
## 目录
```typescript
import {ImageKnife} from '@ohos/imageknife'
export default {
data: {
imageKnife: {} // ImageKnife全局占位符
},
onCreate() {
this.data.imageKnife = ImageKnife.with();// ImageKnife占位符全局初始化赋值
}
}
```
2.在页面index.ets中使用ImageKnife。
```typescript
@Entry
@Component
struct Index {
build() {
}
// 页面初始化完成,生命周期回调函数中 进行调用ImageKnife
aboutToAppear() {
let requestOption = new RequestOption();
requestOptin.load($r('app.media.IceCream'))
.addListener((err,data) => {
//加载成功/失败回调监听
})
...
ImageKnife.call(requestOption)
}
}
var ImageKnife;
var defaultTemp = globalThis.exports.default
if (defaultTemp != undefined) {
ImageKnife = defaultTemp.data.imageKnife;
}
```
#### 推荐使用:
使用ImageKnifeOption作为入参配合自定义组件ImageKnifeComponent使用。
```typescript
@Entry
@Component
struct Index {
@State imageKnifeOption1: ImageKnifeOption =
{
loadSrc: $r('app.media.jpgSample'),
size: { width: 300, height: 300 },
placeholderSrc: $r('app.media.icon_loading'),
errorholderSrc: $r('app.media.icon_failed'),
};
build() {
Scroll() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
ImageKnifeComponent({ imageKnifeOption: $imageKnifeOption1 })
}
}
.width('100%')
.height('100%')
}
}
```
#### 自定义实现:
使用原生Image组件配合用户配置参数实现。
##### 步骤1
定义自定义类。
```typescript
export default class PixelMapPack{
pixelMap:PixelMap;
}
```
使用@State关联PixelMapPack。
```typescript
@State imageKnifePixelMapPack:PixelMapPack = new PixelMapPack();
width:number = 200;
height:number = 200;
```
##### 步骤2
在你的component组件中写下一个Image组件将基础参数入参PixelMap组件的宽、高配置好。
```typescript
Image(this.imageKnifePixelMapPack.pixelMap)
.backgroundColor(Color.Grey)
.objectFit(ImageFit.Contain)
.width(this.width)
.height(this.height)
```
##### 步骤3
在aboutToAppear() 函数中调用加载流程。
```typescript
//配置参数
let requestOptin = new RequestOption();
//加载本地图片
requestOptin.load($r('app.media.jpgSample'))
.addListener((err,data) => {
//加载成功/失败回调监听
})
.placeholder( $r('app.media.icon_loading'), (data)=>{
// 占位图回调监听
})
.errorholder( $r('app.media.icon_failed'), (data)=>{
// 失败占位图回调监听
})
.thumbnail(0.3, (data) => {
// 缩略图加载成功回调
})
// 一定要把控件大小传给RequestOption,图片变换必须
.setImageViewSize({width:200, height:200})
// 设置缓存策略
.diskCacheStrategy(new AUTOMATIC())
.addProgressListener((percentValue: string) => {
// 图片网络加载进度条百分比回调
})
.addRetryListener((error: any) => {
// 加载失败重试监听 图片加载失败时优先展示重试图层,点击重试图层,会重新进行一次加载流程
})
// 左上圆角10pixel像素点
.roundedCorners({top:10})
// 启动加载流程,执行结果将会返回到上面的回调接口中
ImageKnife.call(requestOptin);
```
##### 步骤4
更多细节设置请参考自定义Component的ImageKnifeComponent实现。
## 接口说明
### RequestOpton 用户配置参数
| 方法名 | 入参 | 接口描述 |
| ------------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- |
| load(src: string \| PixelMap \| Resource) | string \| PixelMap \| Resource | 待加载图片的资源 |
| setImageViewSize(imageSize: { width: number, height: number }) | { width: number, height: number } | 传入显示图片组件的大小,变换的时候需要作为参考 |
| diskCacheStrategy(strategy: DiskStrategy) | DiskStrategy | 配置磁盘缓存策略 NONE SOURCE RESULT ALL AUTOMATIC |
| placeholder(src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap>) | src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap> | 配置占位图其中func为数据回调函数 |
| errorholder(src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap>) | src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap> | 配置加载失败占位图其中func为数据回调函数 |
| addListener(func: AsyncCallback<PixelMap>) | func: AsyncCallback<PixelMap> | 配置整个监听回调,数据正常加载返回,加载失败返回错误信息 |
| thumbnail(sizeMultiplier:number, func?: AsyncSuccess<ImageKnifeData>) | sizeMultiplier:number, func?: AsyncSuccess<ImageKnifeData> | 设置缩略图比例,缩略图返回后,加载并展示缩略图 |
| addProgressListener(func?: AsyncSuccess<string>){ this.progressFunc = func; return this; } | func?: AsyncSuccess<string> | 设置网络下载百分比监听,返回数据加载百分比数值 |
| addRetryListener(func?: AsyncSuccess<any>){ this.retryFunc = func; return this; } | func?: AsyncSuccess<any> | 设置重试监听 |
| addAllCacheInfoCallback(func: IAllCacheInfoCallback) | func: IAllCacheInfoCallback | 设置获取所有缓存信息监听 |
| skipMemoryCache(skip: boolean) | skip: boolean | 配置是否跳过内存缓存 |
| retrieveDataFromCache(flag: boolean) | flag: boolean | 配置仅从缓存中加载数据 |
同时支持[图片变换相关](##'图片变换相关')接口。
### ImageKnife 启动器/门面类
| 方法名 | 入参 | 接口描述 |
| ------------------------------- | ---------------------- | ---------------------------------- |
| call(request: RequestOption) | request: RequestOption | 根据用户配置参数具体执行加载流程 |
| preload(request: RequestOption) | request: RequestOption | 根据用户配置参数具体执行预加载流程 |
### 缓存策略相关
| 使用方法 | 类型 | 策略描述 |
| ------------------------------------------ | --------- | ---------------------------------------- |
| request.diskCacheStrategy(new ALL()) | ALL | 表示既缓存原始图片,也缓存转换过后的图片 |
| request.diskCacheStrategy(new AUTOMATIC()) | AUTOMATIC | 表示尝试对本地和远程图片使用最佳的策略 |
| request.diskCacheStrategy(new DATA()) | DATA | 表示只缓存原始图片 |
| request.diskCacheStrategy(new NONE()) | NONE | 表示不缓存任何内容 |
| request.diskCacheStrategy(new RESOURCE()) | RESOURCE | 表示只缓存转换过后的图片 |
### 图片变换相关
| 使用方法 | 类型 | 相关描述 |
| ------------------------------ | ---------------------------------- | ---------------------------------------------------- |
| request.centerCrop() | CenterCrop | 可以根据图片文件目标显示大小进行对应centerCrop |
| request.centerInside() | CenterInside | 可以根据图片文件目标显示大小进行对应centerInside |
| request.fitCenter() | FitCenter | 可以根据图片文件目标显示大小进行对应fitCenter |
| request.blur() | BlurTransformation | 模糊处理 |
| request.brightnessFilter() | BrightnessFilterTransformation | 亮度滤波器 |
| request.contrastFilter() | ContrastFilterTransformation | 对比度滤波器 |
| request.cropCircle() | CropCircleTransformation | 圆形剪裁显示 |
| request.cropCircleWithBorder() | CropCircleWithBorderTransformation | 圆环展示 |
| request.cropSquare() | CropSquareTransformation | 正方形剪裁 |
| request.crop() | CropTransformation | 自定义矩形剪裁 |
| request.grayscale() | GrayscaleTransformation | 灰度级转换 |
| request.invertFilter() | InvertFilterTransformation | 反转滤波器 |
| request.pixelationFilter() | PixelationFilterTransformation | 像素化滤波器 |
| request.rotateImage() | RotateImageTransformation | 图片旋转 |
| request.roundedCorners() | RoundedCornersTransformation | 圆角剪裁 |
| request.sepiaFilter() | SepiaFilterTransformation | 乌墨色滤波器 |
| request.sketchFilter() | SketchFilterTransformation | 素描滤波器 |
## 兼容性
支持 OpenHarmony API version 8 及以上版本。
## 目录结构
```
/imageknife/src/
@ -100,240 +309,16 @@ npm install @ohos/imageknife --save
- worker1.js # worker多线程测试
```
## 接口说明
## 贡献代码
### RequestOpton 用户配置参数
| 方法名 | 入参 | 接口描述 |
| ------------------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------- |
| load(src: string \| PixelMap \| Resource) | string \| PixelMap \| Resource | 待加载图片的资源 |
| setImageViewSize(imageSize: { width: number, height: number }) | { width: number, height: number } | 传入显示图片组件的大小,变换的时候需要作为参考 |
| diskCacheStrategy(strategy: DiskStrategy) | DiskStrategy | 配置磁盘缓存策略 NONE SOURCE RESULT ALL AUTOMATIC |
| placeholder(src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap>) | src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap> | 配置占位图其中func为数据回调函数 |
| errorholder(src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap>) | src: PixelMap \| Resource, func?: AsyncSuccess<PixelMap> | 配置加载失败占位图其中func为数据回调函数 |
| addListener(func: AsyncCallback<PixelMap>) | func: AsyncCallback<PixelMap> | 配置整个监听回调,数据正常加载返回,加载失败返回错误信息 |
| thumbnail(sizeMultiplier:number, func?: AsyncSuccess<ImageKnifeData>) | sizeMultiplier:number, func?: AsyncSuccess<ImageKnifeData> | 设置缩略图比例,缩略图返回后,加载并展示缩略图 |
| addProgressListener(func?: AsyncSuccess<string>){ this.progressFunc = func; return this; } | func?: AsyncSuccess<string> | 设置网络下载百分比监听,返回数据加载百分比数值 |
| addRetryListener(func?: AsyncSuccess<any>){ this.retryFunc = func; return this; } | func?: AsyncSuccess<any> | 设置重试监听 |
| addAllCacheInfoCallback(func: IAllCacheInfoCallback) | func: IAllCacheInfoCallback | 设置获取所有缓存信息监听 |
| skipMemoryCache(skip: boolean) | skip: boolean | 配置是否跳过内存缓存 |
| retrieveDataFromCache(flag: boolean) | flag: boolean | 配置仅从缓存中加载数据 |
同时支持[图片变换相关](##'图片变换相关')接口
### ImageKnife 启动器/门面类
| 方法名 | 入参 | 接口描述 |
| ------------------------------- | ---------------------- | ---------------------------------- |
| call(request: RequestOption) | request: RequestOption | 根据用户配置参数具体执行加载流程 |
| preload(request: RequestOption) | request: RequestOption | 根据用户配置参数具体执行预加载流程 |
### 缓存策略相关
| 使用方法 | 类型 | 策略描述 |
| ------------------------------------------ | --------- | ---------------------------------------- |
| request.diskCacheStrategy(new ALL()) | ALL | 表示既缓存原始图片,也缓存转换过后的图片 |
| request.diskCacheStrategy(new AUTOMATIC()) | AUTOMATIC | 表示尝试对本地和远程图片使用最佳的策略 |
| request.diskCacheStrategy(new DATA()) | DATA | 表示只缓存原始图片 |
| request.diskCacheStrategy(new NONE()) | NONE | 表示不缓存任何内容 |
| request.diskCacheStrategy(new RESOURCE()) | RESOURCE | 表示只缓存转换过后的图片 |
### 图片变换相关
| 使用方法 | 类型 | 相关描述 |
| ------------------------------ | ---------------------------------- | ---------------------------------------------------- |
| request.centerCrop() | CenterCrop | 可以根据图片文件目标显示大小进行对应centerCrop |
| request.centerInside() | CenterInside | 可以根据图片文件目标显示大小进行对应centerInside |
| request.fitCenter() | FitCenter | 可以根据图片文件目标显示大小进行对应fitCenter |
| request.blur() | BlurTransformation | 模糊处理 |
| request.brightnessFilter() | BrightnessFilterTransformation | 亮度滤波器 |
| request.contrastFilter() | ContrastFilterTransformation | 对比度滤波器 |
| request.cropCircle() | CropCircleTransformation | 圆形剪裁显示 |
| request.cropCircleWithBorder() | CropCircleWithBorderTransformation | 圆环展示 |
| request.cropSquare() | CropSquareTransformation | 正方形剪裁 |
| request.crop() | CropTransformation | 自定义矩形剪裁 |
| request.grayscale() | GrayscaleTransformation | 灰度级转换 |
| request.invertFilter() | InvertFilterTransformation | 反转滤波器 |
| request.pixelationFilter() | PixelationFilterTransformation | 像素化滤波器 |
| request.rotateImage() | RotateImageTransformation | 图片旋转 |
| request.roundedCorners() | RoundedCornersTransformation | 圆角剪裁 |
| request.sepiaFilter() | SepiaFilterTransformation | 乌墨色滤波器 |
| request.sketchFilter() | SketchFilterTransformation | 素描滤波器 |
## 代码示例
1.首先初始化全局ImageKnife实例在app.ets中调用ImageKnife.with()进行初始化
```
import {ImageKnife} from '@ohos/imageknife'
export default {
data: {
imageKnife: {} // ImageKnife全局占位符
},
onCreate() {
this.data.imageKnife = ImageKnife.with();// ImageKnife占位符全局初始化赋值
}
}
```
2.在页面index.ets中使用ImageKnife
```
@Entry
@Component
struct Index {
build() {
}
// 页面初始化完成,生命周期回调函数中 进行调用ImageKnife
aboutToAppear() {
let requestOption = new RequestOption();
requestOptin.load($r('app.media.IceCream'))
.addListener((err,data) => {
//加载成功/失败回调监听
})
...
ImageKnife.call(requestOption)
}
}
var ImageKnife;
var defaultTemp = globalThis.exports.default
if (defaultTemp != undefined) {
ImageKnife = defaultTemp.data.imageKnife;
}
```
#### 推荐使用:
使用ImageKnifeOption作为入参配合自定义组件ImageKnifeComponent使用。
```typescript
@Entry
@Component
struct Index {
@State imageKnifeOption1: ImageKnifeOption =
{
loadSrc: $r('app.media.jpgSample'),
size: { width: 300, height: 300 },
placeholderSrc: $r('app.media.icon_loading'),
errorholderSrc: $r('app.media.icon_failed'),
};
build() {
Scroll() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
ImageKnifeComponent({ imageKnifeOption: $imageKnifeOption1 })
}
}
.width('100%')
.height('100%')
}
}
```
#### 自定义实现:
使用原生Image组件配合用户配置参数实现。
##### 步骤1
定义自定义类
```
export default class PixelMapPack{
pixelMap:PixelMap;
}
```
使用@State关联PixelMapPack
```typescript
@State imageKnifePixelMapPack:PixelMapPack = new PixelMapPack();
width:number = 200;
height:number = 200;
```
##### 步骤2
在你的component组件中写下一个Image组件将基础参数入参PixelMap组件的宽、高配置好
```
Image(this.imageKnifePixelMapPack.pixelMap)
.backgroundColor(Color.Grey)
.objectFit(ImageFit.Contain)
.width(this.width)
.height(this.height)
```
##### 步骤3
在aboutToAppear() 函数中调用加载流程
```typescript
//配置参数
let requestOptin = new RequestOption();
//加载本地图片
requestOptin.load($r('app.media.jpgSample'))
.addListener((err,data) => {
//加载成功/失败回调监听
})
.placeholder( $r('app.media.icon_loading'), (data)=>{
// 占位图回调监听
})
.errorholder( $r('app.media.icon_failed'), (data)=>{
// 失败占位图回调监听
})
.thumbnail(0.3, (data) => {
// 缩略图加载成功回调
})
// 一定要把控件大小传给RequestOption,图片变换必须
.setImageViewSize({width:200, height:200})
// 设置缓存策略
.diskCacheStrategy(new AUTOMATIC())
.addProgressListener((percentValue: string) => {
// 图片网络加载进度条百分比回调
})
.addRetryListener((error: any) => {
// 加载失败重试监听 图片加载失败时优先展示重试图层,点击重试图层,会重新进行一次加载流程
})
// 左上圆角10pixel像素点
.roundedCorners({top:10})
// 启动加载流程,执行结果将会返回到上面的回调接口中
ImageKnife.call(requestOptin);
```
##### 步骤4
更多细节设置请参考自定义Component的ImageKnifeComponent实现
## 演示
<img src="screenshot/g3.gif" width="50%"/>
<img src="screenshot/g1.gif" width="50%"/><img src="screenshot/g2.gif" width="50%"/>
## 兼容性
支持OpenHarmony API version 8 及以上版本
使用过程中发现任何问题都可以提 [issue](https://gitee.com/openharmony-tpc/ImageKnife/issues) 给我们,当然,我们也非常欢迎你给我们发 [PR](https://gitee.com/openharmony-tpc/ImageKnife/issues) 。
## 开源协议
[协议详见](https://gitee.com/openharmony-tpc/ImageKnife/blob/master/LICENSE)
## 贡献代码
使用过程中发现任何问题都可以提[issue](https://gitee.com/openharmony-tpc/ImageKnife/issues)给我们,当然,我们也非常欢迎你给我们发[PR](https://gitee.com/openharmony-tpc/ImageKnife/issues)
本项目基于 [Apache License 2.0](https://gitee.com/openharmony-tpc/ImageKnife/blob/master/LICENSE) ,请自由的享受和参与开源
## 遗留问题
1.图片变换缓慢(待优化)
1.图片变换缓慢(待优化)。
2.目前只支持一种图片变换效果
2.目前只支持一种图片变换效果。