xtf-image-crop

组件说明

xtf-image-crop 是图片裁剪组件，支持拖拽平移、缩放裁剪框、圆形/矩形裁剪、比例预设和 Canvas 导出，适用于头像裁剪、证件照裁剪和图片编辑等场景。

---

基础用法

1. 基础裁剪

通过 src 传入图片地址，通过 width 和 height 设置导出尺寸：

<template>
  <xtf-image-crop :src="imageSrc" :width="800" :height="800" @confirm="onConfirm" />
</template>

<script>
export default {
  data() {
    return {
      imageSrc: '/static/photo.jpg'
    }
  },
  methods: {
    onConfirm(result) {
      console.log('裁剪结果:', result.tempFilePath)
    }
  }
}
</script>

2. 圆形裁剪

通过 cropShape 设置裁剪形状为圆形：

<template>
  <xtf-image-crop
    :src="imageSrc"
    crop-shape="circle"
    :width="400"
    :height="400"
    @confirm="onConfirm"
  />
</template>

<script>
export default {
  data() {
    return {
      imageSrc: '/static/avatar.jpg'
    }
  },
  methods: {
    onConfirm(result) {
      console.log('头像裁剪:', result.tempFilePath)
    }
  }
}
</script>

3. 可调整裁剪框

通过 cropResizable 启用裁剪框大小调整：

<template>
  <xtf-image-crop :src="imageSrc" crop-resizable :lock-crop-aspect="false" @confirm="onConfirm" />
</template>

<script>
export default {
  data() {
    return {
      imageSrc: '/static/photo.jpg'
    }
  },
  methods: {
    onConfirm(result) {
      console.log('裁剪结果:', result.tempFilePath)
    }
  }
}
</script>

4. 比例预设与变换控制

通过组件实例调用 setRatioPreset、rotate、flip 和 resetTransform。setRatioPreset 的参数必须是 ratioPresets 中已定义的 key；rotate 不传参数时顺时针旋转 90 度，flip 传入 'y' 时上下翻转，其他值或不传参数时左右翻转。

<template>
  <view>
    <view style="height: 900rpx">
      <xtf-image-crop
        ref="cropper"
        :src="imageSrc"
        :ratio-presets="ratioPresets"
        default-ratio-key="square"
        @confirm="onConfirm"
      />
    </view>
    <view style="display: flex; flex-wrap: wrap; gap: 16rpx; padding: 24rpx">
      <xtf-button label="1:1" @click="setRatio('square')" />
      <xtf-button label="4:3" @click="setRatio('landscape')" />
      <xtf-button label="旋转" @click="rotate" />
      <xtf-button label="左右翻转" @click="flip" />
      <xtf-button label="重置" @click="resetTransform" />
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      imageSrc: '/static/photo.jpg',
      ratioPresets: [
        { key: 'square', label: '1:1', width: 800, height: 800 },
        { key: 'landscape', label: '4:3', width: 1200, height: 900 }
      ]
    }
  },
  methods: {
    setRatio(key) {
      this.$refs.cropper.setRatioPreset(key)
    },
    rotate() {
      this.$refs.cropper.rotate()
    },
    flip() {
      this.$refs.cropper.flip()
    },
    resetTransform() {
      this.$refs.cropper.resetTransform()
    },
    onConfirm(result) {
      console.log('裁剪结果:', result.tempFilePath)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
src	String	''	图片地址	图片
width	String | Number	1080	导出宽度	导出
height	String | Number	1080	导出高度	导出
machineId / templateId	String | Number	''	业务机器与模板标识，原样随组件状态保留	业务上下文关联
confirmText	String	'确定'	确认按钮文字	按钮
tipText	String	''	提示文字	提示
showTip	Boolean	true	是否显示提示	提示
ratioPresets	Array	[]	比例预设列表	比例
defaultRatioKey	String	''	默认比例键	比例
cropShape	String	'rect'	裁剪形状（rect/circle）	形状
cropResizable	Boolean	false	裁剪框是否可调整	交互
lockCropAspect	Boolean	true	是否锁定裁剪比例	比例
minCropSize	String | Number	160	最小裁剪尺寸	限制
exportFormat	String	'png'	导出格式	导出
exportQuality	String | Number	1	导出质量	导出
maxExportSide	String | Number	4096	最大导出边长	限制
maxExportPixels	String | Number	16000000	最大导出像素	限制
backgroundColor	String	''	导出画布背景色	透明图片转 JPEG 等场景

---

事件

事件名称	触发时机	回调参数	参数说明
confirm	确认裁剪时触发	(result)	包含 tempFilePath 等信息
error	发生错误时触发	(err)	错误信息
ready	图片信息读取并完成初始布局时触发	({ width, height, path, orientation })	实际图片尺寸、读取后的图片路径及图片方向

---

方法

方法名	参数	返回值	说明
setRatioPreset	(key: String)	-	切换到 ratioPresets 中对应 key 的比例预设
rotate	(step?: Number)	-	旋转图片；省略参数时旋转 90 度
flip	(direction?: String)	-	翻转图片；传 'y' 上下翻转，其他值或省略参数时左右翻转
resetTransform	-	-	重置旋转和翻转状态，并按当前比例预设重新布局

---

主题说明

• 裁剪框使用白色边框和网格线
• 遮罩使用半透明黑色
• 确认按钮使用主题色

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