cropper-core

v1.0.0

Published

4 months ago

Cropper core library

0High
0Medium
0Low

guochiscoding

cropper image canvas core

cropper-core

基于 Canvas 2D 的图片处理工具库，提供 cropperImage1 ~ cropperImage11 共 11 个常用的裁剪/缩放/翻转/旋转/圆形裁剪/高质量缩放能力。

特性

内置 11 种图片处理：裁剪、等比缩放、指定宽高、翻转、旋转、圆形裁剪、高质量缩放等
统一输出 base64（data:image/png;base64,...），便于直接预览或二次处理
所有方法基于浏览器原生 Image + CanvasRenderingContext2D

安装

cropper-core 依赖浏览器环境（window/document/Image/canvas）。如果你只使用 cropperImage1 ~ cropperImage11，不需要依赖特定的 DOM 节点结构（无需固定的元素 id），但仍需要在工程里安装 jquery（当前版本在入口文件中有引用）。

npm i cropper-core jquery

快速使用

本包使用 ESM 导出（package.json 已设置 type: "module"）：

import ImageCropper from 'cropper-core';

const cropper = new ImageCropper();

const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');

const active = {
  width: 300,
  height: 200,
  imgWidth: 300,
  imgHeight: 200,
};

const src = 'https://example.com/a.png';
const outBase64 = await cropper.cropperImage9(
  active,
  0,
  0,
  active.imgWidth,
  active.imgHeight,
  9,
  30,
  '',
  ctx,
  canvas,
  src
);

通用参数说明

11 个方法的参数形态保持一致（便于串联执行）。你可以按下面的说明传参：

`active_el`

图片处理的“目标尺寸/容器尺寸”描述对象（普通 JS 对象即可）。不同方法会用到不同字段，建议至少提供：

type ActiveElement = {
  width: number;    // 目标容器宽（部分方法用）
  height: number;   // 目标容器高（部分方法用）
  imgWidth: number; // 目标输出宽（部分方法用）
  imgHeight: number;// 目标输出高（部分方法用）
};

`offsetX / offsetY / cutWidth / cutHeight`

用于描述裁剪区域/偏移的工作变量。多数方法内部会重新计算它们，你通常可以这样传：

offsetX = 0;
offsetY = 0;
cutWidth = active_el.imgWidth;
cutHeight = active_el.imgHeight;

`type`

与方法编号一致的数字（1~11）。部分方法内部不依赖它，但建议按编号传入，便于统一调度。

`value1 / value2`

每个方法自己的配置参数（不同方法含义不同，下方逐个说明）。

`ctx / canvas / src`

ctx: CanvasRenderingContext2D
canvas: HTMLCanvasElement（作为渲染/导出载体）
src: 图片来源（URL 或 base64）。内部会创建 Image() 并加载该 src，加载完成后再处理。

11 个方法（签名 + 传参含义）

下面签名与 index.js 保持一致（参数顺序不变）。

1) `cropperImage1` 裁剪（对齐 / 自定义区域）

async cropperImage1(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

active_el.width/height: 用于计算居中/对齐裁剪区域
value1:
- 1: 居中裁剪
- 2: 顶部居中
- 3: 底部居中
- 4: 左侧居中
- 5: 右侧居中
- 6: 自定义裁剪区域（需要 value2）
value2: 当 value1=6 时使用，格式为 "cutWidth,cutHeight,offsetX,offsetY"
返回: Promise<string | undefined>（未满足条件时可能返回 undefined）

2) `cropperImage2` 等比缩放（按宽 / 按高 / 智能）

async cropperImage2(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src,
  boxItem,
  newCanvas,
  isLast
)

active_el.imgWidth/imgHeight: 用于计算目标输出尺寸
value1:
- 1: 按宽度缩放（输出宽 = active_el.imgWidth）
- 2: 按高度缩放（输出高 = active_el.imgHeight）
- 3: 智能（当 active_el.width >= active_el.height 走按宽，否则按高）
value2: 未使用（保留位）
boxItem/newCanvas/isLast: 未使用（保留位）
返回: Promise<string | undefined>

3) `cropperImage3` 适配到目标宽高并按位置对齐

async cropperImage3(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

active_el.imgWidth/imgHeight: 目标输出宽高
value1: 对齐方式（在目标画布内放置图像）
- 1: 左上
- 2: 上中
- 3: 右上
- 4: 左中
- 5: 居中
- 6: 右中
- 7: 左下
- 8: 下中
- 9: 右下
value2: 未使用（保留位）
返回: Promise<string | undefined>

4) `cropperImage4` 指定输出宽度（保持比例）

async cropperImage4(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

value1: 输出宽度（number）
value2: 未使用（保留位）
返回: Promise<string | undefined>

5) `cropperImage5` 指定输出高度（保持比例）

async cropperImage5(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

value1: 输出高度（number）
value2: 未使用（保留位）
返回: Promise<string | undefined>

6) `cropperImage6` 按规则裁剪高度（从底部往上截取）

async cropperImage6(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

active_el.width/height: 参与计算裁剪高度
value1/value2: 未使用（保留位）
返回: Promise<string | undefined>

7) `cropperImage7` 按规则裁剪高度（带额外偏移策略）

async cropperImage7(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

active_el.width/height/imgHeight: 参与计算裁剪高度与偏移
value1/value2: 未使用（保留位）
返回: Promise<string | undefined>

8) `cropperImage8` 镜像翻转

