xtf-image

组件说明

xtf-image 是增强图片组件，在原生 image 基础上增加了加载状态、错误重试、占位图、遮罩文字、标签、徽标、水印和图片预览等功能，适用于商品图片、头像和内容展示等场景。

---

基础用法

1. 基础用法

通过 src 设置图片地址：

<template>
  <xtf-image src="/static/banner.jpg" width="100%" height="360" radius="20" />
</template>

2. 圆形与圆角

通过 circle 设置圆形，通过 radius 设置圆角：

<template>
  <view style="display: flex; gap: 24rpx">
    <xtf-image src="/static/avatar.jpg" width="120" height="120" circle />
    <xtf-image src="/static/product.jpg" width="200" height="200" radius="20" />
  </view>
</template>

3. 带标签与遮罩

通过 tagText 显示标签，通过 caption 和 desc 显示遮罩文字：

<template>
  <xtf-image
    src="/static/product.jpg"
    width="100%"
    height="400"
    tag-text="新品"
    tag-theme="danger"
    caption="限时特惠"
    desc="剩余3天"
  />
</template>

4. 占位图与懒加载

通过 placeholder 设置占位图，通过 lazy 启用懒加载：

<template>
  <xtf-image
    src="/static/large-image.jpg"
    width="100%"
    height="500"
    placeholder="/static/placeholder.png"
    lazy
  />
</template>

---

全部属性

属性	类型	默认值	作用描述	适用范围
src	String	''	图片地址	图片
width	String | Number	'100%'	宽度	尺寸
height	String | Number	220	高度	尺寸
ratio	String | Number	''	宽高比	尺寸
mode	String	'aspectFill'	裁剪模式	模式
radius	String | Number	28	圆角	样式
radiusTopLeft / radiusTopRight / radiusBottomRight / radiusBottomLeft	String | Number	''	分别覆盖四个角的圆角值	非对称圆角
circle	Boolean	false	是否圆形	形状
shape	String	'rounded'	形状	形状
variant	String	'default'	变体	样式
bordered	Boolean	false	是否显示边框	边框
grayscale	Boolean	false	是否灰度	样式
lazy	Boolean	false	是否懒加载	加载
fadeShow	Boolean	true	是否淡入	动画
showLoading	Boolean	true	是否显示加载	加载
showError	Boolean	true	是否显示错误	错误
errorText	String	'加载失败，点击重试'	加载失败时显示的提示文案	错误态文案
placeholder / fallback	String	''	加载占位图、失败备用图片	加载
lazyLoad / webp / showMenuByLongpress	Boolean	undefined / false / false	原生图片能力开关	图片
previewList / previewCurrent	Array / String | Number	[] / 0	预览集合和当前图片	预览
preview	Boolean	false	是否可预览	预览
caption	String	''	遮罩标题	遮罩
desc	String	''	遮罩描述	遮罩
tagText	String	''	标签文字	标签
tagTheme	String	'primary'	标签主题	标签
tagVariant	String	'solid'	标签视觉变体	标签样式
badgeValue	String | Number	''	徽标值	徽标
badgeText	String	''	徽标文字	文本徽标
badgeDot	Boolean	false	是否显示点状徽标	红点提醒
badgeTheme / badgeVariant	String	'danger' / 'bubble'	徽标主题与视觉变体	徽标样式
watermark	String	''	水印文字	水印
overlayAlign	String	'left'	遮罩文字对齐方式	遮罩排版
retryable	Boolean	true	错误态是否允许点击重试	错误恢复
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
load	图片加载完成时触发	(event)	加载事件
error	图片加载失败时触发	(event)	错误事件
retry	重试加载时触发	-	-
click	点击时触发	(event)	点击事件对象
longpress	长按时触发	(event)	长按事件对象
preview	预览图片前触发	(payload)	{ current, urls, src }

事件与插槽使用示例

下例同时监听加载、失败、重试、点击和预览事件，并以 error、overlay、top 插槽覆盖对应区域：

<template>
  <xtf-image
    src="/static/product.jpg"
    :preview-list="previewList"
    preview
    caption="夏日新品"
    @load="onLoad"
    @error="onError"
    @retry="onRetry"
    @click="onClick"
    @longpress="onLongpress"
    @preview="onPreview"
  >
    <template #error><xtf-text text="图片加载失败，点击重试" color="secondary" /></template>
    <template #overlay><xtf-text text="夏日新品" color="inverse" /></template>
    <template #top><xtf-tag label="新品" theme="danger" size="sm" /></template>
  </xtf-image>
</template>

<script>
export default {
  data() {
    return { previewList: ['/static/product.jpg', '/static/product-2.jpg'] }
  },
  methods: {
    onLoad(event) {
      console.log('图片加载完成：', event)
    },
    onError(event) {
      console.log('图片加载失败：', event)
    },
    onRetry() {
      console.log('重新加载图片')
    },
    onClick(event) {
      console.log('点击图片：', event)
    },
    onLongpress(event) {
      console.log('长按图片：', event)
    },
    onPreview(payload) {
      console.log('预览图片：', payload.current)
    }
  }
}
</script>

---

插槽

插槽名称	说明
error	自定义错误状态
overlay	自定义遮罩内容
top	自定义顶部标签/徽标

---

主题说明

• 加载状态使用骨架屏动画
• 错误状态使用 xtf-icon 和 xtf-text 组件
• 标签使用 xtf-tag 组件
• 徽标使用 xtf-badge 组件

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。