Package detail

canvas-crop-image

ato-z10MIT1.1.8

🌈🌈🌈 A simple canvas crop tool

canvas, image, edit

readme

canvas-crop-image 示例集

本仓库包含了丰富的 Canvas 裁剪与图片处理功能示例。你可以参考下述用法快速集成和扩展 canvas-crop-image 的能力。

安装

npm install canvas-crop-image
# 或
pnpm add canvas-crop-image

基本用法

所有功能均通过如下方式导入：

import {
  CanvasCrop,
  Sprite,
  Bloodline,
  DragBehavior,
  ScaleRotationBehavior,
  BorderBehavior,
  LoadingEffect,
  BlurEffect,
  Transition,
  calculateDisplayInfo,
} from 'canvas-crop-image'

常用示例

1. 基础图片显示

展示图片的 full 和 cover 两种模式。

const crop = new CanvasCrop(400, 400)
const sprite = new Sprite('cover', './img/01.png')
crop.addComponent(sprite)
crop.appendTo(document.body)

2. 多图叠加

在同一画布上展示多张图片。

const crop = new CanvasCrop(500, 500)
const sprite1 = new Sprite('cover', './img/01.png', {
  x: 25,
  y: 50,
  width: 200,
  height: 114.5,
})
const sprite2 = new Sprite('cover', './img/02.png', {
  x: 250,
  y: 150,
  width: 200,
  height: 112,
})
crop.addComponent(sprite1)
crop.addComponent(sprite2)
crop.appendTo(document.body)

3. 拖拽图片

为图片添加拖拽行为。

const crop = new CanvasCrop(500, 400)
const sprite = new Sprite('cover', './img/01.png', {
  x: 25,
  y: 50,
  width: 200,
  height: 114.5,
})
sprite.addBehavior(new DragBehavior())
crop.addComponent(sprite)
crop.appendTo(document.body)

4. 旋转与镜像

支持图片旋转和镜像显示。

const crop = new CanvasCrop(400, 400)
const sprite = new Sprite('cover', './img/02.png', {
  angle: 45,
  mirrorX: -1,
  mirrorY: 1,
})
crop.addComponent(sprite)
crop.appendTo(document.body)

5. 缩放与旋转

支持双指缩放与旋转。

const crop = new CanvasCrop(350, 400)
const sprite = new Sprite('cover', './img/01.png')
sprite.addBehavior(new ScaleRotationBehavior(true))
crop.addComponent(sprite)
crop.appendTo(document.body)

6. 缩放旋转拖拽

图片可同时缩放、旋转和拖拽。

const crop = new CanvasCrop(350, 400)
const sprite = new Sprite('cover', './img/01.png')
sprite.addBehavior(new ScaleRotationBehavior(true))
sprite.addBehavior(new DragBehavior())
crop.addComponent(sprite)
crop.appendTo(document.body)

7. 自动缩放适应

通过按钮动态旋转图片并自动适配画布。

const crop = new CanvasCrop(640, 320)
let angle = 0
const sprite = new Sprite('cover', './img/02.png', { angle })
crop.addComponent(sprite)
crop.appendTo(document.body)

document.querySelector('#btn').onclick = () => {
  angle += 90
  const newView = calculateDisplayInfo(
    { width: 640, height: 320 },
    { width: sprite.rect.originWdith, height: sprite.rect.originHeight },
    angle,
  )
  sprite.rect.setView(newView)
}

8. 边框视图与限制

为图片添加可拖拽的边框限制。

const crop = new CanvasCrop(1800, 1800)
const sprite = new Sprite('cover', './img/02.png', {
  width: 800,
  height: 448,
  x: 250,
  y: 150,
})
sprite.addBehavior(new DragBehavior())
sprite.addBehavior(new BorderBehavior(2000, true, '#00ff00'))
crop.addComponent(sprite)
crop.appendTo(document.body)

9. 加载等待效果

为组件添加加载等待的动态提示。

const crop = new CanvasCrop(500, 400)
const sprite = new Sprite('cover', './img/01.png')
sprite.addEffect(new LoadingEffect('加载中...', 'orange'))
crop.addComponent(sprite)
crop.appendTo(document.body)

10. 毛玻璃模糊效果

为组件添加毛玻璃模糊动画效果。

const crop = new CanvasCrop(640, 320)
const sprite = new Sprite('cover', './img/02.png')
crop.addComponent(sprite)
crop.appendTo(document.body)

document.querySelector('#btn').onclick = () => {
  sprite.addEffect(new BlurEffect(10, 2000))
}

11. 淡入淡出过渡

图片淡入淡出过渡效果。

const crop = new CanvasCrop(400, 400)
const sprite = new Sprite('cover', './img/01.png')
sprite.addEffect(
  new Transition(
    { x: 0, y: 0, width: 100, height: 100, angle: 0, mirrorX: 1, mirrorY: 1 },
    {
      x: 50,
      y: 50,
      width: 200,
      height: 200,
      angle: 90,
      mirrorX: -1,
      mirrorY: 1,
    },
    1200,
  ),
)
crop.addComponent(sprite)
crop.appendTo(document.body)

12. 监听过渡动画结束

监听过渡动画结束事件。

