CropperSelection

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

示例

基本

TIP

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

自定义初始覆盖范围

自定义位置和大小

带有手柄

动态变化

将 dynamic 属性设置为 true，以随着图像的变化而变化.

多选区

将 multiple 属性设置为 true，以支持在同一图像上的创建多个选区。

围绕中心调整大小

将 resizeAroundCenter 属性设置为 true，调整大小时选区中心保持不变。

围绕中心缩放

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

固定选区

移动或缩放图片时，选区保持不动。拖动图片可调整其位置，滚动鼠标滚轮可缩放图片。

圆角

设置 border-radius 属性可为选区添加圆角，支持 CSS border-radius 语法，同时也会应用到 $toCanvas() 生成的 canvas。

限制边界

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="withinImage"
          v-model="within"
          type="radio"
          name="within"
          value="image"
        >
        <label for="withinImage">image</label>
        <input
          id="withinNone"
          v-model="within"
          type="radio"
          name="within"
          value="none"
        >
        <label for="withinNone">none</label>
      </fieldset>
    </form>
    <cropper-canvas
      ref="cropperCanvas"
      :key="within"
      background
    >
      <cropper-image
        ref="cropperImage"
        :src="src"
        alt="Picture"
        :rotatable="within !== 'image'"
        :scalable="within !== 'image'"
        :skewable="within !== 'image'"
        :translatable="within !== 'image'"
      />
      <cropper-handle
        action="move"
        plain
      />
      <cropper-selection
        initial-coverage="0.5"
        :min-inset="minInset"
        movable
        resizable
        outlined
      >
        <cropper-grid
          role="grid"
          covered
        />
        <cropper-crosshair centered />
        <cropper-handle
          action="move"
          theme-color="rgba(255, 255, 255, 0.35)"
        />
        <cropper-handle action="n-resize" />
        <cropper-handle action="e-resize" />
        <cropper-handle action="s-resize" />
        <cropper-handle action="w-resize" />
        <cropper-handle action="ne-resize" />
        <cropper-handle action="nw-resize" />
        <cropper-handle action="se-resize" />
        <cropper-handle action="sw-resize" />
      </cropper-selection>
    </cropper-canvas>
  </div>
</template>

<script lang="ts">
import type CropperCanvas from '@cropper/element-canvas';
import type CropperImage from '@cropper/element-image';

const { BASE_URL } = import.meta.env;

export default {
  name: 'CropperSelectionExample',
  data() {
    return {
      src: `${BASE_URL}picture.jpg`,
      within: 'canvas',
      minInset: '0',
    };
  },
  watch: {
    within: 'updateMinInset',
  },
  methods: {
    async updateMinInset() {
      const { within } = this;

      this.minInset = within === 'canvas' ? '0' : 'auto';

      if (within !== 'image') {
        return;
      }

      // Waits for the canvas to be re-created by the `key` change.
      await this.$nextTick();

      const cropperCanvas = this.$refs.cropperCanvas as CropperCanvas;
      const cropperImage = this.$refs.cropperImage as CropperImage;

      await cropperImage.$ready();

      if (this.within !== within) {
        return;
      }

      const canvasRect = cropperCanvas.getBoundingClientRect();
      const imageRect = cropperImage.getBoundingClientRect();

      this.minInset = [
        imageRect.top - canvasRect.top,
        canvasRect.right - imageRect.right,
        canvasRect.bottom - imageRect.bottom,
        imageRect.left - canvasRect.left,
      ].map((value) => `${value}px`).join(' ');
    },
  },
};
</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 继承属性，并实现以下属性：

名称	类型	默认值	可选值	描述
x	`number`	`0`	-	指示选区的 x 轴坐标。
y	`number`	`0`	-	指示选区的 y 轴坐标。
width	`number`	`0`	-	指示选区的宽度。
height	`number`	`0`	-	指示选区的高度。
aspectRatio	`number`	`NaN`	-	指示选区的纵横比，必须是正数。
borderRadius ^2.3.0	`string`	`''`	-	定义选区及导出 canvas 的圆角，支持 CSS `border-radius` 语法（如 `10px`、`25%`、`10% 20% 30% 40%`、`10% 20% / 30% 40%`）。输出 canvas 尺寸变化时，像素值会等比缩放。
initialAspectRatio	`number`	`NaN`	-	指示选区的初始长宽比，必须一个正数。
initialCoverage	`number`	`NaN`	-	指示选区的初始覆盖范围，必须是在 `0` （0％）和 `1` （100%）之间的正数。
dynamic	`boolean`	`false`	-	指示此选区是否是动态的，以及是否随着图像的变化而变化。
movable	`boolean`	`false`	-	指示此元素是否可移动。
maxInset ^2.3.0	`string`	`"auto"`	`"auto"`，或 1 到 4 个 `<length>` / `<percentage>` / `calc()` 值，与 CSS `inset` 属性一致	指示选区各边到其父元素对应边的最大距离，顺序为上、右、下、左。`auto` 表示不限制。违反限制的变更会被拒绝。
minInset ^2.3.0	`string`	`"auto"`	同 `maxInset`	指示选区各边到其父元素对应边的最小距离，顺序为上、右、下、左。`auto` 表示不限制。违反限制的变更会被拒绝。
resizable	`boolean`	`false`	-	指示此元素是否可调整大小。
resizeAroundCenter ^2.3.0	`boolean`	`false`	-	指示调整选区大小时是否保持中心位置不变。
zoomable	`boolean`	`false`	-	指示此元素是否可缩放。
zoomAroundCenter ^2.3.0	`boolean`	`false`	-	指示是否以选区中心作为缩放原点。
multiple	`boolean`	`false`	-	指示是否支持多选区。
keyboard	`boolean`	`false`	-	指示是否支持键盘控制。
outlined	`boolean`	`false`	-	指示是否显示轮廓线。
precise	`boolean`	`false`	-	指示是否保留 `x`、`y`、`width` 和 `height` 属性的精确值。

