---
sidebar: auto
---
# 指南
## 介绍
Cropper.js 2.0 是一系列用于图像裁剪的 Web 组件。
- **Cropper.js 1.0 和 Cropper.js 2.0 有什么区别?**
| 类型 | Cropper.js 1.0 | Cropper.js 2.0 |
| --- | --- | --- |
| 创建于 | 2015 | 2021 |
| 状态 | 维护中 | 活跃中 |
| 包数量 | 1 | 12+ |
| 架构 | 一体化 | 模块化 |
| 浏览器兼容性 | 现代浏览器 / IE 9+ | 现代浏览器 |
| 可扩展 | 否 | 是 |
| 可定制 | 否 | 是 |
| CSS-in-JS | 否 | 是 |
| 按需引用 | 否 | 是 |
| 多选区 | 否 | 是 |
| 触摸旋转图片 | 否 | 是 |
- **Cropper、Cropper.js 和 jQuery Cropper 之间有什么区别?**
| GitHub 项目 | npm 包 | 依赖 | 创建于 | 状态 | 描述 |
| --- | --- | --- | --- | --- | --- |
| [Cropper](https://github.com/fengyuanchen/cropper) | [`cropper`](https://www.npmjs.com/package/cropper) | [`jquery`](https://www.npmjs.com/package/jquery) | 2014 | 已废弃 | 一个简单的 jQuery 图像裁剪插件。 |
| [Cropper.js](https://github.com/fengyuanchen/cropperjs) | [`cropperjs`](https://www.npmjs.com/package/cropperjs) | - | 2015 | 活跃中 | JavaScript 图片裁剪器。 |
| [jQuery Cropper](https://github.com/fengyuanchen/jquery-cropper) | [`jquery-cropper`](https://www.npmjs.com/package/jquery-cropper) | [`jquery`](https://www.npmjs.com/package/jquery) + [`cropperjs@1`](https://www.npmjs.com/package/cropperjs) | 2018 | 维护中 | Cropper.js 1.0 的 jQuery 插件包装器。 |
## 入门
### 安装
#### npm
在使用 Cropper.js 构建大型应用程序时,推荐使用 npm 安装方法。
```sh
npm install cropperjs
```
对于特定的包:
```sh
npm install @cropper/element-canvas
```
#### CDN
出于原型设计或学习目的,你可以使用最新版本:
```html
```
对于生产,我们建议链接到特定版本号和文件名以避免新版本意外损坏。
### 使用
#### 在 JavaScript 中使用
导入 Cropper 类并构造一个新的 Cropper 实例。
```js
import Cropper from 'cropperjs';
// import { createCropper } from 'cropperjs';
const cropper = new Cropper('#image');
// const cropper = createCropper('#image');
```
```html
```
#### 在 DOM 中使用
从 `cropperjs` 包中导入所有 Cropper 元素,并自动将它们[定义](https://developer.mozilla.org/zh-CN/docs/Web/API/CustomElementRegistry/define)为自定义元素。
```js
import 'cropperjs';
```
:::live-demo
```html
```
:::
#### 按需引用
仅导入所需的 Cropper 元素,然后手动将它们[定义](https://developer.mozilla.org/zh-CN/docs/Web/API/CustomElementRegistry/define)为自定义元素。
```js
import CropperCanvas from '@cropper/element-canvas';
import CropperImage from '@cropper/element-image';
import CropperHandle from '@cropper/element-handle';
CropperCanvas.$define();
CropperImage.$define();
CropperHandle.$define();
```
:::live-demo
```html
```
:::
## 安装包
Cropper.js 包含一系列 [npm](https://www.npmjs.com/) 包:
| 安装包名称 | 版本 | 描述 |
| --- | --- | --- |
| `cropperjs` | [](https://www.npmjs.com/package/cropperjs) | 完整包。 |
| `@cropper/element` | [](https://www.npmjs.com/package/@cropper/element) | 用于构造 Cropper 元素的抽象类。 |
| `@cropper/element-canvas` | [](https://www.npmjs.com/package/@cropper/element-canvas) | Cropper 的自定义画布元素。 |
| `@cropper/element-image` | [](https://www.npmjs.com/package/@cropper/element-image) | Cropper 的自定义图像元素。 |
| `@cropper/element-shade` | [](https://www.npmjs.com/package/@cropper/element-shade) | Cropper 的自定义阴影元素。 |
| `@cropper/element-handle` | [](https://www.npmjs.com/package/@cropper/element-handle) | Cropper 的自定义手柄元素。 |
| `@cropper/element-selection` | [](https://www.npmjs.com/package/@cropper/element-selection) | Cropper 的自定义选区元素。 |
| `@cropper/element-grid` | [](https://www.npmjs.com/package/@cropper/element-grid) | Cropper 的自定义网格元素。 |
| `@cropper/element-crosshair` | [](https://www.npmjs.com/package/@cropper/element-crosshair) | Cropper 的自定义十字准线元素。 |
| `@cropper/element-viewer` | [](https://www.npmjs.com/package/@cropper/element-viewer) | Cropper 的自定义查看器元素。 |
| `@cropper/elements` | [](https://www.npmjs.com/package/@cropper/elements) | Cropper 的一系列自定义元素。 |
| `@cropper/utils` | [](https://www.npmjs.com/package/@cropper/utils) | Cropper 的一系列常用常量和实用函数。 |
## 接口
| 接口名称 | 继承自 | 描述 |
| --- | --- | --- |
| `Cropper` | `Function` | `Cropper` 构造函数用于创建一个新的 Cropper 实例。 |
| `CropperElement` | `HTMLElement` | `CropperElement` 接口代表任何 Cropper 元素,扩展了 [HTMLElement](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLElement) 接口。 |
| `CropperCanvas` | `CropperElement` | `CropperCanvas` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
| `CropperImage` | `CropperElement` | `CropperImage` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
| `CropperShade` | `CropperElement` | `CropperShade` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
| `CropperHandle` | `CropperElement` | `CropperHandle` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
| `CropperSelection` | `CropperElement` | `CropperSelection` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
| `CropperGrid` | `CropperElement` | `CropperGrid` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
| `CropperCrosshair` | `CropperElement` | `CropperCrosshair` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
| `CropperViewer` | `CropperElement` | `CropperViewer` 接口提供了用于操作 `` 元素的布局和表示的属性和方法。 |
## 浏览器支持
- Edge 79+
- Firefox 63+
- Chrome 54+
- Safari 10.1+
- Opera 41+
- iOS Safari 10.3+
- Android Browser 81+
- Opera Mobile 46+
- Chrome for Android 81+
- Firefox for Android 68+
- Samsung Internet 6.2+