欢迎使用 nativescript-fresco

一个适用于 Android 应用的 NativeScript 插件。

nativescript-fresco 是什么？

nativescript-fresco 是一个 NativeScript 插件，它公开了用于在 Android 上高效显示图像的 Fresco 库。有关 Fresco 是什么以及它如何工作的更多信息，请访问其官方网站 这里。

nativescript-fresco 插件使 NativeScript 开发者能够使用 FrescoDrawee 类，它扩展了传统的 Android ImageView 组件并添加了智能的 Fresco 图像管理算法。该插件将 drawee 作为 NativeScript 视图公开，因此您只需将其放入页面 XML 定义中，并提供您要使用的图像的 URI。

如何使用 nativescript-fresco？

在纯 NativeScript 中

从 npm

1. 转到您想要安装插件的 {N} 应用程序的根目录，并输入 tns plugin add nativescript-fresco。
2. 使用以下代码在 {N} 应用的 launch 事件中初始化 nativescript-fresco：

从本地仓库？

1. 克隆仓库并转到您的计算机上的根目录。
2. 使用 tsc 将 .ts 源代码转译： tsc -p。
3. 转到您想要安装插件的 {N} 应用的根目录，并输入 tns plugin add <path-to-fresco-repo-dir>。
4. 使用以下代码在 {N} 应用的 launch 事件中初始化 nativescript-fresco：

JavaScript

var application = require("application");
var fresco = require("nativescript-fresco");

if (application.android) {
    application.onLaunch = function (intent) {
        fresco.initialize();
    };
}

TypeScript

import application = require("application");
import fresco = require("nativescript-fresco");

if (application.android) {
    application.onLaunch = function (intent) {
        fresco.initialize();
    };
}

在页面的 XML 定义中使用 fresco 如下所示

<Page
    xmlns="http://www.nativescript.org/tns.xsd" 
    xmlns:nativescript-fresco="nativescript-fresco">
    <nativescript-fresco:FrescoDrawee width="250" height="250"
                                      imageUri="<uri-to-a-photo-from-the-web-or-a-local-resource>"/>
</Page>

在 NativeScript + Angular 2 中

1. 从 nativescript-fresco/angular 导入 TNSFrescoModule 并将其添加到您的初始 @NgModule 的 imports 中，如这里所示。
2. 如上所述，请确保在 {N} 应用的 launch 事件中初始化 nativescript-fresco 插件。

示例

您可以参考仓库中的 demo 文件夹，其中包含可运行的 {N} 项目，演示了带有所有功能的 nativescript-fresco 插件。

功能

如 Fresco 库所述，设置 高度和宽度 是 强制性的，有关此主题的更多详细信息，请参阅 这里。因此，在声明 FrescoDrawee 时，您应该首先设置其 宽度 和 高度 属性，或者只设置其中一个并设置 FrescoDrawee 的 aspectRatio。FrescoDrawee 在您的 {N} 应用程序中支持百分比，这使得您可以将宽度声明为 width="50%" 并设置 aspectRatio="1.33"，从而实现精确的 50% 宽度，并基于从 imageUri 加载的图像的宽高比动态计算高度。

基本属性

• imageUri

用于图像URI的字符串值。您可以使用此属性来设置从远程位置（http、https）、从您的 {N} 应用程序的资源文件和本地文件加载的图像。

<nativescript-fresco:FrescoDrawee imageUri="https://docs.nativescript.cn/angular/img/cli-getting-started/angular/chapter0/NativeScript_logo.png"/>

• placeholderImageUri

用于占位符图像URI的字符串值。您可以使用此属性来设置从您的 {N} 应用程序的本地和资源文件加载的占位符图像。

*注意：目前在对 'placeholderImage' 设置不同图像的数量达到 OutOfMemoryError 之前存在限制。为了获得最佳效果，建议为您的 FrescoDrawee 实例的所有 placeholderImageUri 使用单个图像。