async cropperImage8(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

active_el.width/height: 翻转绘制时的目标尺寸
value1:
- 1: 水平翻转
- 2: 垂直翻转
value2: 未使用（保留位）
返回: Promise<string | undefined>

9) `cropperImage9` 旋转

async cropperImage9(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

value1: 旋转角度（度数，number）。内部会对 360 取模。
value2: 未使用（保留位）
返回: Promise<string | false | undefined>（未传 value1 时返回 false）

10) `cropperImage10` 圆形裁剪

async cropperImage10(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src
)

value1:
- 为空：默认 r = img.naturalWidth（以图片宽作为直径相关计算）
- 非空：字符串形式的数组，例如 "[r,x,y]" 或 "r,x,y"
  - r: 圆形直径（最终画布宽高 = r）
  - x: 圆心参考点 x（可省略，默认 img.width）
  - y: 圆心参考点 y（可省略，默认 img.height）
value2: 未使用（保留位）
返回: Promise<string | undefined>

11) `cropperImage11` 高质量等比缩放

async cropperImage11(
  active_el,
  offsetX,
  offsetY,
  cutWidth,
  cutHeight,
  type,
  value1,
  value2,
  ctx,
  canvas,
  src,
  boxItem,
  newCanvas,
  isLast
)

active_el.imgWidth/imgHeight: 用于计算目标输出尺寸
value1:
- 1: 按宽度缩放
- 3: 智能（当 active_el.width >= active_el.height 按宽，否则按高）
- 其他：按高度缩放
newCanvas: 当走“按高度缩放”分支时，作为输出 canvas（必须是 HTMLCanvasElement）
value2/boxItem/isLast: 未使用（保留位）
返回: Promise<string>

注意事项

跨域图片：内部通过 img.crossOrigin = "anonymous" 加载图片；若图片源未开启 CORS，可能导致 toDataURL 抛安全异常。
Node 环境：默认面向浏览器。若要在 Node 使用，需要自行提供 DOM 与 Canvas 实现（例如 jsdom + node-canvas）。

License

ISC

使用示例（组合多个操作）

下面示例演示把多种处理按顺序串起来（输入可以是 URL 或 base64，输出为 base64）。

import ImageCropper from 'cropper-core';

const cropper = new ImageCropper();

async function runPipeline(inputSrc, processes, active) {
  const canvas = document.createElement('canvas');
  const ctx = canvas.getContext('2d');
  const newCanvas = document.createElement('canvas');

  let src = inputSrc;
  let offsetX = 0;
  let offsetY = 0;
  let cutWidth = active.imgWidth;
  let cutHeight = active.imgHeight;

  for (const p of processes) {
    const fn = cropper[`cropperImage${p.type}`];
    if (typeof fn !== 'function') {
      throw new Error(`Unsupported type: ${p.type}`);
    }

    const out = await fn.call(
      cropper,
      active,
      offsetX,
      offsetY,
      cutWidth,
      cutHeight,
      p.type,
      p.value1 ?? '',
      p.value2 ?? '',
      ctx,
      canvas,
      src,
      undefined,
      newCanvas,
      false
    );

    if (out) src = out;
  }

  return src;
}

const active = {
  width: 300,
  height: 200,
  imgWidth: 300,
  imgHeight: 200,
};

const processes = [
  { type: 1, value1: 1, value2: '' },
  { type: 9, value1: 30, value2: '' },
  { type: 11, value1: 1, value2: '' },
];

const inputSrc = 'https://example.com/a.png';
const outBase64 = await runPipeline(inputSrc, processes, active);

const preview = document.createElement('img');
preview.src = outBase64;
document.body.appendChild(preview);

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

cropper-core

特性

安装

快速使用

通用参数说明

active_el

offsetX / offsetY / cutWidth / cutHeight

type

value1 / value2

ctx / canvas / src

11 个方法（签名 + 传参含义）

1) cropperImage1 裁剪（对齐 / 自定义区域）

2) cropperImage2 等比缩放（按宽 / 按高 / 智能）

3) cropperImage3 适配到目标宽高并按位置对齐

4) cropperImage4 指定输出宽度（保持比例）

5) cropperImage5 指定输出高度（保持比例）

6) cropperImage6 按规则裁剪高度（从底部往上截取）

7) cropperImage7 按规则裁剪高度（带额外偏移策略）

8) cropperImage8 镜像翻转

9) cropperImage9 旋转

10) cropperImage10 圆形裁剪

11) cropperImage11 高质量等比缩放

注意事项

License

使用示例（组合多个操作）

`active_el`

`offsetX / offsetY / cutWidth / cutHeight`

`type`

`value1 / value2`

`ctx / canvas / src`

1) `cropperImage1` 裁剪（对齐 / 自定义区域）

2) `cropperImage2` 等比缩放（按宽 / 按高 / 智能）

3) `cropperImage3` 适配到目标宽高并按位置对齐

4) `cropperImage4` 指定输出宽度（保持比例）

5) `cropperImage5` 指定输出高度（保持比例）

6) `cropperImage6` 按规则裁剪高度（从底部往上截取）

7) `cropperImage7` 按规则裁剪高度（带额外偏移策略）

8) `cropperImage8` 镜像翻转

9) `cropperImage9` 旋转

10) `cropperImage10` 圆形裁剪

11) `cropperImage11` 高质量等比缩放