<image>
用于展示不同类型的图片，包括网络图片、静态资源和本地存储的图片。
使用指南
<image> 是一个空元件，不再支持子节点。
NOTE
要正常显示图片，必须设置非空的 src 属性，并至少提供以下之一：
以下示例展示了 <image> 元件在不同场景下的应用。
展示不同裁剪/缩放模式的图片
支持使用 mode 控制图片裁剪/缩放模式。
图片添加边框、圆角和背景
可通过 CSS 样式设置图片的边框、圆角和背景颜色。
图片添加特殊绘制效果
支持高斯模糊等特殊绘制效果。
自适应原图宽高比例
支持使用 auto-size 自动调整 <image> 尺寸以匹配原图比例。
监听图片加载成功/失败
可通过绑定事件监听图片的加载状态。
属性
src Required
指定要显示的图片 URL。
当前支持的图片格式包括：png、jpg、jpeg、bmp、gif 和 webp。
暂不支持 svg 格式。如需渲染 svg，可参考自定义元件 自行实现。
NOTE
前端内置资源请参照静态资源处理进行配置，否则发布后图片可能会无法正确展示。
mode
// DefaultValue: 'scaleToFill'
mode?: 'scaleToFill' | 'aspectFit' | 'aspectFill';
指定图片裁剪/缩放模式：
-
scaleToFill（默认）：不保持纵横比，拉伸图片以填满 <image>。
-
aspectFit：保持纵横比缩放，使图片的完整内容可见。
-
aspectFill：保持纵横比缩放，使短边填充 <image> 元件，可能导致部分内容裁剪。
placeholder
需要展示的占位图的路径，具体使用方法和限制与 src 相同。
blur-radius
// DefaultValue: '0px'
blur-radius?: string;
图片高斯模糊的模糊半径。
prefetch-width/prefetch-height
// DefaultValue: '0px'
prefetch-width/prefetch-height?: string;
提供图片排版宽高为0时发起请求的能力。
一般在需要提前加载图片的场景使用，设置大小建议和实际排版宽高大小保持一致。
cap-insets
// DefaultValue: '0px 0px 0px 0px'
cap-insets?: string;
9patch 图缩放区域，四个值分别是上、右、下、左，需要是具体数值，不支持百分比和小数。
// 代表从原图[14 * ${cap-insets-scale}，imageWidth - 14 * ${cap-insets-scale}]之间的像素位置开始拉伸图片。
cap-insets="0px 14px 0 14px"
NOTE
使用 cap-insets 并不需要原图是 9patch 图
cap-insets-scale
// DefaultValue: 1
cap-insets-scale?: number;
配合 cap-insets 一同使用，调整最后拉伸时计算的像素位置。
loop-count
// DefaultValue: 0
loop-count?: number;
动图播放次数，默认为循环播放。
image-config Android only
// DefaultValue: 'ARGB_8888'
image-config?: 'RGB_565' | 'ARGB_8888';
指定图像数据格式，有两种取值:
ARGB_8888 每个像素点占用 32 位内存，包含透明通道。
RGB_565 每个像素占用 16 位内存，可以减少内存占用，但透明度会丢失。
NOTE
影响 Android 上实际 bitmap 占用的内存大小。
以一个图像分辨率为 1024*768 的图片为例。
实际占用内存大小为（1024*768*像素位数/8）Byte
auto-size
// DefaultValue: false
auto-size?: boolean;
当该属性为 true 且 <image> 没有宽或高时，在图片下载成功后会根据图片大小重新计算并修改 <image> 大小，保证 <image> 宽高比和图片宽高比一致。
defer-src-invalidation
// DefaultValue: false
defer-src-invalidation ?: boolean;
当该属性为 true 时，<image> 会在一次新的加载成功后才清除已展示的图片资源。
默认行为是在新一次加载发起前清除。
可以解决图片 src 切换之后重新加载导致的闪烁问题，list 等存在视图节点复用的场景不建议打开。
autoplay
// DefaultValue: true
autoplay?: boolean;
是否在动图加载完成之后自动开始播放，默认为自动开始播放。
tint-color
将所有非透明像素的颜色更改为 tint-color 声明的颜色，属性取值为 color。
事件
前端可以在元件上绑定相应事件回调来监听元件的运行时行为，使用方法如下。
bindload
如果图片发起了图片请求，且图片请求成功后，会触发该事件回调，并输出图片宽高。
bindload = (e: ImageLoadEvent) => {};
interface ImageLoadEvent {
detail: {
width: number;
height: number;
};
}
binderror
如果图片发起了图片请求，且图片请求失败后，会触发该事件回调，并输出错误信息和错误码。
binderror = (e: ImageErrorEvent) => {};
interface ImageErrorEvent {
detail: {
errMsg: string; //错误信息
error_code: number;
lynx_categorized_code: number;
};
}
方法
前端可以通过 SelectorQuery API 执行元件的方法。
startAnimate
lynx.createSelectorQuery()
.select('#gifs')
.invoke({
method: 'startAnimate'，
})
.exec();
由前端控制的重启动图播放方法，动图播放进度和 loop-count 均会被重置。
pauseAnimation
lynx.createSelectorQuery()
.select('#gifs')
.invoke({
method: 'pauseAnimation'，
})
.exec();
暂停动图播放，loop-count 不会被重置。
resumeAnimation
lynx.createSelectorQuery()
.select('#gifs')
.invoke({
method: 'resumeAnimation'，
})
.exec();
播放动图，loop-count 不会被重置。
stopAnimation
lynx.createSelectorQuery()
.select('#gifs')
.invoke({
method: 'stopAnimation'，
})
.exec();
停止动图播放，loop-count 会被重置。
进阶功能
请求 URL 重定向映射
功能说明
通过实现请求 URL 重定向机制，开发者 可拦截指定的图片 URL，并将其映射到特定的资源路径。这种能力适用于以下场景：
- 提升静态资源加载速度
- 支持自定义图片协议访问方案
- 保护敏感资源访问路径
实现原理
本功能基于 MediaResourceFetcher 接口实现，核心流程分为两个阶段：
-
资源类型检测 (isLocalResource)
- 判断请求 URL 是否符合自定义协议
- 返回布尔值标识是否进行本地处理
-
路径转换 (shouldRedirectUrl)
- 解析原始 URL
- 转换为有效资源路径
- 返回最终可访问的 URL 地址
以下示例演示如何将类似 http://localhost/xxx 的 URL 映射到应用内置资源路径：
/// 本地资源处理器头文件
#import <LynxMediaResourceFetcher/LynxMediaResourceFetcher.h>
@interface LocalMediaFetcher : NSObject <LynxMediaResourceFetcher>
- (NSString *)shouldRedirectUrl:(LynxResourceRequest *)request;
- (LynxResourceOptionalBool)isLocalResource:(NSURL *)url;
@end
/// 本地资源处理器实现
#import "LocalMediaFetcher.h"
@implementation LocalMediaFetcher
/**
* 资源路径转换方法
* @param request 资源请求对象
* @return 本地文件路径或空字符串
*/
- (NSString *)shouldRedirectUrl:(LynxResourceRequest *)request {
NSURL *url = [NSURL URLWithString:request.url];
NSString *fileType = [url pathExtension];
NSString *fileName = [[url URLByDeletingPathExtension] lastPathComponent];
NSString *subdir = [[[url URLByDeletingLastPathComponent] absoluteString] stringByReplacingOccurrencesOfString:@"http://localhost" withString:@""];
NSString *path = [[NSBundle mainBundle] pathForResource:fileName ofType:fileType inDirectory:subdir];
return path ? [NSString stringWithFormat:@"file://%@", path] : @"";
}
/**
* 本地资源判断方法
* @param url 请求的原始URL
* @return LynxResourceOptionalBoolTrue 需要重定向的请求
*/
- (LynxResourceOptionalBool)isLocalResource:(NSURL *)url {
return [url.absoluteString hasPrefix:@"http://localhost"] ?
LynxResourceOptionalBoolTrue :
LynxResourceOptionalBoolFalse;
}
@end
import com.lynx.tasm.resourceprovider.LynxResourceRequest
import com.lynx.tasm.resourceprovider.media.LynxMediaResourceFetcher
import com.lynx.tasm.resourceprovider.media.OptionalBool
/**
* 自定义媒体资源处理器
*
* @property protocol 需要拦截的协议头 "http://localhost"
* @property scheme 目标资源协议头 "asset://"
*/
class LocalMediaFetcher : LynxMediaResourceFetcher() {
/**
* 判断是否本地资源
* @param url 请求的原始URL
* @return OptionalBool.TRUE 需要重定向的请求
*/
override fun isLocalResource(url: String?): OptionalBool {
return if (url?.startsWith("http://localhost") == true) {
OptionalBool.TRUE
} else {
OptionalBool.FALSE
}
}
/**
* 执行URL重定向
* @param request 资源请求对象
* @return 转换后的有效资源路径
*/
override fun shouldRedirectUrl(request: LynxResourceRequest?): String {
return request?.url?.replace(
oldValue = "http://localhost",
newValue = "asset://",
ignoreCase = true
) ?: ""
}
}
import {
LynxMediaResourceFetcher,
LynxResourceRequest,
LynxOptionalBool,
} from '@lynx/lynx';
// 本地资源处理器实现
export class ExampleMediaResourceFetcher extends LynxMediaResourceFetcher {
// 资源路径转换方法
// @param request 资源请求对象
// @return 本地文件路径或空字符串
shouldRedirectUrl(request: LynxResourceRequest): string {
return request.url?.replace(
'http://localhost',
'file://'
) ?? '';
}
// 判断是否本地资源
// @param url 请求的原始URL
// @return LynxOptionalBool.TRUE 需要重定向的请求
isLocalResource(url: string): LynxOptionalBool {
if (url.startsWith('http://localhost')) {
return LynxOptionalBool.TRUE
}
return LynxOptionalBool.FALSE
}
}
更多详细信息请参考 MediaResourceFetcher 的 API 文档。
兼容性
LCD tables only load in the browser
