市场place
作者 NativeScript.org
@nativescript-community/ui-image
由 NativeScript 社区提供 | v4.5.3
高级高效的图像显示插件，使用 Fresco（Android）和 SDWebImage（iOS）来实现缓存、占位符、图像效果等。
npm i --save @nativescript-community/ui-image

@nativescript-community/ui-image

Downloads per month NPM Version

高级高效的图像显示插件，使用 Fresco（Android）和 SDWebImage（iOS）来实现缓存、占位符、图像效果等。
iOS 示例 Android 示例

目录

安装

从项目的根目录运行以下命令

ns plugin add @nativescript-community/ui-image

设置

import imageModule = require("@nativescript-community/ui-image");

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

API

事件

finalImageSet - 参数 FinalEventData

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

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

JavaScript

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

TypeScript

import {Img, FinalEventData } from "@nativescript-community/ui-image";

export function onFinalImageSet(args: FinalEventData) {
    var img = args.object as Img;
}
  • failure - 参数 FailureEventData

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

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

JavaScript

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

TypeScript

import {Img, FailureEventData } from "@nativescript-community/ui-image";

export function onFailure(args: FailureEventData) {
    var img = args.object as Img;
}
  • intermediateImageSet - 参数 IntermediateEventData（仅限 Android）

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

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

JavaScript

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

TypeScript

import {Img, IntermediateEventData } from "@nativescript-community/ui-image";

export function onIntermediateImageSet(args: IntermediateEventData) {
    var img = args.object as Img;
}
  • intermediateImageFailed - 参数 FailureEventData（仅限 Android）

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

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

JavaScript

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

TypeScript

import {Img, FailureEventData } from "@nativescript-community/ui-image";

export function intermediateImageFailed(args: FailureEventData) {
    var img = args.object as Img;
}
  • submit - 参数 EventData（仅限 Android）

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

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

JavaScript

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

TypeScript

import {Img, EventData } from "@nativescript-community/ui-image";

export function onSubmit(args: EventData) {
    var img = args.object as Img;
}
  • release - 参数 EventData（仅限 Android）

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

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

JavaScript

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

TypeScript

import {Img, EventData } from "@nativescript-community/ui-image";

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

事件参数

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

import {Img, FinalEventData, ImageInfo, AnimatedImage } from "@nativescript-community/ui-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-community/ui-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-community/ui-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-community/ui-image";

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

属性

  • src

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

<@nativescript-community/ui-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-community/ui-image:Img placeholderImageUri="~/placeholder.jpg"/>
  • failureImageUri

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

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

高级 可选 属性

Img实例可以设置一些可选属性以实现高级功能。

  • backgroundUri（仅限Android）

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

*注意：目前在对图像设置'background'之前，如果超过一定数量，将会抛出OutOfMemoryError。为了获得最佳效果，建议为Img实例的所有backgroundUri使用单个图像。

<@nativescript-community/ui-image:Img backgroundUri="~/image.jpg"/>
  • stretch

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

'center' - 不进行缩放。

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

'centerInside' - 缩放子项，使其完全适应父项。

'fitCenter' - 缩放子项，使其完全适应父项。

'aspectFit' - 缩放子项，使其完全适应父项。

'fitStart' - 缩放子项，使其完全适应父项。

'fitEnd' - 缩放子项，使其完全适应父项。

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

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

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

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

<@nativescript-community/ui-image:Img stretch="centerInside"/>
  • fadeDuration

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

<@nativescript-community/ui-image:Img fadeDuration="3000"/>
  • blurRadius

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

<@nativescript-community/ui-image:Img blurRadius="25"/>
  • blurDownSampling（仅限Android）

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

<@nativescript-community/ui-image:Img blurDownSampling="2"/>
  • aspectRatio

用于图像宽高比的数字值。此属性在处理不同宽高比的图像时很有用，当需要固定宽度或高度时。图像的比率是通过将其宽度除以高度来计算的。

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

<@nativescript-community/ui-image:Img aspectRatio="1.33" verticalAlignment="top"/>
  • decodeWidth（下采样）- 确保在插件初始化函数中启用下采样（isDownsampleEnabled），否则此属性将被忽略。

用于图像模块可绘制内容的下采样宽度的数字值。

<@nativescript-community/ui-image:Img decodeWidth="100"/>
  • decodeHeight（下采样）- 确保在插件初始化函数中启用下采样（isDownsampleEnabled），否则此属性将被忽略。

用于图像模块可绘制内容的下采样宽度的数字值。

<@nativescript-community/ui-image:Img decodeHeight="100"/>
  • headers

定义与图像下载请求一起发送的自定义请求头部的对象。

<@nativescript-community/ui-image:Img headers="{Authorization: 'bearer abcdefghijk'}"/>
  • progressiveRenderingEnabled

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