<nativescript-fresco:FrescoDrawee placeholderImageUri="~/placeholder.jpg"/>

• failureImageUri

用于失败图像URI的字符串值。您可以使用此属性来设置从您的 {N} 应用程序的本地和资源文件加载的失败图像，如果图像Uri的加载不成功，将显示此图像。

<nativescript-fresco:FrescoDrawee failureImageUri="~/failure.jpg"/>

高级 可选 属性

有一些 可选 属性可以设置在 FrescoDrawee 实例上，以实现高级行为

• backgroundUri

用于背景图像URI的字符串值。使用此属性的效果与 placeholderImageUri 类似，但图像会被拉伸到 FrescoDrawee 的大小。

*注意：目前在对 'background' 设置不同图像的数量达到 OutOfMemoryError 之前存在限制。为了获得最佳效果，建议为您的 FrescoDrawee 实例的所有 backgroundUri 使用单个图像。

<nativescript-fresco:FrescoDrawee backgroundUri="~/image.jpg"/>

• actualImageScaleType

FrescoDrawee 图像缩放类型所使用的字符串值。此属性可以设置为

'center' - 不进行缩放。

'centerCrop' - 缩放子元素，使其两个维度都大于或等于父元素对应的维度。

'centerInside' - 缩放子元素，使其完全适合父元素内部。

'fitCenter' - 缩放子元素，使其完全适合父元素内部。

'fitStart' - 缩放子元素，使其完全适合父元素内部。

'fitEnd' - 缩放子元素，使其完全适合父元素内部。

'fitXY' - 独立缩放宽度和高度，使子元素与父元素完全匹配。

'focusCrop' - 缩放子元素，使其两个维度都大于或等于父元素对应的维度。

<nativescript-fresco:FrescoDrawee actualImageScaleType="centerInside"/>

• fadeDuration

用于淡入持续时间的数字值。此值以毫秒为单位。

<nativescript-fresco:FrescoDrawee fadeDuration="3000"/>

• aspectRatio

用作图像宽高比的数字值。当您处理不同宽高比图像并希望具有固定宽度或高度时，此属性非常有用。图像的比率是通过将其宽度除以高度来计算的。

注意：在某些布局场景中，有必要将 FrescoDrawee 的 verticalAlignment 设置为 'top' 或 'bottom'，以便“锚定”drawee 并实现动态大小。

<nativescript-fresco:FrescoDrawee aspectRatio="1.33" verticalAlignment="top"/>

• progressiveRenderingEnabled

用于启用或禁用渐进式 JPEG 图像流式的布尔值。此属性默认设置为 'false'。在加载非渐进式编码的 JPEG 图像时将此属性设置为 'true' 将导致这些图像以标准方式加载。

<nativescript-fresco:FrescoDrawee progressiveRenderingEnabled="true"/>

• showProgressBar

用于显示或隐藏进度条的布尔值。

<nativescript-fresco:FrescoDrawee showProgressBar="true"/>

• progressBarColor

用于设置进度条颜色的字符串值。您可以将它设置为十六进制值（"#FF0000"）和/或预定义颜色（"green"）。

<nativescript-fresco:FrescoDrawee progressBarColor="blue"/>

• roundAsCircle

用于确定图像是否以圆形圆润的布尔值。其默认值为 false。如果设置为 true，则图像将更圆以形成圆形。

<nativescript-fresco:FrescoDrawee roundAsCircle="true"/>

• roundedCornerRadius

用于圆润图像角落的半径的数字值。

<nativescript-fresco:FrescoDrawee roundedCornerRadius="50"/>

• roundBottomRight

布尔值，用于确定图像的右下角是否需要圆角。使用roundedCornerRadius作为圆角半径。

<nativescript-fresco:FrescoDrawee roundBottomRight="true"/>

• roundBottomLeft

布尔值，用于确定图像的左下角是否需要圆角。使用roundedCornerRadius作为圆角半径。

<nativescript-fresco:FrescoDrawee roundBottomLeft="true"/>

