CropperImage

CropperImage 接口提供了用于操作 <cropper-image> 元素的布局和表示的属性和方法。

示例

基本

TIP

此元素的默认宽度和高度为 0。

有图片源

围绕中心缩放

将 zoomAroundCenter 属性设置为 true，即可从图像中心缩放；否则以指针位置作为缩放原点。

设置初始尺寸

Details

vue

<template>
  <div class="cropper-container">
    <form>
      <fieldset>
        <legend>initialFit:</legend>
        <input
          id="initialFitCover"
          v-model="initialFit"
          type="radio"
          name="initialFit"
          value="cover"
        >
        <label for="initialFitCover">cover</label>
        <input
          id="initialFitFill"
          v-model="initialFit"
          type="radio"
          name="initialFit"
          value="fill"
        >
        <label for="initialFitFill">fill</label>
        <input
          id="initialFitContain"
          v-model="initialFit"
          type="radio"
          name="initialFit"
          value="contain"
        >
        <label for="initialFitContain">contain</label>
        <input
          id="initialFitScaleDown"
          v-model="initialFit"
          type="radio"
          name="initialFit"
          value="scale-down"
        >
        <label for="initialFitScaleDown">scale-down</label>
        <input
          id="initialFitNone"
          v-model="initialFit"
          type="radio"
          name="initialFit"
          value="none"
        >
        <label for="initialFitNone">none</label>
      </fieldset>
    </form>
    <cropper-canvas
      ref="cropperCanvas"
      :key="initialFit"
      background
    >
      <cropper-image
        ref="cropperImage"
        :src="src"
        alt="Picture"
        :initial-fit="initialFit"
        rotatable
        scalable
        skewable
        translatable
      />
      <cropper-handle
        action="move"
        plain
      />
    </cropper-canvas>
  </div>
</template>

<script lang="ts">
const { BASE_URL } = import.meta.env;

export default {
  name: 'CropperImageInitialFitExample',
  data() {
    return {
      src: `${BASE_URL}picture.jpg`,
      initialFit: 'contain',
    };
  },
};
</script>

<style lang="scss" scoped>
.cropper-container {
  border: 1px solid var(--vp-c-divider);
  border-radius: 0.375rem;
  margin-bottom: 1rem;
  margin-top: 1rem;
  padding: 1.25rem 1.5rem;

  fieldset {
    border: 1px solid var(--vp-c-divider);
    border-radius: 0.375rem;
    margin-bottom: 1rem;
    padding: 0.25rem 0.75rem 0.75rem 0.75rem;

    > input {
      margin: 0 0.25rem 0 0;
      transform: translateY(-0.5px);
      vertical-align: middle;
    }

    > label {
      margin-right: 0.5rem;
    }
  }

  cropper-canvas {
    height: 320px;
  }
}
</style>

限制最大尺寸和（或）最小尺寸

Details

vue

<template>
  <div class="cropper-container">
    <form>
      <fieldset>
        <legend>Max Fit:</legend>
        <input
          id="maxFit"
          v-model="maxFit"
          type="radio"
          name="maxFit"
          value=""
        >
        <label for="maxFit">default</label>
        <input
          id="maxFitCover"
          v-model="maxFit"
          type="radio"
          name="maxFit"
          value="cover"
        >
        <label for="maxFitCover">cover</label>
        <input
          id="maxFitFill"
          v-model="maxFit"
          type="radio"
          name="maxFit"
          value="fill"
        >
        <label for="maxFitFill">fill</label>
        <input
          id="maxFitContain"
          v-model="maxFit"
          type="radio"
          name="maxFit"
          value="contain"
        >
        <label for="maxFitContain">contain</label>
        <input
          id="maxFitScaleDown"
          v-model="maxFit"
          type="radio"
          name="maxFit"
          value="scale-down"
        >
        <label for="maxFitScaleDown">scale-down</label>
        <input
          id="maxFitNone"
          v-model="maxFit"
          type="radio"
          name="maxFit"
          value="none"
        >
        <label for="maxFitNone">none</label>
      </fieldset>
      <fieldset>
        <legend>Min Fit:</legend>
        <input
          id="minFit"
          v-model="minFit"
          type="radio"
          name="minFit"
          value=""
        >
        <label for="minFit">default</label>
        <input
          id="minFitCover"
          v-model="minFit"
          type="radio"
          name="minFit"
          value="cover"
        >
        <label for="minFitCover">cover</label>
        <input
          id="minFitFill"
          v-model="minFit"
          type="radio"
          name="minFit"
          value="fill"
        >
        <label for="minFitFill">fill</label>
        <input
          id="minFitContain"
          v-model="minFit"
          type="radio"
          name="minFit"
          value="contain"
        >
        <label for="minFitContain">contain</label>
        <input
          id="minFitScaleDown"
          v-model="minFit"
          type="radio"
          name="minFit"
          value="scale-down"
        >
        <label for="minFitScaleDown">scale-down</label>
        <input
          id="minFitNone"
          v-model="minFit"
          type="radio"
          name="minFit"
          value="none"
        >
        <label for="minFitNone">none</label>
      </fieldset>
    </form>
    <cropper-canvas
      ref="cropperCanvas"
      :key="minFit"
      background
    >
      <cropper-image
        ref="cropperImage"
        :src="src"
        alt="Picture"
        :max-fit="maxFit"
        :min-fit="minFit"
        rotatable
        scalable
        skewable
        translatable
      />
      <cropper-handle
        action="move"
        plain
      />
    </cropper-canvas>
  </div>
