欢迎使用 NativeScript imageModule

Android 应用程序的 NativeScript 插件。

• 什么是 nativescript-image？
• 如何使用 nativescript-image？
  • 在纯 NativeScript 中
  • 在 NativeScript + Angular 2 中
• 示例
• 特性
  • 基本属性
  • 高级 可选 属性
  • 事件
  • 缓存
• 示例截图
• 贡献
• 获取帮助

什么是 nativescript-image？

nativescript-image 是一个用于在 iOS 和 Android 上高效显示图像的 NativeScript 插件。它在 Android 上使用 imageModule，在 iOS 上使用 SDWebImage。

如何使用 nativescript-image？

在纯 NativeScript 中

从 npm

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

从本地仓库？

1. 克隆仓库并转到您计算机上的根目录。
2. 使用 tsc 将 .ts 源文件转换：tsc -p。
3. 转到您想安装插件的 {N} 应用程序根目录，并输入 tns plugin add <path-to-imageModule-repo-dir>。
4. 当使用 "下采样" 时，您需要将图像及其配置初始化到 initialize 函数中。

import imageModule = require("nativescript-image");

//do this before creating any image view
imageModule.initialize({ isDownsampleEnabled: true });

如下所示，在页面的 XML 定义中使用 imageModule：

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

在 NativeScript + Angular 2 中

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

示例

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

特性

基本属性

• src

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

<nativescript-image:Img src="https://docs.nativescript.cn/angular/img/cli-getting-started/angular/chapter0/NativeScript_logo.png"/>

• placeholderImageUri

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

*注意：当前在抛出 OutOfMemoryError 之前可以设置多少个不同的图像作为 'placeholderImage' 存在有限制。为了获得最佳效果，建议为所有 Img 实例的 placeholderImageUri 使用单个图像。

<nativescript-image:Img placeholderImageUri="~/placeholder.jpg"/>

• failureImageUri

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

<nativescript-image:Img failureImageUri="~/failure.jpg"/>

高级 可选 属性

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

• backgroundUri（仅限 Android）

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

*注意：目前设置不同图片作为'背景'之前，存在限制，否则会抛出OutOfMemoryError异常。为了获得最佳效果，建议为Img实例的所有backgroundUri使用单个图片。

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

• 拉伸

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

'center' - 不进行缩放。

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

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

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

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

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

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

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

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

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

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

<nativescript-image:Img stretch="centerInside"/>

• 渐变持续时间

用于渐变持续时间的数值。此值以毫秒为单位。

<nativescript-image:Img fadeDuration="3000"/>

• 模糊半径

大于零的数值，用作模糊函数的输入。值越大，处理速度越慢。例如，值为10表示图像中的每个像素都会使用相邻像素（距离达10个像素）进行模糊处理。

<nativescript-image:Img blurRadius="25"/>

• blurDownSampling（仅限Android）

大于零的数值，用于在应用模糊函数之前缩放图像。值越大，处理速度越快。例如，值为2表示在应用模糊之前，图像会以两倍的比例缩放。

<nativescript-image:Img blurDownSampling="2"/>

• 宽高比

用作图像宽高比的数值。此属性在处理不同宽高比的图像时非常有用，当您需要固定宽度或高度时。图像的宽高比通过其宽度除以高度来计算。

注意：在某些布局场景中，为了“锚定”img并实现动态大小，需要将Img的verticalAlignment设置为'top'或'bottom'。

<nativescript-image:Img aspectRatio="1.33" verticalAlignment="top"/>

• decodeWidth（下采样）- 确保在插件的初始化函数中启用下采样（isDownsampleEnabled），否则此属性将被忽略。

用作图像模块可绘制下采样宽度的数值。

<nativescript-image:Img decodeWidth="100"/>

• decodeHeight（下采样）- 确保在插件的初始化函数中启用下采样（isDownsampleEnabled），否则此属性将被忽略。

用作图像模块可绘制下采样宽度的数值。

<nativescript-image:Img decodeHeight="100"/>

• progressiveRenderingEnabled

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

<nativescript-image:Img progressiveRenderingEnabled="true"/>

• showProgressBar（仅限Android）

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

<nativescript-image:Img showProgressBar="true"/>

• progressBarColor（仅限Android）

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

<nativescript-image:Img progressBarColor="blue"/>

• roundAsCircle

用于确定图像是否以圆形进行圆形处理的布尔值。默认值为false。如果设置为true，则图像将被更圆地调整为圆形。

<nativescript-image:Img roundAsCircle="true"/>

• roundedCornerRadius

用作图像圆角半径的数字值。

<nativescript-image:Img roundedCornerRadius="50"/>

• roundBottomRight

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

<nativescript-image:Img roundBottomRight="true"/>

