编辑器初学者中的裁剪

通过裁剪，用户可以选择在四个方向（左、右、上、下）剪掉项目的边缘。

🌐 With cropping, users can choose to cut off edges of an item in all 4 directions (left, right, top, bottom).

状态

🌐 State

裁剪功能已在 PR #415 中实现，并于 2025 年 11 月 27 日合并。

🌐 Cropping was implemented in PR #415, merged on November 27th, 2025.

它为项目引入了新的字段：

🌐 It introduces new fields for items:

• 可裁剪项目 有 cropLeft、cropRight、cropTop 和 cropBottom 字段。
• 全局状态 有一个新字段 itemSelectedForCrop，用于存储一个物品是否处于作物模式。

如果你有现有状态而没有这些字段，编辑器入门版应该能够优雅地处理它。如果你编写涉及此逻辑的代码，需要考虑你旧的持久化状态可能没有这些字段。

🌐 If you have existing state without these fields, the Editor Starter should handle it gracefully. If you write code that touches this logic, consider that your old persisted state may not have these fields.

功能开关

🌐 Feature Flag

可以通过将功能标志 FEATURE_CROPPING 设置为 false 来全局禁用裁剪。

🌐 Cropping can be globally disabled by setting the feature flag FEATURE_CROPPING to false.

支持裁剪的项目

🌐 Items supporting cropping

在默认项目类型中，图片、GIF 和视频支持裁剪。

🌐 Out of the default item types, images, GIFs and videos support cropping.

机械师

🌐 Mechanic

cropLeft、cropRight、cropTop 和 cropBottom 字段是比率，而 0 表示不裁剪，1 表示裁剪整个轴。

🌐 The cropLeft, cropRight, cropTop and cropBottom fields are ratios, whereas 0 means no crop and 1 means cropping the entire axis.

通过使用比例而不是像素，我们可以确保在结合调整大小和裁剪时不会丢失精度。

🌐 By using ratios instead of pixels, we can ensure that we don't lose precision when combining resizing and cropping.

在整个代码中，我们确保在裁剪的项目中每个轴至少保留 1 个像素。

🌐 Throughout the code, we ensure that at least 1 pixel remains in the cropped item for each axis.

我们还确保每个轴的两个裁剪值都小于1。
例如，不应该出现将 cropLeft 设置为 0.5 并将 cropRight 设置为 0.5 的情况，因为那样会什么都不剩。

🌐 We also ensure that the 2 crop values of each axis are less than 1.
For example, it should not be possible to have cropLeft set to 0.5 and cropRight set to 0.5, because nothing would remain.

作物种植方式

🌐 Ways of cropping

作物可以通过检查器中的滑块进行控制（功能标志：FEATURE_CROP_CONTROL）。 或者，可以通过激活裁剪模式在画布上进行裁剪。

🌐 Crop can be controlled in the inspector using sliders (feature flag: FEATURE_CROP_CONTROL).
Alternatively, cropping can be done on the canvas by activating Crop Mode.

裁剪模式

🌐 Crop Mode

通过在画布上双击一个可裁剪的项目，“裁剪模式”被激活，调整大小的控制点将被裁剪控制点替代。

🌐 By double-clicking an item that is croppable on the canvas, "Crop Mode" is activated, replacing resize handles with crop handles.

在任意一个八个控制点上，用户都可以拖动来调整裁剪数值。

🌐 On any of the 8 handles, the user can drag to control the crop values.

功能标志: FEATURE_DOUBLE_CLICK_TO_CROP

🌐 Feature flag: FEATURE_DOUBLE_CLICK_TO_CROP

裁剪背景

🌐 Crop Backgrounds

当启用裁剪模式时，完整的未裁剪项目会以降低的不透明度显示在背景中，以帮助用户可视化裁剪区域。项目的实际不透明度会暂时被覆盖为 1 以确保对比度。

🌐 When crop mode is activated, the full uncropped item is shown in the background with reduced opacity, to help the user visualize the cutout area. The actual opacity of the item is overridden to be 1 temporarily to ensure contrast.

功能标志: FEATURE_CROP_BACKGROUNDS

🌐 Feature flag: FEATURE_CROP_BACKGROUNDS

负作物值

🌐 Negative crop values

在裁剪模式下，用户还可以重新定位画布上的项目，从而影响剪切区域，因此也会影响裁剪数值。

🌐 In Crop Mode, the user can also reposition the item on the canvas, affecting the cutout area and therefore the crop values.

在拖动项目时允许负裁切更直观，这也是我们这么做的原因。这与 Figma 的行为一致。

🌐 It is more intuitive to also allow for negative crops while dragging the item, which is why we do so. This is aligned with Figma's behavior.

一旦用户通过点击项目外的任意位置退出裁剪模式，裁剪值将被限制为非负数。

🌐 Once the user exits crop mode by clicking anywhere outside of the item, the crop values are clamped to be non-negative.