必须绕过yii2-imagine默认裁剪逻辑，接入SmartCrop.js实现内容感知裁剪，因其本身无自动识别能力，仅支持手动坐标裁剪；前端集成后计算坐标，后端用yii2-imagine执行物理裁剪。
要在Yii2项目中实现图片内容感知的智能裁剪，必须绕过yii2-imagine默认的固定比例裁剪逻辑，接入SmartCrop.js的前端分析能力或服务端增强方案，否则人脸、主体物极易被切掉。
为什么不能直接用yii2-imagine做智能裁剪
yii2-imagine本身不包含内容感知能力，Image::crop()和Image::thumbnail()仅支持坐标指定裁剪或缩放填充，【所有裁剪行为都依赖开发者手动传入x/y/width/height】，无法自动识别画面焦点。强行用它模拟“智能”效果，需额外集成OpenCV或调用第三方AI接口，成本远超直接引入SmartCrop.js。
SmartCrop.js是纯前端JS库，轻量、免后端依赖、实时反馈，与Yii2的视图层天然契合——只需在用户上传预览或编辑页注入脚本，即可完成坐标计算。
前端集成SmartCrop.js到Yii2视图
方法一：CDN直连（推荐新手）
在视图文件（如views/site/upload.php）的<head>内插入：
<script src="https://cdn.jsdelivr.net/npm/smartcrop@2.0.5/smartcrop.js"></script>
方法二：本地部署（适合内网/离线环境）
下载smartcrop.js源码 → 放入web/js/smartcrop.js → 在视图中引用：<script src="/js/smartcrop.js"></script>
注意：不要放在AppAsset里统一打包，SmartCrop.js需在<img>元素渲染后加载，否则getElementById会取不到DOM节点。
在Yii2表单中触发智能裁剪计算
第一步：给图片容器添加唯一ID并确保已加载
<img id="smartcrop-source" src="= $model->previewUrl ?>" onload="runSmartCrop()" />
第二步：编写裁剪逻辑函数，绑定到onload事件
function runSmartCrop() { const img = document.getElementById('smartcrop-source'); smartcrop.crop(img, { width: 300, height: 200 }).then(result => { const crop = result.topCrop; // 将x/y/width/height写入隐藏字段，供Yii2后端接收 document.getElementById('crop_x').value = crop.x; document.getElementById('crop_y').value = crop.y; document.getElementById('crop_w').value = crop.width; document.getElementById('crop_h').value = crop.height; }); }
第三步：在ActiveForm中声明对应隐藏输入域
= $form->field($model, 'crop_x')->hiddenInput(['id' => 'crop_x'])->label(false) ?>= $form->field($model, 'crop_y')->hiddenInput(['id' => 'crop_y'])->label(false) ?>= $form->field($model, 'crop_w')->hiddenInput(['id' => 'crop_w'])->label(false) ?>= $form->field($model, 'crop_h')->hiddenInput(['id' => 'crop_h'])->label(false) ?>
这一步做完，用户看到的是自动框选出的红框区域，表单提交时四个坐标值会作为普通POST参数传入Yii2控制器。
后端用yii2-imagine执行最终裁剪
① 在Controller中接收坐标参数
$x = (int) Yii::$app->request->post('crop_x', 0); $y = (int) Yii::$app->request->post('crop_y', 0); $w = (int) Yii::$app->request->post('crop_w', 0); $h = (int) Yii::$app->request->post('crop_h', 0);
② 校验坐标有效性（关键防错）
【必须检查 $x+$w 不超过原图宽度，$y+$h 不超过原图高度，否则yii2-imagine会抛出Imagine\Exception\RuntimeException】
③ 调用yii2-imagine执行物理裁剪
use yii\imagine\Image; Image::crop($originalPath, $w, $h, [$x, $y])->save($outputPath);
