#<image>

Used to display different types of images, including web images, static resources, and locally stored images.

#Usage Guide

<image> is an empty element and no longer supports child nodes.

The following examples show how the <image> element is used in different scenarios.

#Displaying images with different cropping/scaling modes

Supports controlling the image cropping/scaling mode using mode.

imagesrc/App.tsx

Preview

#Adding borders, rounded corners, and backgrounds to the image

You can set the image's borders, rounded corners, and background colors using CSS styles.

imagesrc/App.tsx

Preview

#Adding special drawing effects to the image

Supports special drawing effects like Gaussian blur.

imagesrc/App.tsx

Preview

#Adapting to the original image aspect ratio

Use auto-size to automatically adjust the <image> size to match the original image aspect ratio.

imagesrc/App.tsx

Preview

#Listening to image load success/failure

You can bind events to listen for the image load state.

#Properties

#srcRequired

src: string;

Specifies the image URL to display.

The supported image formats are: png, jpg, jpeg, bmp, gif, and webp.

svg format is currently not supported. If you need to render svg images, you can refer to Custom Element to implement it yourself.

#mode

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

Specifies the image cropping/scaling mode:

• scaleToFill (default): The image is stretched to fill the <image> element without maintaining its aspect ratio.
• aspectFit: Scales the image to maintain its aspect ratio, ensuring the entire image is visible.
• aspectFill: Scales the image to maintain its aspect ratio, causing the shorter side to fill the <image> element, which may crop part of the image.

#placeholder

placeholder?: string;

Specifies the path to the placeholder image. The usage and limitations are the same as for the src attribute.

#blur-radius

// DefaultValue: '0px'
blur-radius?: string;

Specifies the Gaussian blur radius for the image.

#prefetch-width/prefetch-height

// DefaultValue: '0px'
prefetch-width/prefetch-height?: string;

Allows initiating a request when the image has a width/height of 0. This is typically used when preloading images. It's recommended to set the sizes to match the actual layout width/height.

#cap-insets

// DefaultValue: '0px 0px 0px 0px'
cap-insets?: string;

Specifies the 9patch image scaling area with four values representing the top, right, bottom, and left edges. Values must be specific numbers and do not support percentages or decimals.

// Specifies the pixel range starting from [14 * ${cap-insets-scale}, imageWidth - 14 * ${cap-insets-scale}] for stretching the image.
cap-insets="0px 14px 0 14px"

#cap-insets-scale

// DefaultValue: 1
cap-insets-scale?: number;

Works with cap-insets to adjust the pixel positions when stretching the image.

#loop-count

// DefaultValue: 0
loop-count?: number;

Specifies the number of times to play an animated image. The default is to loop indefinitely.

#image-config

Android only

// DefaultValue: 'ARGB_8888'
image-config?: 'RGB_565' | 'ARGB_8888';

Specifies the image data format. There are two options:

• ARGB_8888: Each pixel uses 32 bits of memory, including an alpha channel for transparency.
• RGB_565: Each pixel uses 16 bits of memory, which reduces memory usage but loses transparency.

#auto-size

// DefaultValue: false
auto-size?: boolean;

When set to true and the <image> element has no width or height, the size of the <image> will be automatically adjusted to match the image's original dimensions after the image is successfully loaded, ensuring that the aspect ratio is maintained.

#defer-src-invalidation

// DefaultValue: false
defer-src-invalidation?: boolean;

When set to true, the <image> will only clear the previously displayed image resource after a new image has successfully loaded.

The default behavior is to clear the image resource before starting a new load.

This can resolve flickering issues when the image src is switched and reloaded. It is not recommended to enable this in scenarios where there is node reuse in views like lists.

#autoplay

// DefaultValue: true
autoplay?: boolean;

Specifies whether the animated image should start playing automatically once it is loaded. The default is to autoplay.

#tint-color

tint-color?: string;

Changes the color of all non-transparent pixels to the tint-color specified. The value is a color.

#Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

#bindload

Triggered when the image request succeeds, outputting the image's width and height.

bindload = (e: ImageLoadEvent) => {};

interface ImageLoadEvent {
  detail: {
    width: number;
    height: number;
  };
}

#binderror

Triggered when the image request fails, outputting the error message and code.

binderror = (e: ImageErrorEvent) => {};

interface ImageErrorEvent {
  detail: {
    errMsg: string; // Error message
    error_code: number;
    lynx_categorized_code: number;
  };
}

#Methods

Frontend can invoke component methods via the SelectorQuery API.

#startAnimate

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'startAnimate'，
    })
    .exec();

Restarts the animation. The animation progress and loop-count are both reset.

#pauseAnimation

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'pauseAnimation'，
    })
    .exec();

Pauses the animation, without resetting the loop-count.

#resumeAnimation

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'resumeAnimation'，
    })
    .exec();

Resumes the animation, without resetting the loop-count.

#stopAnimation

lynx.createSelectorQuery()
     .select('#gifs')
     .invoke({
      method: 'stopAnimation'，
    })
    .exec();

Stops the animation, resetting the loop-count.

#Advanced Features

#Request URL Redirection Mapping

#Feature Description

By implementing a URL redirection mechanism, developers can intercept specific image URLs and map them to specific resource paths. This ability is useful for the following scenarios:

• Improving static resource loading speed
• Supporting custom image protocol access schemes
• Protecting sensitive resource access paths

#Implementation Principle

This feature is implemented based on the MediaResourceFetcher interface, with the core process divided into two stages:

1. Resource Type Detection (isLocalResource)

   • Determines if the request URL matches the custom protocol
   • Returns a boolean indicating whether to handle it locally

2. Path Conversion (shouldRedirectUrl)

   • Parses the original URL
   • Converts it into a valid resource path
   • Returns the final accessible URL address

The following example shows how to map a URL like http://localhost/xxx to an app's built-in resource path:

/// Local resource handler header
#import <LynxMediaResourceFetcher/LynxMediaResourceFetcher.h>

@interface LocalMediaFetcher : NSObject <LynxMediaResourceFetcher>

- (NSString *)shouldRedirectUrl:(LynxResourceRequest *)request;

- (LynxResourceOptionalBool)isLocalResource:(NSURL *)url;

@end

/// Local resource handler implementation
#import "LocalMediaFetcher.h"

@implementation LocalMediaFetcher

/**
 * Resource path conversion method
 * @param request Resource request object
 * @return Local file path or empty string
 */
- (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] : @"";
}

/**
 * Local resource detection method
 * @param url The original request URL
 * @return LynxResourceOptionalBoolTrue indicates the request needs redirection
 */
- (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

/**
 * Custom media resource handler
 *
 * @property protocol The protocol to intercept "http://localhost"
 * @property scheme The target resource protocol "asset://"
 */
class LocalMediaFetcher : LynxMediaResourceFetcher() {

    /**
     * Determines if the resource is local
     * @param url The original request URL
     * @return OptionalBool.TRUE indicates the request needs redirection
     */
    override fun isLocalResource(url: String?): OptionalBool {
        return if (url?.startsWith("http://localhost") == true) {
            OptionalBool.TRUE
        } else {
            OptionalBool.FALSE
        }
    }

    /**
     * Performs URL redirection
     * @param request The resource request object
     * @return The converted valid resource path
     */
    override fun shouldRedirectUrl(request: LynxResourceRequest?): String {
        return request?.url?.replace(
            oldValue = "http://localhost",
            newValue = "asset://",
            ignoreCase = true
        ) ?: ""
    }
}

Read the API reference of MediaResourceFetcher for more details.

#Compatibility

LCD tables only load in the browser