支持的键盘键：

Delete 或 Command + Backspace：删除活动选区。
ArrowLeft：将活动选区向左移动 1 个像素。
ArrowRight：将活动选区向右移动 1 个像素。
ArrowUp：将活动选区向上移动 1 个像素。
ArrowDown：将活动选区向下移动 1 个像素。
+：将活动选区放大 10%。
-：将活动选区缩小 10%。

方法

$center

语法：$center()
返回值：
- 类型：CropperSelection
- 元素实例。

将选区与其父元素的中心对齐。

$move

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

移动选区。

$moveTo

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

移动选区到指定位置。

$resize

语法：
- $resize(action)
- $resize(action, offsetX)
- $resize(action, offsetX, offsetY)
- $resize(action, offsetX, offsetY, aspectRatio)
参数：
- action：
  - 类型：string
  - 可选值："n-resize", "e-resize", "s-resize", "w-resize", "ne-resize", "nw-resize", "se-resize", and "sw-resize".
  - 指示要调整大小的边或角。
- offsetX：
  - 类型：number
  - 默认值：0
  - 指定边或角的水平偏移。
- offsetY：
  - 类型：number
  - 默认值：0
  - 指定边或角的垂直偏移。
- aspectRatio：
  - 类型：number
  - 默认值：this.aspectRatio
  - 必要时计算新尺寸的纵横比。
返回值：
- 类型：CropperSelection
- 元素实例。

调整指定边或角上选区的大小。

$zoom

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

示例：

cropperSelection.$zoom(0.1); // 放大 10%
cropperSelection.$zoom(-0.1); // 缩小 10%

缩放选区。同时直接变更选区的宽度和高度（以像素为单位）。

$change

语法：
- $change(x, y)
- $change(x, y, width, height)
- $change(x, y, width, height, aspectRatio)
参数：
- x：
  - 类型：number
  - 水平方向的新位置。
- y：
  - 类型：number
  - 垂直方向的新位置。
- width：
  - 类型：number
  - 默认值：this.width
  - 新宽度。
- height：
  - 类型：number
  - 默认值：this.height
  - 新高度。
- aspectRatio：
  - 类型：number
  - 默认值：this.aspectRatio
  - 仅限当前变更的新纵横比。
返回值：
- 类型：CropperSelection
- 元素实例。

变更选区的位置和/或大小。

$reset

语法：$reset()
返回值：
- 类型：CropperSelection
- 元素实例。

将选区重置为其初始位置和大小。

$clear

语法：$clear()
返回值：
- 类型：CropperSelection
- 元素实例。

清空选区。

$render

语法：$render()
返回值：
- 类型：CropperSelection
- 元素实例。

刷新选区的位置或大小。

$toCanvas

语法：
- $toCanvas()
- $toCanvas(options)
参数：
- options：
  - 类型：Object
  - 可用选项。
  - 属性：
    - width：
      - 类型：number
      - 画布的宽度。
    - height：
      - 类型：number
      - 画布的高度。
    - beforeDraw：
      - 类型：Function
      - 在将图像绘制到画布上之前调用的函数。
      - 语法：beforeDraw(context, canvas)
      - 参数：
        context：
        类型：CanvasRenderingContext2D
        画布的 2D 渲染上下文。
        canvas：
        类型：HTMLCanvasElement
        画布元素本身。
      - 示例：function (context) { context.filter = 'grayscale(100%)'; }
返回值：
- 类型：Promise
- 一个以生成的画布元素为给定值解析后的 Promise 对象。
示例：

生成一个真实的画布元素，如果有图像（仅限选定区域），则将其绘制到其中。

事件

change

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

事件：
- 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-selection id="selection"></cropper-selection>

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

插槽

此元素中只有一个默认插槽。

你可以通过将 slottable 属性设置为 false 来禁用它：
html
<cropper-selection slottable="false"></cropper-selection>

CropperSelection ​

示例 ​

基本 ​

自定义初始覆盖范围 ​

自定义位置和大小 ​

带有手柄 ​

动态变化 ​

多选区 ​

围绕中心调整大小 ​

围绕中心缩放 ​

固定选区 ​

圆角 ​

限制边界 ​

属性 ​

方法 ​

$center ​

$move ​

$moveTo ​

$resize ​

$zoom ​

$change ​

$reset ​

$clear ​

$render ​

$toCanvas ​

事件 ​

change ​

插槽 ​