MiImageCarousel

The MiImageCarousel component is a Flutter widget for displaying a scrollable carousel of images, configurable via JSON.

Overview

The MiImageCarousel component, extending MiStatelessWidget, is designed to present a collection of images in a horizontally scrolling carousel. It supports displaying images from network URLs and offers customization options such as previewing the next image, auto-play, border radius, and aspect ratio. This component is ideal for showcasing image galleries or featured content within your application, driven by JSON configurations.

Component Name: imageCarousel

JSON key: "component": "imageCarousel".

Parameters

Parameter Key	JSON Value Type	Flutter Type	Description	Default Value	Nullable	Requires Build
imageUrls	List<String>	List<String>	A list of image URLs to be displayed in the carousel. Each URL should be a valid network image path. The URLs can include keys enclosed by "$ and " to access the state (e.g., ${key1}, ${items}). Refer to Key.	None	Yes	No
previewNextImage	bool	bool	If true, the carousel will display a preview of the next image on the side, using CarouselSlider. If false, it uses a simpler PageView based carousel without next image preview.	false	Yes	No
autoPlay	bool	bool	If true, the carousel will automatically transition to the next image after a set interval (3 seconds). Only effective when previewNextImage is true.	false	Yes	No
borderRadius	num (Number)	double	The border radius to be applied to the corners of each image in the carousel. Converted from JSON num to Flutter double using DoubleHelper.get.	None	Yes	No
aspectRatio	num (Number)	double	The aspect ratio (width/height) of the image carousel when previewNextImage is false. Converted from JSON num to Flutter double using DoubleHelper.get.	16/9	Yes	No
color	String	Color	The color of the component. (Inherited from MiStatelessWidget)	Theme default color	Yes	No
width	num (Number)	double	The width of the component. (Inherited from MiStatelessWidget)	None (Intrinsic width)	Yes	No
height	num (Number)	double	The height of the component. (Inherited from MiStatelessWidget)	None (Intrinsic height)	Yes	No
padding	List<num>	EdgeInsets	Padding to be applied around the carousel. Expects a list of numbers representing padding values (e.g., [left, top, right, bottom] or [horizontal, vertical] or [all]). (Inherited from MiStatelessWidget)	None	Yes	No
margin	List<num>	EdgeInsets	Margin to be applied around the carousel. Expects a list of numbers representing margin values (e.g., [left, top, right, bottom] or [horizontal, vertical] or [all]). (Inherited from MiStatelessWidget)	None	Yes	No
alignment	String	AlignmentGeometry	How the carousel should be aligned within its allocated space. Accepts alignment keywords like 'topLeft', 'center', 'bottomRight', etc. Refer to Flutter's Alignment documentation. (Inherited from MiStatelessWidget)	Defaults to topLeft	Yes	No

Note:

• Inherited Parameters: color, alignment, width, height, padding, and margin are inherited parameters from MiStatelessWidget and provide basic styling and layout control for the MiImageCarousel.
• Image URL Resolution: The imageUrls parameter expects a list of network image URLs. Keys can be included in the URLs using the format ${key} to access dynamic state values. Refer to Key for state access details.
• Carousel Types: The previewNextImage parameter determines the type of carousel. When true, it utilizes CarouselSlider for a visually richer carousel with next image preview and auto-play capabilities. When false, it uses a PageView based carousel which is simpler and does not have preview or auto-play.
• Helper Classes: DoubleHelper.get is used to convert JSON num values to Flutter double values for borderRadius and aspectRatio parameters, ensuring type safety and proper value handling.

Example JSON Configurations

Example 1: Basic Image Carousel with Preview and Auto-play

{
  "component": "imageCarousel",
  "imageUrls": [
    "image1.jpg",
    "image2.jpg",
    "image3.jpg"
  ],
  "previewNextImage": true,
  "autoPlay": true,
  "borderRadius": 8
}

Explanation of Example 1:

• component: "imageCarousel" - Identifies this configuration as a MiImageCarousel component.
• imageUrls - Provides a list of image URLs: "image1.jpg", "image2.jpg", "image3.jpg". These URLs will be used as the source for images in the carousel. The URLs are relative and will be resolved using ImageUrlUtil.resolve by prepending the baseUrl from the APIRepository.
• previewNextImage: true - Enables the preview next image feature, using CarouselSlider for the carousel display.
• autoPlay: true - Enables auto-play for the carousel, automatically transitioning images every 3 seconds.
• borderRadius: 8 - Sets the border radius of each image in the carousel to 8.0. This numeric JSON value is converted to a Flutter double using DoubleHelper.get. See the "borderRadius" parameter description.

Example 2: Simple Image Carousel without Preview and Custom Aspect Ratio

{
  "component": "imageCarousel",
  "imageUrls": [
    "imageA.png",
    "imageB.png"
  ],
  "previewNextImage": false,
  "aspectRatio": 1.5,
  "padding": [10]
}

Explanation of Example 2:

• component: "imageCarousel" - Identifies this configuration as a MiImageCarousel component.
• imageUrls - Provides a list of image asset paths: "imageA.png", "imageB.png". These assets will be loaded and displayed in the carousel. The URLs are relative and will be resolved using ImageUrlUtil.resolve by prepending the baseUrl from the APIRepository.
• previewNextImage: false - Disables the preview next image feature, resulting in a simpler PageView based carousel.
• aspectRatio: 1.5 - Sets the aspect ratio of the carousel to 1.5. This numeric JSON value is converted to a Flutter double using DoubleHelper.get. See the "aspectRatio" parameter description in the table and DoubleHelper.dart.
• padding: [10] - Applies a padding of 10.0 to all sides of the carousel. This list of numbers is converted to Flutter EdgeInsets using EdgeInsetsHelper.get. See the "padding" parameter description in the table and MiStatelessWidget.dart for details on inherited padding and EdgeInsetsHelper.get.