refactor(element-selection)!: rename the linked property to dynamic and disable it by default

ref #1175

Author: fengyuanchen

docs/.vitepress/components/CropperPlayground.vue

@@ -890,6 +890,15 @@
               step="0.1"
             >
           </li>
+          <li>
+            <label for="selectionLinked">dynamic</label>
+            <input
+              id="selectionLinked"
+              v-model="selection.dynamic"
+              type="checkbox"
+              name="dynamic"
+            >
+          </li>
           <li>
             <label for="selectionMovable">movable</label>
             <input
@@ -953,15 +962,6 @@
               name="precise"
             >
           </li>
-          <li>
-            <label for="selectionLinked">linked</label>
-            <input
-              id="selectionLinked"
-              v-model="selection.linked"
-              type="checkbox"
-              name="linked"
-            >
-          </li>
           <li>
             <button
               type="button"
@@ -1611,7 +1611,7 @@
           :keyboard="selection.keyboard"
           :outlined="selection.outlined"
           :precise="selection.precise"
-          :linked="selection.linked"
+          :dynamic="selection.dynamic"
           @change="onSelectionChange"
         >
           <cropper-grid
@@ -1815,14 +1815,14 @@ export default {
         aspectRatio: undefined,
         initialAspectRatio: undefined,
         initialCoverage: 0.5,
+        dynamic: false,
         movable: true,
         resizable: true,
         zoomable: true,
         multiple: false,
         keyboard: false,
         outlined: false,
         precise: false,
-        linked: true,
       },
       grid: {
         hidden: false,

docs/api/cropper-selection.md

@@ -142,14 +142,14 @@ Inherits properties from its parent, [`CropperElement`](cropper-element.html), a
 | aspectRatio | `number` | `NaN` | - | Indicates the aspect ratio of the selection, must a positive number. |
 | initialAspectRatio | `number` | `NaN` | - | Indicates the initial aspect ratio of the selection, must a positive number. |
 | initialCoverage | `number` | `NaN` | - | Indicates the initial coverage of the selection, must a positive number between `0` (0%) and `1` (100%). |
+| dynamic | `boolean` | `false` | - | Indicates whether this selection is dynamic and changes as the image changes. |
 | movable | `boolean` | `false` | - | Indicates whether this element is movable. |
 | resizable | `boolean` | `false` | - | Indicates whether this element is resizable. |
 | zoomable | `boolean` | `false` | - | Indicates whether this element is zoomable. |
 | multiple | `boolean` | `false` | - | Indicates whether multiple selections is supported. |
 | keyboard | `boolean` | `false` | - | Indicates whether keyboard control is supported. |
 | outlined | `boolean` | `false` | - | Indicates whether show the outlined or not. |
 | precise | `boolean` | `false` | - | Indicates whether reserve the precise of the `x`, `y`, `width`, and `height` properties or not. |
-| linked | `boolean` | `false` | - | Indicates whether to link with the cropper image. |
 
 The supported keyboard keys:
 

docs/api/index.md

@@ -42,9 +42,9 @@ The default template for the Cropper:
   <cropper-image></cropper-image>
   <cropper-shade hidden></cropper-shade>
   <cropper-handle action="select" plain></cropper-handle>
-  <cropper-selection initial-coverage="0.5" linked movable resizable zoomable>
+  <cropper-selection initial-coverage="0.5" movable resizable zoomable>
     <cropper-grid role="grid" bordered covered></cropper-grid>
-    <cropper-crosshair theme-color="rgba(238, 238, 238, 0.5)" centered></cropper-crosshair>
+    <cropper-crosshair centered></cropper-crosshair>
     <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle>
     <cropper-handle action="n-resize"></cropper-handle>
     <cropper-handle action="e-resize"></cropper-handle>

docs/guide.md

@@ -91,7 +91,7 @@ import 'cropperjs';
   <cropper-image src="/cropperjs/v2/picture.jpg" alt="Picture" rotatable scalable skewable translatable></cropper-image>
   <cropper-shade hidden></cropper-shade>
   <cropper-handle action="select" plain></cropper-handle>
-  <cropper-selection initial-coverage="0.5" linked movable resizable zoomable>
+  <cropper-selection initial-coverage="0.5" movable resizable zoomable>
     <cropper-grid role="grid" covered></cropper-grid>
     <cropper-crosshair centered></cropper-crosshair>
     <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle>
@@ -141,17 +141,17 @@ Cropper.js contains a series of [npm](https://www.npmjs.com/) packages:
 | Package | Version | Description |
 | --- | --- | --- |
 | `cropperjs` | [![Version](https://img.shields.io/npm/v/cropperjs/next)](https://www.npmjs.com/package/cropperjs/v/next) | The all-in-one package. |
-| `@cropper/element` | [![Version](https://img.shields.io/npm/v/@cropper/element)](https://www.npmjs.com/package/@cropper/element) | An abstract class for constructing Cropper elements. |
-| `@cropper/element-canvas` | [![Version](https://img.shields.io/npm/v/@cropper/element-canvas)](https://www.npmjs.com/package/@cropper/element-canvas) | A custom canvas element for the Cropper. |
-| `@cropper/element-image` | [![Version](https://img.shields.io/npm/v/@cropper/element-image)](https://www.npmjs.com/package/@cropper/element-image) | A custom image element for the Cropper. |
-| `@cropper/element-shade` | [![Version](https://img.shields.io/npm/v/@cropper/element-shade)](https://www.npmjs.com/package/@cropper/element-shade) | A custom shade element for the Cropper. |
-| `@cropper/element-handle` | [![Version](https://img.shields.io/npm/v/@cropper/element-handle)](https://www.npmjs.com/package/@cropper/element-handle) | A custom handle element for the Cropper. |
-| `@cropper/element-selection` | [![Version](https://img.shields.io/npm/v/@cropper/element-selection)](https://www.npmjs.com/package/@cropper/element-selection) | A custom selection element for the Cropper. |
-| `@cropper/element-grid` | [![Version](https://img.shields.io/npm/v/@cropper/element-grid)](https://www.npmjs.com/package/@cropper/element-grid) | A custom grid element for the Cropper. |
-| `@cropper/element-crosshair` | [![Version](https://img.shields.io/npm/v/@cropper/element-crosshair)](https://www.npmjs.com/package/@cropper/element-crosshair) | A custom crosshair element for the Cropper. |
-| `@cropper/element-viewer` | [![Version](https://img.shields.io/npm/v/@cropper/element-viewer)](https://www.npmjs.com/package/@cropper/element-viewer) | A custom viewer element for the Cropper. |
-| `@cropper/elements` | [![Version](https://img.shields.io/npm/v/@cropper/elements)](https://www.npmjs.com/package/@cropper/elements) | A series of custom elements for the Cropper. |
-| `@cropper/utils` | [![Version](https://img.shields.io/npm/v/@cropper/utils)](https://www.npmjs.com/package/@cropper/utils) | A series of common constants and utility functions for Cropper. |
+| `@cropper/element` | [![Version](https://img.shields.io/npm/v/@cropper/element/next)](https://www.npmjs.com/package/@cropper/element) | An abstract class for constructing Cropper elements. |
+| `@cropper/element-canvas` | [![Version](https://img.shields.io/npm/v/@cropper/element-canvas/next)](https://www.npmjs.com/package/@cropper/element-canvas) | A custom canvas element for the Cropper. |
+| `@cropper/element-image` | [![Version](https://img.shields.io/npm/v/@cropper/element-image/next)](https://www.npmjs.com/package/@cropper/element-image) | A custom image element for the Cropper. |
+| `@cropper/element-shade` | [![Version](https://img.shields.io/npm/v/@cropper/element-shade/next)](https://www.npmjs.com/package/@cropper/element-shade) | A custom shade element for the Cropper. |
+| `@cropper/element-handle` | [![Version](https://img.shields.io/npm/v/@cropper/element-handle/next)](https://www.npmjs.com/package/@cropper/element-handle) | A custom handle element for the Cropper. |
+| `@cropper/element-selection` | [![Version](https://img.shields.io/npm/v/@cropper/element-selection/next)](https://www.npmjs.com/package/@cropper/element-selection) | A custom selection element for the Cropper. |
+| `@cropper/element-grid` | [![Version](https://img.shields.io/npm/v/@cropper/element-grid/next)](https://www.npmjs.com/package/@cropper/element-grid) | A custom grid element for the Cropper. |
+| `@cropper/element-crosshair` | [![Version](https://img.shields.io/npm/v/@cropper/element-crosshair/next)](https://www.npmjs.com/package/@cropper/element-crosshair) | A custom crosshair element for the Cropper. |
+| `@cropper/element-viewer` | [![Version](https://img.shields.io/npm/v/@cropper/element-viewer/next)](https://www.npmjs.com/package/@cropper/element-viewer) | A custom viewer element for the Cropper. |
+| `@cropper/elements` | [![Version](https://img.shields.io/npm/v/@cropper/elements/next)](https://www.npmjs.com/package/@cropper/elements) | A series of custom elements for the Cropper. |
+| `@cropper/utils` | [![Version](https://img.shields.io/npm/v/@cropper/utils/next)](https://www.npmjs.com/package/@cropper/utils) | A series of common constants and utility functions for Cropper. |
 
 ## Interfaces
 

docs/zh/api/cropper-selection.md

@@ -142,14 +142,14 @@
 | aspectRatio | `number` | `NaN` | - | 指示选区的纵横比，必须是正数。 |
 | initialAspectRatio | `number` | `NaN` | - | 指示选区的初始长宽比，必须一个正数。 |
 | initialCoverage | `number` | `NaN` | - | 指示选区的初始覆盖范围，必须是在 `0` （0％）和 `1` （100%）之间的正数。 |
+| dynamic | `boolean` | `false` | - | 指示此选区是否是动态的，以及是否随着图像的变化而变化。 |
 | movable | `boolean` | `false` | - | 指示此元素是否可移动。 |
 | resizable | `boolean` | `false` | - | 指示此元素是否可调整大小。 |
 | zoomable | `boolean` | `false` | - | 指示此元素是否可缩放。 |
 | multiple | `boolean` | `false` | - | 指示是否支持多选区。 |
 | keyboard | `boolean` | `false` | - | 指示是否支持键盘控制。 |
 | outlined | `boolean` | `false` | - | 指示是否显示轮廓线。 |
 | precise | `boolean` | `false` | - | 指示是否保留 `x`、`y`、`width` 和 `height` 属性的精确值。 |
-| linked | `boolean` | `false` | - | 指示是否与图片联动。 |
 
 支持的键盘键：
 

docs/zh/api/index.md

@@ -42,9 +42,9 @@ Cropper 的默认模板：
   <cropper-image></cropper-image>
   <cropper-shade hidden></cropper-shade>
   <cropper-handle action="select" plain></cropper-handle>
-  <cropper-selection initial-coverage="0.5" linked movable resizable zoomable>
+  <cropper-selection initial-coverage="0.5" movable resizable zoomable>
     <cropper-grid role="grid" bordered covered></cropper-grid>
-    <cropper-crosshair theme-color="rgba(238, 238, 238, 0.5)" centered></cropper-crosshair>
+    <cropper-crosshair centered></cropper-crosshair>
     <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle>
     <cropper-handle action="n-resize"></cropper-handle>
     <cropper-handle action="e-resize"></cropper-handle>

docs/zh/guide.md

@@ -91,7 +91,7 @@ import 'cropperjs';
   <cropper-image src="/cropperjs/v2/picture.jpg" alt="Picture" rotatable scalable skewable translatable></cropper-image>
   <cropper-shade hidden></cropper-shade>
   <cropper-handle action="select" plain></cropper-handle>
-  <cropper-selection initial-coverage="0.5" linked movable resizable zoomable>
+  <cropper-selection initial-coverage="0.5" movable resizable zoomable>
     <cropper-grid role="grid" covered></cropper-grid>
     <cropper-crosshair centered></cropper-crosshair>
     <cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle>
@@ -141,17 +141,17 @@ Cropper.js 包含一系列 [npm](https://www.npmjs.com/) 包：
 | 安装包名称 | 版本 | 描述 |
 | --- | --- | --- |
 | `cropperjs` | [![Version](https://img.shields.io/npm/v/cropperjs/next)](https://www.npmjs.com/package/cropperjs/v/next) | 完整包。 |
-| `@cropper/element` | [![Version](https://img.shields.io/npm/v/@cropper/element)](https://www.npmjs.com/package/@cropper/element) | 用于构造 Cropper 元素的抽象类。 |
-| `@cropper/element-canvas` | [![Version](https://img.shields.io/npm/v/@cropper/element-canvas)](https://www.npmjs.com/package/@cropper/element-canvas) | Cropper 的自定义画布元素。 |
-| `@cropper/element-image` | [![Version](https://img.shields.io/npm/v/@cropper/element-image)](https://www.npmjs.com/package/@cropper/element-image) | Cropper 的自定义图像元素。 |
-| `@cropper/element-shade` | [![Version](https://img.shields.io/npm/v/@cropper/element-shade)](https://www.npmjs.com/package/@cropper/element-shade) | Cropper 的自定义阴影元素。 |
-| `@cropper/element-handle` | [![Version](https://img.shields.io/npm/v/@cropper/element-handle)](https://www.npmjs.com/package/@cropper/element-handle) | Cropper 的自定义手柄元素。 |
-| `@cropper/element-selection` | [![Version](https://img.shields.io/npm/v/@cropper/element-selection)](https://www.npmjs.com/package/@cropper/element-selection) | Cropper 的自定义选区元素。 |
-| `@cropper/element-grid` | [![Version](https://img.shields.io/npm/v/@cropper/element-grid)](https://www.npmjs.com/package/@cropper/element-grid) | Cropper 的自定义网格元素。 |
-| `@cropper/element-crosshair` | [![Version](https://img.shields.io/npm/v/@cropper/element-crosshair)](https://www.npmjs.com/package/@cropper/element-crosshair) | Cropper 的自定义十字准线元素。 |
-| `@cropper/element-viewer` | [![Version](https://img.shields.io/npm/v/@cropper/element-viewer)](https://www.npmjs.com/package/@cropper/element-viewer) | Cropper 的自定义查看器元素。 |
-| `@cropper/elements` | [![Version](https://img.shields.io/npm/v/@cropper/elements)](https://www.npmjs.com/package/@cropper/elements) | Cropper 的一系列自定义元素。 |
-| `@cropper/utils` | [![Version](https://img.shields.io/npm/v/@cropper/utils)](https://www.npmjs.com/package/@cropper/utils) | Cropper 的一系列常用常量和实用函数。 |
+| `@cropper/element` | [![Version](https://img.shields.io/npm/v/@cropper/element/next)](https://www.npmjs.com/package/@cropper/element) | 用于构造 Cropper 元素的抽象类。 |
+| `@cropper/element-canvas` | [![Version](https://img.shields.io/npm/v/@cropper/element-canvas/next)](https://www.npmjs.com/package/@cropper/element-canvas) | Cropper 的自定义画布元素。 |
+| `@cropper/element-image` | [![Version](https://img.shields.io/npm/v/@cropper/element-image/next)](https://www.npmjs.com/package/@cropper/element-image) | Cropper 的自定义图像元素。 |
+| `@cropper/element-shade` | [![Version](https://img.shields.io/npm/v/@cropper/element-shade/next)](https://www.npmjs.com/package/@cropper/element-shade) | Cropper 的自定义阴影元素。 |
+| `@cropper/element-handle` | [![Version](https://img.shields.io/npm/v/@cropper/element-handle/next)](https://www.npmjs.com/package/@cropper/element-handle) | Cropper 的自定义手柄元素。 |
+| `@cropper/element-selection` | [![Version](https://img.shields.io/npm/v/@cropper/element-selection/next)](https://www.npmjs.com/package/@cropper/element-selection) | Cropper 的自定义选区元素。 |
+| `@cropper/element-grid` | [![Version](https://img.shields.io/npm/v/@cropper/element-grid/next)](https://www.npmjs.com/package/@cropper/element-grid) | Cropper 的自定义网格元素。 |
+| `@cropper/element-crosshair` | [![Version](https://img.shields.io/npm/v/@cropper/element-crosshair/next)](https://www.npmjs.com/package/@cropper/element-crosshair) | Cropper 的自定义十字准线元素。 |
+| `@cropper/element-viewer` | [![Version](https://img.shields.io/npm/v/@cropper/element-viewer/next)](https://www.npmjs.com/package/@cropper/element-viewer) | Cropper 的自定义查看器元素。 |
+| `@cropper/elements` | [![Version](https://img.shields.io/npm/v/@cropper/elements/next)](https://www.npmjs.com/package/@cropper/elements) | Cropper 的一系列自定义元素。 |
+| `@cropper/utils` | [![Version](https://img.shields.io/npm/v/@cropper/utils/next)](https://www.npmjs.com/package/@cropper/utils) | Cropper 的一系列常用常量和实用函数。 |
 
 ## 接口
 

packages/cropperjs/src/template.ts

@@ -3,7 +3,7 @@ export default (
     + '<cropper-image rotatable scalable skewable translatable></cropper-image>'
     + '<cropper-shade hidden></cropper-shade>'
     + '<cropper-handle action="select" plain></cropper-handle>'
-    + '<cropper-selection initial-coverage="0.5" linked movable resizable zoomable>'
+    + '<cropper-selection initial-coverage="0.5" movable resizable zoomable>'
       + '<cropper-grid role="grid" bordered covered></cropper-grid>'
       + '<cropper-crosshair centered></cropper-crosshair>'
       + '<cropper-handle action="move" theme-color="rgba(255, 255, 255, 0.35)"></cropper-handle>'

packages/element-image/src/index.ts

@@ -233,7 +233,7 @@ export default class CropperImage extends CropperElement {
               $selection = $canvas.querySelector(`${this.$getTagNameOf(CROPPER_SELECTION)}[active]`);
             }
 
-            if (!$selection || $selection.hidden || !$selection.movable || $selection.linked
+            if (!$selection || $selection.hidden || !$selection.movable || $selection.dynamic
               || !(this.$actionStartTarget && $selection.contains(this.$actionStartTarget as Node))
             ) {
               this.$move(detail.endX - detail.startX, detail.endY - detail.startY);
@@ -264,7 +264,7 @@ export default class CropperImage extends CropperElement {
                 this.$getTagNameOf(CROPPER_SELECTION),
               );
 
-              if (!$selection || $selection.linked) {
+              if (!$selection || $selection.dynamic) {
                 const { x, y } = this.getBoundingClientRect();
 
                 this.$zoom(

packages/element-selection/src/index.ts

@@ -83,6 +83,8 @@ export default class CropperSelection extends CropperElement {
 
   active = false;
 
+  dynamic = false;
+
   movable = false;
 
   resizable = false;
@@ -97,8 +99,6 @@ export default class CropperSelection extends CropperElement {
 
   precise = false;
 
-  linked = false;
-
   protected set $canvas(element: CropperCanvas) {
     canvasCache.set(this, element);
   }
@@ -111,11 +111,11 @@ export default class CropperSelection extends CropperElement {
     return super.observedAttributes.concat([
       'active',
       'aspect-ratio',
+      'dynamic',
       'height',
       'initial-aspect-ratio',
       'initial-coverage',
       'keyboard',
-      'linked',
       'movable',
       'multiple',
       'outlined',
@@ -435,7 +435,7 @@ export default class CropperSelection extends CropperElement {
 
         case ACTION_MOVE:
           if (this.movable && (
-            this.linked
+            this.dynamic
             || (this.$actionStartTarget && this.contains(this.$actionStartTarget as Node))
           )) {
             this.$move(moveX, moveY);
@@ -444,7 +444,7 @@ export default class CropperSelection extends CropperElement {
 
         case ACTION_SCALE:
           if (relatedEvent && this.zoomable && (
-            this.linked
+            this.dynamic
             || this.contains(relatedEvent.target as Node)
           )) {
             const offset = getOffset(currentTarget as Element);