纯前端实现可访问的图片裁剪器：拖拽缩放、键盘微调与导出画质

图片裁剪器看起来只是「画个框、拖一拖」，但真正落地时会遇到三类问题：坐标算不准（缩放和缩放比例叠加后偏移）、键盘用户完全没法用、以及导出的图和屏幕上看到的不是一回事。把这三类问题分开处理，裁剪器就稳了。

一、先定坐标系

至少要区分四个坐标系：原图像素坐标、显示区（舞台）坐标、裁剪框相对舞台的坐标、以及设备像素比带来的物理像素。最省事的做法是让裁剪框永远用「原图像素」表达：内部只存 {x, y, w, h} 四个原图像素值，渲染时再乘以一个统一的缩放因子映射到舞台。这样无论舞台怎么缩放、窗口怎么变化，裁剪结果都不会漂。

const state = {
  crop: { x: 0, y: 0, w: 0, h: 0 },   // 原图像素
  stageScale: 1,                       // 显示缩放因子
};
const toStage = (rect) => ({
  x: rect.x * state.stageScale,
  y: rect.y * state.stageScale,
  w: rect.w * state.stageScale,
  h: rect.h * state.stageScale,
});

舞台缩放由「容器可用尺寸 ÷ 原图尺寸」算出，并取 min 保证整图可见。不要用 CSS transform 缩放图片后再去反算坐标——精度差且容易出现半像素误差。

二、拖拽与手柄

裁剪框至少有 9 个交互点：4 条边、4 个角、以及内部（平移）。用 Pointer Events 统一处理，并在 pointerdown 时 setPointerCapture，指针移出裁剪框也能继续拖。

拖动时只改 state.crop，然后重算裁剪框的 style，不要在 pointermove 里做重排以外的重活。若图片很大，拖动期间给裁剪框加 will-change: transform，并把「实时预览」降级为低频更新，松手后再出一张高质量预览。

约束要考虑：裁剪框是否允许超出图片边界（一般不允许）、最小尺寸（比如 32×32）、以及固定的宽高比（头像常用 1:1）。有比例锁时，改宽要带动高，且必须按比例反算，不能让用户拖出变形框。

三、键盘与无障碍替代

只用鼠标能拖的裁剪器，对键盘用户等于不可用。必须提供等价操作：把裁剪框本身做成可聚焦元素（tabindex="0"），方向键微调位置（按住 Shift 加速），用独立的按键或一组可聚焦手柄调整尺寸，Home/End 回到左/上边界。更彻底的做法是提供一组数字输入框（x / y / 宽 / 高），键盘用户直接输数值——这同时也是给高级用户的效率入口。

<div class="crop-box" tabindex="0" role="application"
     aria-label="裁剪区域，方向键移动，Shift 加方向键调整大小"></div>
<label>宽 <input type="number" min="32" value="320" /></label>

手柄不要只做成视觉上的小方块，它们要么在 Tab 序列里可达，要么由上层的键盘模型覆盖，二选一，别两头都不占。

四、裁剪结果与画质

导出的正确做法是：在原图分辨率下按 state.crop 把像素画到 canvas 上，而不是截取屏幕上被缩放过的画面。这样 4K 原图被缩到 600px 宽展示时，导出依然是原图画质。

const canvas = document.createElement('canvas');
canvas.width = state.crop.w;
canvas.height = state.crop.h;
const ctx = canvas.getContext('2d');
ctx.imageSmoothingQuality = 'high';
ctx.drawImage(image, state.crop.x, state.crop.y, state.crop.w, state.crop.h,
              0, 0, state.crop.w, state.crop.h);
const blob = await new Promise((resolve) => canvas.toBlob(resolve, 'image/jpeg', 0.92));

格式与质量要按用途分：头像用 WebP 或 JPEG 0.9 左右；需要透明背景就必须用 PNG 或 WebP。还要处理 EXIF 方向——手机竖拍的照片常带 Orientation 标记，不处理会导出成横的。稳妥做法是先用 createImageBitmap 并指定 imageOrientation: 'from-image'。

五、大图与内存

几千万像素的图直接解码进内存就可能崩。先用 createImageBitmap 带 resizeWidth 做一次降采样用于「显示」，把原图 File 保留到提交时再按需全量解码。上传前不要忘了校验体积与最大边长，并对超大图给出明确提示，而不是等浏览器卡死。

多次裁剪（比如用户反复调整）要记得释放旧 canvas 与 URL.createObjectURL 产生的对象 URL，否则内存会持续增长。

六、与上传流程的配合

裁剪得到 Blob 后，用 FormData 上传，文件名保留原扩展名或按目标格式改名，并在请求头或字段里带上实际内容类型。若后端要求固定尺寸，前端裁剪后仍应允许后端再次校验，避免绕过。上传中要显示进度并允许取消；失败时保留裁剪状态，让用户能重试而不必重新选图。

七、测试清单

覆盖：窗口缩放后裁剪框不漂移、按住 Shift 的加速微调、比例锁下拖角不变形、最小尺寸与边界约束、触屏拖拽不与页面滚动打架、超小屏下舞台缩放正确、导出尺寸等于裁剪框原图像素、EXIF 竖拍图导出方向正确、大图不崩、以及重复裁剪不泄漏内存。用键盘完整完成一次裁剪，是发现「手柄不可达」最有效的方式。

八、小结

裁剪器的核心是把裁剪区域统一用原图像素表达，渲染时再映射；把拖拽与键盘两套操作都做实；导出时回到原图分辨率并正确处理方向与格式。做到这三点，头像裁切这种小事就不会再反复出坑。