const transition = new Transition(sprite.rect, target, 600)
sprite.addEffect(transition)
transition.runState.promise.then(() => {
  // 动画结束回调
})

13. 自动变换过渡

自动变换图片角度并过渡。

const target = calculateDisplayInfo(
  { width: 640, height: 320 },
  { width: sprite.rect.originWdith, height: sprite.rect.originHeight },
  angle,
)
sprite.addEffect(new Transition(sprite.rect, target, 600))

14. 出血线辅助组件

添加出血线辅助组件。

const crop = new CanvasCrop(1200, 1840)
const bloodline = new Bloodline(20, 8, '#ff0000')
crop.addComponent(bloodline)
crop.appendTo(document.body)

主要类与参数说明

CanvasCrop

/**
 * @param {number} width - 画布宽度
 * @param {number} height - 画布高度
 * @param {boolean} [willReadFrequently=false] - 是否优化离屏canvas读取性能（如需频繁读取像素建议设为 true）
 */
const crop = new CanvasCrop(400, 400, true)

Sprite

Sprite 是一个主要的视图组件，开发者可以根据自己需求去继承 Sprite 并实现更多的功能。

/**
 * @param {'full'|'cover'} mode - 图片显示模式
 * @param {string} source - 图片地址
 * @param {Object} [prop] - 图片属性
 * @param {number} [prop.x]
 * @param {number} [prop.y]
 * @param {number} [prop.width]
 * @param {number} [prop.height]
 * @param {number} [prop.angle]
 * @param {1|-1} [prop.mirrorX]
 * @param {1|-1} [prop.mirrorY]
 */
const sprite = new Sprite('cover', './img/01.png', {
  x: 10,
  y: 20,
  width: 200,
  height: 100,
  angle: 45,
  mirrorX: -1,
  mirrorY: 1,
})

继承 Sprite 实现自定义拖拽视图组件

// 只接受图片路径，自动 cover 模式和自适应尺寸
class DraggableSprite extends Sprite {
  constructor(source) {
    super('cover', source)
    this.addBehavior(new DragBehavior())
  }
}

const dragSprite = new DraggableSprite('./img/01.png')
crop.addComponent(dragSprite)

Bloodline

Bloodline 是一个出血线绘制组件，用于显示纸制类产品裁切时可能会产生的误差。

/**
 * @param {number} borderWidth - 出血线宽度
 * @param {number} [rounded=0] - 圆角半径
 * @param {string} [color='red'] - 线颜色
 */
const bloodline = new Bloodline(20, 8, '#ff0000')

Behavior（行为）

行为（如拖拽、缩放、旋转等，主要响应用户交互）

DragBehavior

/** 无参数，直接 new 即可 */
sprite.addBehavior(new DragBehavior())

ScaleRotationBehavior

为组件添加缩放和旋转的交互行为，支持双指缩放和旋转。

/**
 * @param {boolean} [rotate=false] - 是否允许旋转
 */
sprite.addBehavior(new ScaleRotationBehavior(true))

BorderBehavior

为组件边缘插入虚线边框，用于辅助操作。

/**
 * @param {number} [duration=1500] - 边框显示时长(ms)
 * @param {boolean} [rotate=false] - 是否允许旋转
 * @param {string} [color='#1989fa'] - 边框颜色
 */
sprite.addBehavior(new BorderBehavior(2000, true, '#00ff00'))

Effect（动态效果）

动态效果（如模糊、加载、过渡等，主要用于视觉动画）

LoadingEffect

为组件添加加载等待的动态提示。

/**
 * @param {string} [message='Loading...'] - 加载提示文字
 * @param {string} [color='grey'] - 文字颜色
 */
sprite.addEffect(new LoadingEffect('加载中...', 'orange'))

BlurEffect

为组件添加毛玻璃模糊动画效果。

/**
 * @param {number} [value=15] - 模糊像素
 * @param {number} [duration=1000] - 动画时长(ms)
 */
sprite.addEffect(new BlurEffect(10, 2000))

Transition

Transition 是一个变换组件，接受两个矩阵（变化前和变化后）的关键帧，并生成补间动画。

/**
 * @param {Object} start - 形如 { width, height, x, y, angle, mirrorX, mirrorY }
 * @param {Object} end - 形如 { width, height, x, y, angle, mirrorX, mirrorY }
 * @param {number} [duration=1000] - 动画时长(ms)
 */
sprite.addEffect(
  new Transition(
    { x: 0, y: 0, width: 100, height: 100, angle: 0, mirrorX: 1, mirrorY: 1 },
    {
      x: 50,
      y: 50,
      width: 200,
      height: 200,
      angle: 90,
      mirrorX: -1,
      mirrorY: 1,
    },
    1200,
  ),
)

calculateDisplayInfo

用于计算一个居中的组件经过旋转方向后，应该放大的系数和偏移量，返回适合当前角度下的 width、height、x、y 等信息，常用于图片自适应旋转时的居中显示。

/**
 * @param {Object} parentRect - { width, height }
 * @param {Object} origin - { width, height }
 * @param {number} angle - 旋转角度
 */
const view = calculateDisplayInfo(
  { width: 400, height: 300 },
  { width: 200, height: 100 },
  90,
)