<image>#

用于展示不同类型的图片，包括网络图片、静态资源和本地存储的图片。

使用指南#

<image> 是一个空元件，不再支持子节点。

以下示例展示了 <image> 元件在不同场景下的应用。

展示不同裁剪/缩放模式的图片#

支持使用 mode 控制图片裁剪/缩放模式。

imagesrc/App.tsx

预览

图片添加边框、圆角和背景#

可通过 CSS 样式设置图片的边框、圆角和背景颜色。

imagesrc/App.tsx

预览

图片添加特殊绘制效果#

支持高斯模糊等特殊绘制效果。

imagesrc/App.tsx

预览

自适应原图宽高比例#

支持使用 auto-size 自动调整 <image> 尺寸以匹配原图比例。

imagesrc/App.tsx

预览

监听图片加载成功/失败#

可通过绑定事件监听图片的加载状态。

属性#

src Required#

src: string;

指定要显示的图片 URL。

mode#

// DefaultValue: 'scaleToFill'
mode?: 'scaleToFill' | 'aspectFit' | 'aspectFill';

指定图片裁剪/缩放模式：

• scaleToFill（默认）：不保持纵横比，拉伸图片以填满 <image>。

• aspectFit：保持纵横比缩放，使图片的完整内容可见。

• aspectFill：保持纵横比缩放，使短边填充 <image> 元件，可能导致部分内容裁剪。

placeholder#

placeholder?: string;

需要展示的占位图的路径，具体使用方法和限制与 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"

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 位内存，可以减少内存占用，但透明度会丢失。

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?: string;

将所有非透明像素的颜色更改为 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 接口实现，核心流程分为两个阶段：

1. 资源类型检测 (isLocalResource)

   • 判断请求 URL 是否符合自定义协议
   • 返回布尔值标识是否进行本地处理

2. 路径转换 (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
        ) ?: ""
    }
}

完整 API 参考：MediaResourceFetcher 文档

兼容性#