</template>

<script lang="ts">
const { BASE_URL } = import.meta.env;

export default {
  name: 'CropperImageMaxFitAndMinFitExample',
  data() {
    return {
      src: `${BASE_URL}picture.jpg`,
      maxFit: 'cover',
      minFit: 'contain',
    };
  },
};
</script>

<style lang="scss" scoped>
.cropper-container {
  border: 1px solid var(--vp-c-divider);
  border-radius: 0.375rem;
  margin-bottom: 1rem;
  margin-top: 1rem;
  padding: 1.25rem 1.5rem;

  fieldset {
    border: 1px solid var(--vp-c-divider);
    border-radius: 0.375rem;
    margin-bottom: 1rem;
    padding: 0.25rem 0.75rem 0.75rem 0.75rem;

    > input {
      margin: 0 0.25rem 0 0;
      transform: translateY(-0.5px);
      vertical-align: middle;
    }

    > label {
      margin-right: 0.5rem;
    }
  }

  cropper-canvas {
    height: 320px;
  }
}
</style>

限制最大间距和（或）最小间距

间距指图像四条边到其父元素对应边的距离（上、右、下、左），负值表示图像超出画布。违反限制的变换会被拒绝。

Details

vue

<template>
  <div class="cropper-container">
    <form>
      <fieldset>
        <legend>Max Inset:</legend>
        <select
          id="maxInsetOption"
          v-model="maxInsetOption"
          name="maxInsetOption"
        >
          <option
            v-for="option in options"
            :key="option"
            :value="option"
          >
            {{ option }}
          </option>
          <option value="">
            custom
          </option>
        </select>
        <input
          v-if="maxInsetOption === ''"
          id="maxInset"
          v-model="maxInsetCustom"
          type="text"
          name="maxInset"
          placeholder="e.g. 10px 5% 1rem"
          autocomplete="off"
        >
      </fieldset>
      <fieldset>
        <legend>Min Inset:</legend>
        <select
          id="minInsetOption"
          v-model="minInsetOption"
          name="minInsetOption"
        >
          <option
            v-for="option in options"
            :key="option"
            :value="option"
          >
            {{ option }}
          </option>
          <option value="">
            custom
          </option>
        </select>
        <input
          v-if="minInsetOption === ''"
          id="minInset"
          v-model="minInsetCustom"
          type="text"
          name="minInset"
          placeholder="e.g. -50px 0"
          autocomplete="off"
        >
      </fieldset>
    </form>
    <cropper-canvas
      background
    >
      <cropper-image
        :src="src"
        alt="Picture"
        :max-inset="maxInset"
        :min-inset="minInset"
        rotatable
        scalable
        skewable
        translatable
      />
      <cropper-handle
        action="move"
        plain
      />
    </cropper-canvas>
  </div>
</template>

<script lang="ts">
const { BASE_URL } = import.meta.env;

export default {
  name: 'CropperImageMaxInsetAndMinInsetExample',
  data() {
    return {
      src: `${BASE_URL}picture.jpg`,
      options: [
        'auto',
        '0',
        '50px',
        '-50px',
        '50%',
        '-50px 0',
        '0 50px',
        '0 -50px -100px',
        '10px 20px 30px 40px',
      ],
      maxInsetOption: 'auto',
      maxInsetCustom: '',
      minInsetOption: '-50px 0',
      minInsetCustom: '',
    };
  },
  computed: {
    maxInset(): string {
      return this.maxInsetOption || this.maxInsetCustom || 'auto';
    },
    minInset(): string {
      return this.minInsetOption || this.minInsetCustom || 'auto';
    },
  },
};
</script>

