repository·master·Indexed 22 days ago
https://github.com/advanced-cropper/vue-advanced-cropperA highly customizable image cropping library for Vue.js supporting mobile and desktop. It provides a Cropper component with various cropping modes, aspect ratio restrictions, and canvas/coordinate outputs. The library includes specialized components like BoundingBox, DraggableArea, StencilPreview, and CircleStencil to allow developers to build fully custom cropping UIs.
Preview component is used to display a preview of the cropped image. It can be populated using the results from the cropper component.Init Stretcher algorithm is used to initialize a stretcher, which is a special element designed to stretch the cropper to fit an image. The core logic of this algorithm is to attempt to fit an image into the available container dimensions.The resetCoordinates method is triggered automatically on every successful image change. It follows this sequence:
defaultSize (returns { width, height }).defaultPosition (returns { left, top }).[{ width, height }, { left, top }].A custom stencil is a Vue component that allows you to define unique cropping shapes (like a circle) and custom resize/move logic. To work correctly with the cropper, a custom stencil must follow a specific contract:
image, coordinates, transitions, and stencilCoordinates as props.aspectRatios(): It must provide a method that returns an object with minimum and maximum fields (e.g., { minimum: 1, maximum: 1 } for a circle).StencilPreview component to show the user what is being cropped.move, move-end, resize, and resize-end events to communicate changes back to the main cropper.stencilCoordinates prop to set the stencil's position via CSS transform (specifically translate(left, top)) to avoid lag and flickering.<script>
export default {
name: 'CircleStencil',
props: {
image: Object,
coordinates: Object,
transitions: Object,
stencilCoordinates: Object,
},
methods: {
aspectRatios() {
return { minimum: 1, maximum: 1 };
}
}
};
</script>
<template>
<div class="circle-stencil" :style="style"></div >
</template>A stencil can be any arbitrary component, but to function correctly with the Cropper's resize algorithm and interaction model, it must meet these requirements:
width, height, left, top).aspectRatios() method. This method should return an object containing minimum and maximum aspect ratio values.resize and move events to communicate user interactions back to the cropper.When migrating to 1.0+, note the following changes to how the cropper renders:
background-class to set a background-color, it will only fill the area within the cropper boundary. To apply a background color to the entire cropper area (including parts wider or taller than the boundary), use the standard class attribute instead.foreground-class prop. This layer sits between the image and the stencil and is typically used to darken the image.::: danger
Important: Do not pass these props directly to the CircleStencil component. They are internal service props injected by the Cropper component itself.
:::
image: An object containing image metadata: { src, width, height, transforms, loaded }.stencilCoordinates: An object { left, right, height, width } representing the stencil's coordinates relative to the visible area.transitions: A Boolean indicating if transitions are currently allowed.BoundingBox component serves as a foundational service component used to construct typical stencil components (like a cropping rectangle). It provides the structural logic for managing handlers (corners/edges) and lines (sides) that make up a selection area.The Cropper component's logic is built on four key concepts:
defaultBoundaries prop to force the boundaries to fill the cropper.boundaries. It is defined by left, top, width, and height relative to the image.left, top, width, height) of the image fragment relative to the image, located within the visibleArea.The anchor property is critical for implementing accurate stencil resizing algorithms.
When building a resize algorithm, relying solely on the current cursor position can lead to inaccuracies because the cursor might not align perfectly with the handler's center after a movement. To ensure the mouse cursor remains at the exact same relative point on the handler where the user started the drag, you should use the anchor coordinates to adjust the resize box (the stencil). By calculating the offset based on the anchor, you can compensate for the movement and achieve the expected visual result.
The applyTransforms method is the core mechanism for updating coordinates. It is used internally by setCoordinates, resetCoordinates, and when adapting to prop changes like minWidth, maxWidth, minHeight, or maxHeight.
Note: Do not call applyTransforms directly.
applyTransforms(transforms, autoZoom)
transforms: An object containing new coordinates or an array containing one coordinate object.autoZoom: A boolean indicating whether to use the auto-zoom algorithm (translating and resizing the visible area to fit the new coordinates).For each transform provided:
width or height): Uses the approximatedSize algorithm to create a box. This respects aspect ratio and min/max constraints. The box is moved back to its previous position based on positionRestrictions (note: it may move outside the current visibleArea).left or top): Moves the box to the specified coordinates, respecting positionRestrictions.autoZoom is true, the visible area is transformed so that the new coordinates fit within it.onChangeCoordinates to update internal state and emit the corresponding event.The library is conceptually divided into two parts to allow for maximum flexibility:
Cropper: The root component that manages the logic. It handles the image, boundaries, visible area, and the mathematical coordinates of the crop.Stencil: An arbitrary component used to visualize the cropped area and provide user interaction (moving and resizing).The Cropper operates on abstract coordinates, while the Stencil is responsible for rendering those coordinates as a UI element that the user can manipulate. This separation allows you to build highly custom cropping interfaces by providing your own stencil component.
<!-- The Cropper manages logic, while the Stencil manages UI/Interaction -->
<cropper>
<my-custom-stencil />
</cropper>