cms-image CMS 图片组件

简介

cms-image 用于根据 CMS 资源标识拉取图片地址，并通过 fs-image 完成渲染。

组件会在 appId 和 apiName 同时有效时自动请求接口：

• 请求地址：/FHH/EM1HWebPage/cms/resource/batchGetFileInfo
• 请求方式：POST
• 请求参数：

{
  appId,
  apiNameList: [apiName]
}

适用于 CMS 配图、运营素材、页面装修图片等需要“按资源标识动态取图”的场景。

使用方法

局部引入，在页面或组件的 index.json 中配置：

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

PWC（自定义组件/插件）使用：仅 usingComponents 注册方式使用 avaComponent:// 协议，其他用法与局部引入一致。

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

基础用法：

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

代码演示

基础用法

行为说明

请求触发时机

• appId 和 apiName 同时有值时自动发起请求
• 任一参数为空时，不发起请求，并清空当前图片地址
• 任一参数变化时，会重新请求最新图片

返回结果处理

• 当接口正常返回且匹配到目标 apiName 的 url 时，组件渲染图片
• 当接口成功但未解析到可用 url 时，会触发 success 事件，但页面展示 slot 占位内容
• 当接口请求失败时，会清空图片地址并触发 error 事件

参数建议

appId

• 含义：当前页面所属应用的 appId
• 来源：通常来自页面上下文、路由参数或全局配置
• 建议：保持与当前业务页面真实应用一致，否则接口可能无法返回资源

apiName

• 含义：CMS 资源的唯一标识
• 示例：cms_image_home_banner
• 建议：直接使用 CMS 后台配置的 API Name，不要传展示名称

API

属性

参数	说明	类型	可选值	默认值
appId	页面所属应用的 appId	String	-	''
apiName	CMS 资源 API Name	String	-	''
mode	图片裁剪/缩放模式，透传给 fs-image	String	同小程序 image	aspectFit
lazyLoad	是否启用懒加载，透传给 fs-image	Boolean	true / false	true
showMenuByLongpress	是否开启长按菜单，透传给 fs-image	Boolean	true / false	false
extStyle	组件根节点自定义样式	String	-	''
extClass	组件根节点自定义 class	String	-	''
imageStyle	图片节点样式，透传给 fs-image 的 extStyle	String	-	''
emptyStyle	未获取到图片地址时，占位容器样式	String	-	''

事件

事件名	参数	说明
success	{ src, raw }	接口请求成功，src 为解析后的图片地址，raw 为原始响应数据
error	{ error }	接口请求失败
load	event	图片加载成功，透传 fs-image 的 load 事件
imgerror	event	图片加载失败，透传 fs-image 的 error 事件

Slot

名称	说明
默认插槽	当未获取到可用图片地址时显示的占位内容

注意事项

• 文档示例中的 appId、apiName 为演示占位值，接入时请替换为真实业务配置
• 如果页面没有传入有效 appId 或 apiName，组件不会发起请求
• 如果需要自定义空态展示，直接在组件标签内部传入 slot 内容即可

打开预览