• roundTopLeft

布尔值，用于确定图像的左上角是否需要圆角。使用roundedCornerRadius作为圆角半径。

<nativescript-fresco:FrescoDrawee roundTopLeft="true"/>

• roundTopRight

布尔值，用于确定图像的右上角是否需要圆角。使用roundedCornerRadius作为圆角半径。

<nativescript-fresco:FrescoDrawee roundTopRight="true"/>

• autoPlayAnimations

布尔值，用于启用自动播放动画图像。注意，不支持此类图像的圆角，将被忽略。

<nativescript-fresco:FrescoDrawee autoPlayAnimations="true"/>

• tapToRetryEnabled

布尔值，用于启用/禁用FrescoDrawee图像下载的重试触摸操作。

<nativescript-fresco:FrescoDrawee tapToRetryEnabled="true"/>

事件

• finalImageSet - 参数 FinalEventData

此事件在最终图像设置后触发。当处理动画图像时，可以通过调用FinalEventData.animatable.start()函数来启动动画。

<nativescript-fresco:FrescoDrawee finalImageSet="onFinalImageSet"/>

JavaScript

function onFinalImageSet(args) {
    var frescoEventData = args;
    var drawee = frescoEventData.object;
}
exports.onFinalImageSet = onFinalImageSet;

TypeScript

import {FrescoDrawee, FinalEventData } from "nativescript-fresco";

export function onFinalImageSet(args: FinalEventData) {
    var drawee = args.object as FrescoDrawee;
}

• failure - 参数 FailureEventData

在获取最终图像失败后触发此事件。

<nativescript-fresco:FrescoDrawee failure="onFailure"/>

JavaScript

function onFailure(args) {
    var drawee = args.object;
}
exports.onFailure = onFailure;

TypeScript

import {FrescoDrawee, FailureEventData } from "nativescript-fresco";

export function onFailure(args: FailureEventData) {
    var drawee = args.object as FrescoDrawee;
}

• intermediateImageSet - 参数 IntermediateEventData

在设置任何中间图像后触发此事件。

<nativescript-fresco:FrescoDrawee intermediateImageSet="onIntermediateImageSet"/>

JavaScript

function onIntermediateImageSet(args) {
    var drawee = args.object;
}
exports.onIntermediateImageSet = onIntermediateImageSet;

TypeScript

import {FrescoDrawee, IntermediateEventData } from "nativescript-fresco";

export function onIntermediateImageSet(args: IntermediateEventData) {
    var drawee = args.object as FrescoDrawee;
}

• intermediateImageFailed - 参数 FailureEventData

在获取中间图像失败后触发此事件。

<nativescript-fresco:FrescoDrawee intermediateImageFailed="onIntermediateImageFailed"/>

JavaScript

function intermediateImageFailed(args) {
    var drawee = args.object;
}
exports.intermediateImageFailed = intermediateImageFailed;

TypeScript

import {FrescoDrawee, FailureEventData } from "nativescript-fresco";

export function intermediateImageFailed(args: FailureEventData) {
    var drawee = args.object as FrescoDrawee;
}

• submit - 参数 EventData

在提交图像请求之前触发此事件。

<nativescript-fresco:FrescoDrawee submit="onSubmit"/>

JavaScript

function onSubmit(args) {
    var drawee = args.object;
}
exports.onSubmit = onSubmit;

TypeScript

import {FrescoDrawee, EventData } from "nativescript-fresco";

export function onSubmit(args: EventData) {
    var drawee = args.object as FrescoDrawee;
}

• release - 参数 EventData

在控制器释放获取的图像后触发此事件。

<nativescript-fresco:FrescoDrawee release="onRelease"/>

JavaScript

function onRelease(args) {
    var drawee = args.object;
}
exports.onRelease = onRelease;

TypeScript

import {FrescoDrawee, EventData } from "nativescript-fresco";

export function onRelease(args: EventData) {
    var drawee = args.object as FrescoDrawee;
}

