API Reference #

Because this plugin is a Vue component wrapper for Cropper.js, all APIs of Cropper.js are synchronized.

This document only records the properties and methods of component extensions. If you need more advanced functions, you can use the original Cropper.js API through the cropper instance. Click to read Cropper.js API Documentation.

Props #

You can adjust it yourself by referring to the demo code of live demos.

• Example:

<template>
  <VuePictureCropper
    :boxStyle="{
      width: '100%',
      height: '100%',
      backgroundColor: '#f8f8f8',
      margin: 'auto',
    }"
    :img="pic"
    :options="{
      viewMode: 1,
      dragMode: 'crop',
      aspectRatio: 16 / 9,
    }"
    @ready="ready"
  />
</template>

Options #

Option parameters passed to Cropper.js, for a complete list of options, please refer to Cropper.js Options Documentation .

Common options are as follows:

• Example:

<template>
  <VuePictureCropper
    :options="{
      viewMode: 1,
      dragMode: 'crop',
      aspectRatio: 16 / 9,
    }"
  />
</template>

Events #

Events passed to Cropper.js, each event is bound using v-on: or @, similar to the component Emits, for a complete list of events, please refer to Cropper.js event documentation 。

• Example:

<template>
  <VuePictureCropper @ready="ready" />
</template>

Methods #

The component extends several common methods on the basis of Cropper.js, and various APIs of the plugin can be called through the cropper instance.

Type Declarations #

export interface CropperInstance extends Cropper {
  /**
   * Get the cropped Base64 result
   * @description can be used for local preview display
   */
  getDataURL: (options?: Record<string, any>) => string

  /**
   * Get the cropped blob result
   * @description can be used to pass to the server
   */
  getBlob: (options?: Record<string, any>) => Promise<Blob | null>

  /**
   * Get the cropped file result
   * @description can be used to pass to the server
   * @since 0.2.0
   */
  getFile: (options?: Record<string, any>) => Promise<File | null>
}

Have to be aware of is:

1. getDataURL is a synchronous method, you can get the result directly
2. getBlob and getFile are asynchronous methods starting from 0.3.0, and need to cooperate with Promise or async / await to get the result

All three methods belong to the built-in method of the plug-in. The generated file format is based on the format of the source image, and only supports processing local images, not remote images.

In addition, there are two common methods based on Cropper.js, which can be operated through examples:

1. Clear crop box cropper.clear()
2. Reset crop box cropper.reset()

Parameters #

The three methods of component extension can be passed in as parameters, which are used to control the changes of the obtained results.

Examples #

Get the Base64 image using getDataURL, this is a synchronous method:

// Set the specified size after cropping to `400 x 250`
const opt = {
  width: 400,
  height: 250,
}

// After cropping, the result will be generated according to this size
const dataURL = cropper.getDataURL(opt)

If you want to get Blob and File formats, please remember to use asynchronous methods:

cropper.getBlob().then((blob) => {
  console.log('Blob', blob)
})
// Or use `await cropper.getBlob()`

cropper.getFile().then((file) => {
  console.log('File', file)
})
// Or use `await cropper.getFile()`

If you need to convert formats or process remote images, please use the getCroppedCanvas API, it provided by Cropper.js. This method has some asynchronous operations, please pay attention to the usage instructions.