<@nativescript-community/ui-image:Img progressiveRenderingEnabled="true"/>
  • showProgressBar

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

<@nativescript-community/ui-image:Img showProgressBar="true"/>
  • progressBarColor

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

<@nativescript-community/ui-image:Img progressBarColor="blue"/>
  • roundAsCircle

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

<@nativescript-community/ui-image:Img roundAsCircle="true"/>
  • roundTopLeftRadius

左上角圆角半径

<@nativescript-community/ui-image:Img roundTopLeftRadius="50"/>
  • roundTopRightRadius

右上角圆角半径

<@nativescript-community/ui-image:Img roundTopRightRadius="50"/>
  • roundBottomLeftRadius

左下角圆角半径

<@nativescript-community/ui-image:Img roundBottomLeftRadius="50"/>
  • roundBottomRightRadius

右下角圆角半径

<@nativescript-community/ui-image:Img roundBottomRightRadius="50"/>
  • autoPlayAnimations

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

<@nativescript-community/ui-image:Img autoPlayAnimations="true"/>
  • tapToRetryEnabled（仅限Android）

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

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

缓存

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

'刷新' 'src'

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

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

从缓存中清除所有内容

通过 ImagePipeline 来管理 @nativescript-community/ui-image 中的缓存。要获取 ImagePipeline 的引用，只需调用 getImagePipeline() 函数。

var imageModuleModel = require("@nativescript-community/ui-image");

var imagePipeLine = imageModuleModel.getImagePipeline();
  • 清除内存和磁盘缓存
imagePipeLine.clearCaches();
  • 清除内存缓存
imagePipeLine.clearMemoryCaches();
  • 清除磁盘缓存
imagePipeLine.clearDiskCaches();

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

如果您不希望清除整个缓存，可以仅清除与特定 URI（src）相关的图像。驱逐操作同样通过 ImagePipeline 完成。

var imageModuleModel = require("@nativescript-community/ui-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>");

手动关闭本机 imageModule 库

在非常非常罕见的情况下，本机 Android imageModule 库可能会遇到奇怪的内存泄漏问题。在这种情况下，作为最后的手段，您可能希望“关闭”库，强制释放所有管理的内存。您可以通过调用 @nativescript-community/ui-image 模块公开的 shutDown 函数来完成此操作。一个良好的应用程序生命周期事件来调用它可能是应用程序的 exit 事件。

import * as app from "application";
import * as imageModuleModule from "@nativescript-community/ui-image";

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

风味

使用核心

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

其他版本在 demo-snippets 下的演示应用程序中有所展示。

示例

此存储库包括 Angular、Vue.js 演示。要运行这些演示，请在您的 shell 中执行以下操作

$ git clone https://github.com/@nativescript-community/ui-image
$ cd ui-image
$ npm i
$ npm run setup
$ npm run build # && npm run build.angular
$ cd demo-ng # or demo-vue or demo-svelte
$ ns run ios|android

示例和开发

仓库设置

此存储库使用子模块。如果您没有使用 --recursive 克隆，则需要调用

git submodule update --init

用于安装和链接依赖项的包管理器必须是 pnpm 或 yarn。 npm 将不起作用。

要开发和测试：如果您使用 yarn，则运行 yarn；如果您使用 pnpm，则运行 pnpm i。

交互式菜单

要启动交互式菜单，请运行 npm start（或 yarn start 或 pnpm start）。这将列出所有常用脚本。

构建

npm run build.all

警告：yarn build.all 似乎并不总是工作（在 node_modules/.bin 中找不到二进制文件），这就是为什么文档明确使用 npm run 的原因。

示例

npm run demo.[ng|react|svelte|vue].[ios|android]

npm run demo.svelte.ios # Example

演示设置在某种程度上是特殊的，因为如果您想修改/添加演示，您不会直接在 demo-[ng|react|svelte|vue] 中工作。相反，您将在 demo-snippets/[ng|react|svelte|vue] 中工作。您可以从每个版本的 install.ts 开始，了解如何注册新的演示。

贡献

更新仓库

您可以很容易地更新存储库文件。

首先更新子模块

npm run update

然后提交更改，然后更新通用文件

npm run sync

然后您可以运行 yarn|pnpm，如果有任何更改，请提交更改文件。

更新 README

npm run readme

更新文档

npm run doc

发布

发布完全由 lerna 处理（您可以通过添加 -- --bump major 来强制主要版本发布）只需运行即可

npm run publish

修改子模块

此存储库使用 https:// 用于子模块，这意味着您无法直接推送到子模块。一个简单的解决方案是修改 ~/.gitconfig 并添加

[url "ssh://[email protected]/"]
	pushInsteadOf = https://github.com/

问题

如果您有任何问题/问题/评论，请随时在NativeScript 社区 Discord创建问题或开始对话。