事件参数

'nativescript-fresco'公开的所有事件都为其处理程序提供了处理事件所需的信息。以下是每个事件附带的事件参数的简要描述。

• FinalEventData

此类的实例提供给finalImageSet的处理程序。

import {FrescoDrawee, FinalEventData, ImageInfo, AnimatedImage } from "nativescript-fresco";

export function onFinalImageSet(args: FinalEventData) {
    var info: ImageInfo  = args.imageInfo;
    var animatable: AnimatedImage = args.animatable;
    var quality: number = info.getQualityInfo().getQuality();
    var isFullQuality: boolean = info.getQualityInfo().isOfFullQuality();
    var isOfGoodEnoughQuality: boolean = info.getQualityInfo().isOfGoodEnoughQuality();
}

• FailureEventData

此类的实例提供给failure和intermediateImageFailed的处理程序。

import {FrescoDrawee, FailureEventData, FrescoError } from "nativescript-fresco";

export function onFailure(args: FailureEventData) {
    var error: FrescoError = args.error;
    var message: string = error.getMessage();
    var type: string = error.getErrorType();
    var fullError: string = error.toString();
}

• IntermediateEventData

此类的实例提供给intermediateImageSet的处理程序。

import {FrescoDrawee, IntermediateEventData, ImageInfo } from "nativescript-fresco";

export function onIntermediateImageSet(args: IntermediateEventData) {
    var info: ImageInfo  = args.imageInfo;
    var quality: number = info.getQualityInfo().getQuality();
    var isFullQuality: boolean = info.getQualityInfo().isOfFullQuality();
    var isOfGoodEnoughQuality: boolean = info.getQualityInfo().isOfGoodEnoughQuality();}

• EventData

此类的实例提供给release和submit的处理程序。

import {FrescoDrawee, EventData } from "nativescript-fresco";

export function onSubmit(args: EventData) {
    var drawee = args.object as FrescoDrawee;
}

缓存

nativescript-fresco {N}插件具有内置的缓存机制，用于管理内存中的图像。有两种类型的缓存机制：memory和disk，您可以使用以下功能手动管理这两个。

刷新'imageUri'

不经常的情况下，您可能会遇到远程服务中的实际图像从FrescoDrawee的imageUri已更改，但{n}应用程序已经在其内部缓存中有一个图像的情况。在这种情况下，您可以通过调用updateImageUri()轻松地刷新imageUri。

// 'drawee' is the instance the 'FrescoDrawee' in the project.
drawee.updateImageUri();

从缓存中清除一切

通过ImagePipeline管理nativescript-fresco中的缓存。要获取ImagePipeline的引用，只需调用getImagePipeline()函数。

var frescoModel = require("nativescript-fresco");

var imagePipeLine = frescoModel.getImagePipeline();

• 清除内存和磁盘缓存

imagePipeLine.clearCaches();

• 清除内存缓存

imagePipeLine.clearMemoryCaches();

• 清除磁盘缓存

imagePipeLine.clearDiskCaches();

从缓存中清除具有特定URI的所有图像

如果清除整个缓存不是您所希望的，您可以通过ImagePipeline清除与特定URI（imageUri）链接的图像。清除操作再次通过ImagePipeline执行。

var frescoModel = require("nativescript-fresco");

var imagePipeLine = frescoModel.getImagePipeline();

• 从内存和磁盘缓存中清除URI

imagePipeLine.evictFromCache("<uri-to-a-photo-from-the-web>");

• 从内存缓存中清除URI

imagePipeLine.evictFromMemoryCache("<uri-to-a-photo-from-the-web>");

• 从磁盘缓存中清除URI

imagePipeLine.evictFromDiskCache("<uri-to-a-photo-from-the-web>");

示例截图

所有图像都是用于展示的示例图像。

示例1 - 占位符图像	示例2 - 过渡（淡入动画）

示例3 - 成功从imageUri显示图像	示例4 - 显示'失败'图像