cms-image CMS Image Component

Introduction

cms-image fetches the image URL based on a CMS resource identifier and renders it via fs-image.

The component automatically requests the API when both appId and apiName are valid:

• Request URL: /FHH/EM1HWebPage/cms/resource/batchGetFileInfo
• Request method: POST
• Request parameters:

{
  appId,
  apiNameList: [apiName]
}

Suitable for scenarios that need to "dynamically fetch images by resource identifier", such as CMS illustrations, operational assets, and page decoration images.

Usage

When importing locally, configure it in the page or component's index.json:

{
  "usingComponents": {
    "cms-image": "/avaui-sub/cms-image/index"
  },
  "componentPlaceholder": {
    "cms-image": "view"
  }
}

PWC (custom component/plugin) usage: only the usingComponents registration follows the format below (the avaComponent:// protocol); other usage is identical to local registration.

{
  "usingComponents": {
    "cms-image": "avaComponent://avaui-sub/cms-image/index"
  }
}

Basic usage:

<cms-image
  appId="{{appId}}"
  apiName="cms_image_home_banner"
  mode="aspectFill"
  imageStyle="width: 320rpx; height: 180rpx; border-radius: 16rpx;"
>
  <view>No image</view>
</cms-image>

Code Demos

Basic Usage

Behavior Notes

Request Trigger Timing

• A request is automatically initiated when both appId and apiName have values
• If either parameter is empty, no request is made and the current image URL is cleared
• When either parameter changes, the latest image is re-requested

Response Handling

• When the API returns normally and a url matching the target apiName is found, the component renders the image
• When the API succeeds but no usable url is resolved, the success event is triggered but the slot placeholder content is displayed
• When the API request fails, the image URL is cleared and the error event is triggered

Parameter Guidelines

appId

• Meaning: The appId of the application the current page belongs to
• Source: Usually from page context, route parameters, or global configuration
• Recommendation: Keep it consistent with the real application of the current business page, otherwise the API may not return resources

apiName

• Meaning: The unique identifier of the CMS resource
• Example: cms_image_home_banner
• Recommendation: Use the API Name configured in the CMS backend directly; do not pass a display name

API

Attributes

Parameter	Description	Type	Optional Values	Default
appId	The appId of the page's application	String	-	''
apiName	CMS resource API Name	String	-	''
mode	Image crop/scale mode, forwarded to fs-image	String	same as mini-program image	aspectFit
lazyLoad	Whether to enable lazy loading, forwarded to fs-image	Boolean	true / false	true
showMenuByLongpress	Whether to enable the long-press menu, forwarded to fs-image	Boolean	true / false	false
extStyle	Custom styles for the component root node	String	-	''
extClass	Custom class for the component root node	String	-	''
imageStyle	Image node styles, forwarded to fs-image's extStyle	String	-	''
emptyStyle	Placeholder container styles when no image URL is available	String	-	''

Events

Event Name	Parameters	Description
success	{ src, raw }	API request succeeded; src is the resolved image URL, raw is the raw response data
error	{ error }	API request failed
load	event	Image loaded successfully; forwards the load event of fs-image
imgerror	event	Image failed to load; forwards the error event of fs-image

Slot

Name	Description
Default slot	Placeholder content displayed when no usable image URL is available

Notes

• The appId and apiName in the documentation examples are placeholder values; replace them with real business configuration when integrating
• If the page does not pass a valid appId or apiName, the component will not make a request
• If you need a custom empty-state display, just pass slot content inside the component tag

打开预览