<style lang="scss" scoped>
.cropper-container {
  border: 1px solid var(--vp-c-divider);
  border-radius: 0.375rem;
  margin-bottom: 1rem;
  margin-top: 1rem;
  padding: 1.25rem 1.5rem;

  fieldset {
    border: 1px solid var(--vp-c-divider);
    border-radius: 0.375rem;
    margin-bottom: 1rem;
    padding: 0.25rem 0.75rem 0.75rem 0.75rem;

    > input {
      border: 1px solid var(--vp-c-divider);
      border-radius: 0.25rem;
      display: block;
      margin-top: 0.5rem;
      padding: 0.25rem 0.5rem;
      width: 100%;
    }
  }

  cropper-canvas {
    height: 320px;
  }
}
</style>

限制边界

Details

vue

<template>
  <div class="cropper-container">
    <form>
      <fieldset>
        <legend>Within:</legend>
        <input
          id="withinCanvas"
          v-model="within"
          type="radio"
          name="within"
          value="canvas"
        >
        <label for="withinCanvas">canvas</label>
        <input
          id="withinNone"
          v-model="within"
          type="radio"
          name="within"
          value="none"
        >
        <label for="withinNone">none</label>
      </fieldset>
    </form>
    <cropper-canvas background>
      <cropper-image
        :src="src"
        alt="Picture"
        :min-inset="within === 'canvas' ? '0' : 'auto'"
        rotatable
        scalable
        skewable
        translatable
      />
      <cropper-handle
        action="move"
        plain
      />
    </cropper-canvas>
  </div>
</template>

<script lang="ts">
const { BASE_URL } = import.meta.env;

export default {
  name: 'CropperImageExample',
  data() {
    return {
      src: `${BASE_URL}picture.jpg`,
      within: 'canvas',
    };
  },
};
</script>

<style lang="scss" scoped>
.cropper-container {
  border: 1px solid var(--vp-c-divider);
  border-radius: 0.375rem;
  margin-bottom: 1rem;
  margin-top: 1rem;
  padding: 1.25rem 1.5rem;

  fieldset {
    border: 1px solid var(--vp-c-divider);
    border-radius: 0.375rem;
    margin-bottom: 1rem;
    padding: 0.25rem 0.75rem 0.75rem 0.75rem;

    > input {
      margin: 0 0.25rem 0 0;
      transform: translateY(-0.5px);
      vertical-align: middle;
    }

    > label {
      margin-right: 0.5rem;
    }
  }

  cropper-canvas {
    height: 320px;
  }
}
</style>

属性

从其父级 CropperElement 继承属性，并实现以下属性：

名称	类型	默认值	可选值	描述
initialFit ^2.2.0	`string`	`"contain"`	`"cover"` \| `"fill"` \| `"contain"` \| `"scale-down"` \| `"none"`	指示图像与其父元素的中心对齐时的初始大小。
maxFit ^2.2.0	`string`	`""`	`"cover"` \| `"fill"` \| `"contain"` \| `"scale-down"` \| `"none"`	指示此元素相对于其父元素的最大尺寸。
minFit ^2.2.0	`string`	`""`	`"cover"` \| `"fill"` \| `"contain"` \| `"scale-down"` \| `"none"`	指示此元素相对于其父元素的最小尺寸。
maxInset ^2.3.0	`string`	`"auto"`	`"auto"`，或 1 到 4 个 `<length>` / `<percentage>` / `calc()` 值，与 CSS `inset` 属性一致	指示图像各边到其父元素对应边的最大距离，顺序为上、右、下、左。`auto` 表示不限制。
minInset ^2.3.0	`string`	`"auto"`	同 `maxInset`	指示图像各边到其父元素对应边的最小距离，顺序为上、右、下、左。`auto` 表示不限制。
rotatable	`boolean`	`false`	-	指示此元素是否可旋转。
scalable	`boolean`	`false`	-	指示此元素是否可缩放。
skewable	`boolean`	`false`	-	指示此元素是否可倾斜。
slottable	`boolean`	`false`	-	指示此元素是否启用默认插槽。
translatable	`boolean`	`false`	-	指示此元素是否可移动。
zoomAroundCenter ^2.3.0	`boolean`	`false`	-	指示是否以图像中心作为缩放原点。
initialCenterSize deprecated	`string`	`"contain"`	`"contain"`, `"cover"`	指示此元素与其父元素的中心对齐时的初始大小。

默认情况下，内置的 <img> 元素将继承以下属性：

alt
crossorigin
decoding
elementtiming
fetchpriority
loading
referrerpolicy
sizes
src
srcset

