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

从本地仓库？

1. 克隆仓库并转到计算机上的根目录。
2. 使用 tsc 将 .ts 源文件转译：tsc -p。
3. 转到您想要安装插件的应用程序的根目录，并输入 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 插件。

示例

您可以在仓库的 示例 文件夹中查看可运行的 {N} 项目，该项目演示了带有所有功能的 nativescript-fresco 插件。

功能

如 Fresco 库所述，设置 高度和宽度 是 必需的，有关此主题的更多详细信息可以在 此处 找到。因此，在声明 FrescoDrawee 时，您应该首先设置其 宽度 和 高度 属性，或者只设置其中一个并设置 FrescoDrawee 的 aspectRatio。在您的 {N} 应用程序中，FrescoDrawee 的宽度和高度支持百分比，这使得您可以将宽度声明为 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} 应用程序的本地和资源文件中加载的占位符图像。

*注意：目前在使用抛出 OutOfMemoryError 之前，可以设置的“placeholderImage”的不同图像数量有限制。为了获得最佳结果，建议为所有 FrescoDrawee 实例的 placeholderImageUri 使用单个图像。

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

• failureImageUri

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

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

高级 可选 属性

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

• backgroundUri

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

*注意：目前在使用抛出 OutOfMemoryError 之前，可以设置的“background”的不同图像数量有限制。为了获得最佳结果，建议为所有 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'

您可能会遇到这样的情况：远程服务中从 imageUri 的 FrescoDrawee 实际图像已更改，但 {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 的所有图像

如果您不希望清除整个缓存，则可以仅清除与特定 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 - 显示 '失败' 图像