• roundBottomLeft

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

<nativescript-image:Img roundBottomLeft="true"/>

• roundTopLeft

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

<nativescript-image:Img roundTopLeft="true"/>

• roundTopRight

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

<nativescript-image:Img roundTopRight="true"/>

• autoPlayAnimations

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

<nativescript-image:Img autoPlayAnimations="true"/>

• tapToRetryEnabled (仅限Android)

用于启用/禁用Img图像下载时“点击重试”操作的布尔值。

<nativescript-image:Img tapToRetryEnabled="true"/>

事件

• finalImageSet - 参数 FinalEventData

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

<nativescript-image:Img finalImageSet="onFinalImageSet"/>

JavaScript

function onFinalImageSet(args) {
    var imageModuleEventData = args;
    var img = imageModuleEventData.object;
}
exports.onFinalImageSet = onFinalImageSet;

TypeScript

import {Img, FinalEventData } from "nativescript-image";

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

• failure - 参数 FailureEventData

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

<nativescript-image:Img failure="onFailure"/>

JavaScript

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

TypeScript

import {Img, FailureEventData } from "nativescript-image";

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

• intermediateImageSet - 参数 IntermediateEventData (仅限Android)

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

<nativescript-image:Img intermediateImageSet="onIntermediateImageSet"/>

JavaScript

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

TypeScript

import {Img, IntermediateEventData } from "nativescript-image";

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

• intermediateImageFailed - 参数 FailureEventData (仅限Android)

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

<nativescript-image:Img intermediateImageFailed="onIntermediateImageFailed"/>

JavaScript

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

TypeScript

import {Img, FailureEventData } from "nativescript-image";

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

• submit - 参数 EventData (仅限Android)

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

<nativescript-image:Img submit="onSubmit"/>

JavaScript

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

TypeScript

import {Img, EventData } from "nativescript-image";

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

• release - 参数 EventData (仅限Android)

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

<nativescript-image:Img release="onRelease"/>

JavaScript

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

TypeScript

import {Img, EventData } from "nativescript-image";

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

事件参数

由 'nativescript-image' 提供的所有事件都为其处理程序提供了所需以正确处理它们的信息。以下是每个事件随带的参数的简要说明

• FinalEventData

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

import {Img, FinalEventData, ImageInfo, AnimatedImage } from "nativescript-image";

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 {Img, FailureEventData, imageModuleError } from "nativescript-image";

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

• IntermediateEventData

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

import {Img, IntermediateEventData, ImageInfo } from "nativescript-image";

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 {Img, EventData } from "nativescript-image";

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

缓存

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

'刷新' 'src'

不常见的情况下，您可能有一个场景，其中远程服务中从 Img 的 src 的实际图像已更改，但 {N} 应用程序已经在其内部缓存中有图像。在这种情况下，您可以轻松地通过调用 updateImageUri() 来“刷新” src。

// 'img' is the instance the 'Img' in the project.
img.updateImageUri();

清除缓存中的所有内容

通过 ImagePipeline 管理nativescript-image中的缓存。为了获取ImagePipeline的引用，请调用 getImagePipeline() 函数

var imageModuleModel = require("nativescript-image");

var imagePipeLine = imageModuleModel.getImagePipeline();

• 清除内存和磁盘缓存

imagePipeLine.clearCaches();

• 清除内存缓存

imagePipeLine.clearMemoryCaches();

• 清除磁盘缓存

imagePipeLine.clearDiskCaches();

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

如果清除整个缓存不是您想要的，您可以只清除与特定URI（src）链接的图像。清除是通过ImagePipeline完成的

var imageModuleModel = require("nativescript-image");

var imagePipeLine = imageModuleModel.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>");

手动关闭本地图像模块库

在极其罕见的情况下，本地的Android图像模块库可能会遇到奇怪的内存泄漏问题。在这种情况下，作为最后的手段，您可能想要“关闭”库，强制释放所有受管理内存。您可以通过调用nativescript-image模块公开的shutDown函数来实现这一点，一个在应用程序生命周期事件中调用它的好方法是应用程序的exit事件

import * as app from "application";
import * as imageModuleModule from "nativescript-image";

if (app.android) {
    app.on(app.exitEvent, (args) => {
        imageModuleModule.shutDown();
    });
}

示例截图

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

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

示例3 - 成功从src显示图像	示例4 - 显示“失败”图像

贡献

我们喜欢Pull Requests！请查看贡献指南。如果您想贡献，但不确定从哪里开始，请寻找标记为help wanted的问题。

获取帮助

请严格使用GitHub问题来报告错误或请求新功能。对于一般问题和支持，请查看Stack Overflow或在我们的NativeScript社区Slack频道中咨询我们的专家。