方法

$ready

语法：
- $ready()
- $ready(callback)
参数：
- callback：
  - 类型：Function
  - 成功加载图片后执行的回调。
返回值：
- 类型：Promise
- 一个以图片元素为给定值解析后的 Promise。

示例：

const cropperImage = new CropperImage();

cropperImage.$ready((image) => {
  console.log(image.naturalWidth, image.naturalHeight);
});
cropperImage.src = '/cropperjs/picture.jpg';

成功加载图像后延迟执行回调。

$center

语法：
- $center()
- $center(size)
参数：
- size：
  - 类型：string
  - 可选值："cover"、"fill"、"contain"、"scale-down" 和 "none".
  - 图像的尺寸模式。
返回值：
- 类型：CropperImage
- 元素实例。

将图像与其父元素的中心对齐。

$move

语法：
- $move(x)
- $move(x, y)
参数：
- x：
  - 类型：number
  - 水平方向的移动距离。
- y：
  - 类型：number
  - 默认值：x
  - 垂直方向的移动距离。
返回值：
- 类型：CropperImage
- 元素实例。

移动图像。

$moveTo

语法：
- $moveTo(x)
- $moveTo(x, y)
参数：
- x：
  - 类型：number
  - 水平方向的新位置。
- y：
  - 类型：number
  - 默认值：x
  - 垂直方向的新位置。
返回值：
- 类型：CropperImage
- 元素实例。

移动图像到指定位置。

$rotate

语法：$rotate(angle)
参数：
- angle：
  - 类型：number | string
  - 旋转角度（以弧度为单位）。默认单位是 rad。
- x：
  - 类型：number
  - 默认值：图像在水平方向的中心。
  - 水平方向的旋转原点。
- y：
  - 类型：number
  - 默认值：图像在垂直方向的中心。
  - 垂直方向的旋转原点。
返回值：
- 类型：CropperImage
- 元素实例。
示例：
- $rotate(0.8)
- $rotate('0.8rad')
- $rotate('45deg')
- $rotate('50grad')
- $rotate('0.1turn')
- $rotate('90deg', 0, 0)

旋转图像。它类似于 CSS 函数 rotate() 或 CanvasRenderingContext2D.rotate()。

$zoom

语法：
- $zoom(scale)
- $zoom(scale, x, y)
参数：
- scale：
  - 类型：number
  - 缩放系数。正数表示放大，负数表示缩小。
- x：
  - 类型：number
  - 默认值：图像在水平方向的中心。
  - 水平方向的缩放原点。
- y：
  - 类型：number
  - 默认值：图像在垂直方向的中心。
  - 垂直方向的缩放原点。
返回值：
- 类型：CropperImage
- 元素实例。

示例：

cropperImage.$zoom(0.1); // 放大 10%
cropperImage.$zoom(-0.1); // 缩小 10%
cropperImage.$zoom(0.1, 0, 0); // 以图片左上角为原点放大 10%
cropperImage.$zoom(-0.1, 0, 0); // 以图片左上角为原点缩小 10%

缩放图像。

$scale

语法：
- $scale(x)
- $scale(x, y)
参数：
- x：
  - 类型：number
  - 水平方向的缩放系数。
- y：
  - 类型：number
  - 默认值：x
  - 垂直方向的缩放系数。
返回值：
- 类型：CropperImage
- 元素实例。

示例：

cropperImage.$scale(1.1); // 放大 10%
cropperImage.$scale(0.9); // 缩小 10%
cropperImage.$scale(-1); // 翻转水平和垂直方向
cropperImage.$scale(-1, 1); // 翻转水平方向
cropperImage.$scale(1, -1); // 翻转垂直方向

缩放图像。它类似于 CSS 函数 scale() 或 CanvasRenderingContext2D.scale()。

$skew

语法：
- $skew(x)
- $skew(x, y)
参数：
- x：
  - 类型：number | string
  - 水平方向的倾斜角度。默认单位是 rad。
- y：
  - 类型：number | string
  - 默认值：x
  - 垂直方向的倾斜角度。默认单位是 rad。
返回值：
- 类型：CropperImage
- 元素实例。
示例：
- $skew(0.8)
- $skew('0.8rad')
- $skew('45deg')
- $skew('50grad')
- $skew('0.1turn')
- $skew(0, 0.8)

倾斜图像。它类似于 CSS 函数 skew()。

$translate

语法：
- $translate(x)
- $translate(x, y)
参数：
- x：
  - 类型：number
  - 水平方向的平移距离。
- y：
  - 类型：number
  - 默认值：x
  - 垂直方向的平移距离。
返回值：
- 类型：CropperImage
- 元素实例。

平移图像。它类似于 CSS 函数 translate() 或 CanvasRenderingContext2D.translate()。

$transform

语法：$transform(a, b, c, d, e, f)
参数：
- a：
  - 类型：number
  - 水平方向的缩放系数。
- b：
  - 类型：number
  - 垂直方向的倾斜角度。
- c：
  - 类型：number
  - 水平方向的倾斜角度。
- d：
  - 类型：number
  - 垂直方向的缩放系数。
- e：
  - 类型：number
  - 水平方向的平移距离。
- f：
  - 类型：number
  - 垂直方向的平移距离。
返回值：
- 类型：CropperImage
- 元素实例。

变换图像。它类似于 CSS 函数 matrix() 或 CanvasRenderingContext2D.transform()。

$setTransform

语法：
- $setTransform(a, b, c, d, e, f)
- $setTransform(a)
参数：
- a：
  - 类型：number | Array
  - 水平方向的缩放系数，或变换矩阵。
- b：
  - 类型：number
  - 垂直方向的倾斜角度。
- c：
  - 类型：number
  - 水平方向的倾斜角度。
- d：
  - 类型：number
  - 垂直方向的缩放系数。
- e：
  - 类型：number
  - 水平方向的平移距离。
- f：
  - 类型：number
  - 垂直方向的平移距离。
返回值：
- 类型：CropperImage
- 元素实例。

将当前变换重置（覆盖）为指定的单位矩阵，然后调用由该方法的参数描述的变换。这使你可以缩放、旋转、平移（移动）和倾斜上下文。它类似于 CanvasRenderingContext2D.setTransform()。

$getTransform

语法：$getTransform()
返回值：
- 类型：Array
- 元素的当前变换矩阵。

检索应用于元素的当前变换矩阵。它类似于 CanvasRenderingContext2D.getTransform()。

$resetTransform

语法：
- $resetTransform()
等同于：
- $setTransform(1, 0, 0, 1, 0, 0)
- $setTransform([1, 0, 0, 1, 0, 0])
返回值：
- 类型：CropperImage
- 元素实例。

将当前变换重置为初始单位矩阵。它类似于 CanvasRenderingContext2D.resetTransform()。

事件

transform

事件：
- event.bubbles：true
- event.cancelable：true
- event.composed：true
- event.detail：
  - 类型：Object
  - 图像的变换信息。
- event.detail.matrix：
  - 类型：Array
  - 新的（下一个）矩阵对象。
- event.detail.oldMatrix：
  - 类型：Array
  - 旧的（当前）矩阵对象。

当元素的 transform CSS 属性将要变更时，将触发该事件。

change ^2.2.0

当图像的位置和尺寸即将发生变化时触发该事件。

事件：
- event.bubbles：true
- event.cancelable：true
- event.composed：true
- event.detail：
  - 类型：Object
  - 图像的位置和大小数据。
- event.detail.x：
  - 类型：number
  - 图像的 x 轴坐标。
- event.detail.y：
  - 类型：number
  - 图像的 y 轴坐标。
- event.detail.width：
  - 类型：number
  - 图像的宽度。
- event.detail.height：
  - 类型：number
  - 图像的高度。
示例：

html

<cropper-image id="image"></cropper-image>

<script>
document.querySelector('#image').addEventListener('change', function (event) {
  console.log(event);
});
</script>

插槽

此元素中没有可用的插槽。

你可以通过将 slottable 属性设置为 true 来启用默认插槽：
html
<cropper-image slottable></cropper-image>

CropperImage ​

示例 ​

基本 ​

有图片源 ​

围绕中心缩放 ​

设置初始尺寸 ​

限制最大尺寸和（或）最小尺寸 ​

限制最大间距和（或）最小间距 ​

限制边界 ​

属性 ​

方法 ​

$ready ​

$center ​

$move ​

$moveTo ​

$rotate ​

$zoom ​

$scale ​

$skew ​

$translate ​

$transform ​

$setTransform ​

$getTransform ​

$resetTransform ​

事件 ​

transform ​

change ^2.2.0 ​

插槽 ​

CropperImage

示例

基本

有图片源

围绕中心缩放

设置初始尺寸

限制最大尺寸和（或）最小尺寸

限制最大间距和（或）最小间距

限制边界

属性

方法

$ready

$center

$move

$moveTo

$rotate

$zoom

$scale

$skew

$translate

$transform

$setTransform

$getTransform

$resetTransform

事件

transform

change ^2.2.0

插槽