@vvfx/sdk 0.2.2-alpha.0 → 0.2.2-alpha.2

package/dist/index.mjs

@@ -3,7 +3,7 @@
  * Description: TODO
  * Author: Ant Group CO., Ltd.
  * Contributors: 赤芍,何即,不择,意绮
- * Version: v0.2.2-alpha.0
+ * Version: v0.2.2-alpha.2
  */
 
 'use strict';
@@ -24032,9 +24032,21 @@ function getUniqueName(name, names) {
     };
     _create_class(TextItem, [
         {
-            key: "text",
+            key: "pixelWidth",
             get: // ==================== 便捷访问器 ====================
-            /**
+            function get() {
+                return this.width;
+            }
+        },
+        {
+            key: "pixelHeight",
+            get: function get() {
+                return this.height;
+            }
+        },
+        {
+            key: "text",
+            get: /**
    * @description 文本内容
    */ function get() {
                 return this.property.text;
@@ -56591,6 +56603,10 @@ var cursorMap = {
         type: 'preset',
         content: 'crosshair'
     },
+    'box-select': {
+        type: 'preset',
+        content: 'crosshair'
+    },
     'text-rotation': {
         type: 'svg',
         content: 'default',
@@ -60959,7 +60975,7 @@ var PageDataUtils = /*#__PURE__*/ function() {
    * @description 更新 PlayerItem 的 Property 属性
    */ _proto.updatePlayerItemPropertyAttribute = function updatePlayerItemPropertyAttribute(playerItem, targetItem, propertyName, propertyValue) {
         return _async_to_generator(function() {
-            var _this, _playerItem_getComponent, _playerItem_getComponent1, color, _array_, array, family, textComponent, textComponent1, lineCount, textHeight, _playerItem_getComponent2, textComponent2, textHeight1, textComponent3, outlineColor, textComponent4, textComponent5, textComponent6, originFontSize, lineCount1, textHeight2, textComponent7, textHeight3, viewSize, worldSizeX, originSize, originChildBoxes, originBox, worldScaleX, originScale, originWidth, currentWidth, ratio, originScale1, textComponent8, originChildBoxes1, originBox1, worldScaleY, originScale2, originHeight, currentHeight, ratio1, originScale3, viewSize1, worldSizeY, originSize1, textComponent9, textHeight4, _playerItem_getComponent3, _, _playerItem_getComponent4, _1, _propertyValue_compositions_find, _ref, subCompositionItem, compositionId, mainComposition, effectsSize, viewSize2, worldSize, compositionItem, component, videoComponent, videoComponent1, videoComponent2, pixelTranslation, viewTranslation, translation, rotation, currentScale, scaleRatio, frameComponent, _SDK_config_itemConfig_frameConfig, freeLayoutBackgroundColor, autoLayoutBackgroundColor, color1, childrenItem, time;
+            var _this, _playerItem_getComponent, _playerItem_getComponent1, color, _array_, array, family, textComponent, textComponent1, lineCount, textHeight, _playerItem_getComponent2, textComponent2, textHeight1, textComponent3, outlineColor, textComponent4, textComponent5, textComponent6, originFontSize, lineCount1, textHeight2, textComponent7, textHeight3, viewSize, worldSizeX, originSize, originChildBoxes, originBox, worldScaleX, originScale, originWidth, currentWidth, ratio, originScale1, textComponent8, originChildBoxes1, originBox1, worldScaleY, originScale2, originHeight, currentHeight, ratio1, originScale3, viewSize1, worldSizeY, originSize1, textComponent9, textHeight4, _playerItem_getComponent3, _, _playerItem_getComponent4, _1, _propertyValue_compositions_find, _ref, subCompositionItem, compositionId, mainComposition, effectsSize, viewSize2, worldSize, compositionItem, component, videoPlayStates, videoComponent, videoComponent1, videoComponent2, pixelTranslation, viewTranslation, translation, rotation, currentScale, scaleRatio, frameComponent, _SDK_config_itemConfig_frameConfig, freeLayoutBackgroundColor, autoLayoutBackgroundColor, color1, childrenItem, time, videoPlayStates1;
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -61447,7 +61463,10 @@ var PageDataUtils = /*#__PURE__*/ function() {
                         compositionItem.parentId = playerItem.getInstanceId();
                         component = compositionItem.components[0];
                         component == null ? void 0 : component.pause();
+                        // 刷新前快照视频播放态，刷新后恢复，避免更换特效导致全量视频被自动播放
+                        videoPlayStates = this.snapshotVideoPlayStates();
                         this.sdk.player.gotoAndPlay(0);
+                        this.restoreVideoPlayStates(videoPlayStates);
                         _state.label = 28;
                     case 28:
                         return [
@@ -61597,11 +61616,14 @@ var PageDataUtils = /*#__PURE__*/ function() {
                             'size'
                         ].includes(propertyName)) {
                             time = this.sdk.pageData.time;
+                            // 刷新前快照视频播放态，刷新后恢复，避免设置属性导致全量视频被自动播放
+                            videoPlayStates1 = this.snapshotVideoPlayStates();
                             if (SDK.config.mode === 'editor') {
                                 this.player.gotoAndPlay(time);
                             } else {
                                 this.player.gotoAndStop(time);
                             }
+                            this.restoreVideoPlayStates(videoPlayStates1);
                         }
                         return [
                             2
@@ -64579,7 +64601,7 @@ var PageDataUtils = /*#__PURE__*/ function() {
                         };
                         addTextItemIntoNewScene = function addTextItemIntoNewScene(textCreateInfo, sceneSize, itemViewPosition) {
                             var _scene_fonts;
-                            var _textCreateInfo_id = textCreateInfo.id, id = _textCreateInfo_id === void 0 ? EFFECTS.generateGUID() : _textCreateInfo_id, _textCreateInfo_name = textCreateInfo.name, name = _textCreateInfo_name === void 0 ? '文本' : _textCreateInfo_name, _textCreateInfo_property = textCreateInfo.property, lineHeight = _textCreateInfo_property.lineHeight, textWidth = _textCreateInfo_property.width, tmp = _textCreateInfo_property.height, textHeight = tmp === void 0 ? lineHeight : tmp, fontFamily = _textCreateInfo_property.fontFamily, fontSize = _textCreateInfo_property.fontSize, _textCreateInfo_property_fontWeight = _textCreateInfo_property.fontWeight, fontWeight = _textCreateInfo_property_fontWeight === void 0 ? EFFECTS.spec.TextWeight.normal : _textCreateInfo_property_fontWeight, _textCreateInfo_property_fontStyle = _textCreateInfo_property.fontStyle, fontStyle = _textCreateInfo_property_fontStyle === void 0 ? EFFECTS.spec.FontStyle.normal : _textCreateInfo_property_fontStyle, _textCreateInfo_property_textAlign = _textCreateInfo_property.textAlign, textAlign = _textCreateInfo_property_textAlign === void 0 ? EFFECTS.spec.TextAlignment.left : _textCreateInfo_property_textAlign, text = _textCreateInfo_property.text, textColor = _textCreateInfo_property.color, tmp1 = _textCreateInfo_property.rotation, sourceRotation = tmp1 === void 0 ? 0 : tmp1, url = _textCreateInfo_property.fontUrl, outlineColor = _textCreateInfo_property.outlineColor, outlineWidth = _textCreateInfo_property.outlineWidth, outlineEnabled = _textCreateInfo_property.outlineEnabled;
+                            var _textCreateInfo_id = textCreateInfo.id, id = _textCreateInfo_id === void 0 ? EFFECTS.generateGUID() : _textCreateInfo_id, _textCreateInfo_name = textCreateInfo.name, name = _textCreateInfo_name === void 0 ? '文本' : _textCreateInfo_name, _textCreateInfo_property = textCreateInfo.property, lineHeight = _textCreateInfo_property.lineHeight, textWidth = _textCreateInfo_property.width, tmp = _textCreateInfo_property.height, textHeight = tmp === void 0 ? lineHeight : tmp, fontFamily = _textCreateInfo_property.fontFamily, fontSize = _textCreateInfo_property.fontSize, _textCreateInfo_property_fontWeight = _textCreateInfo_property.fontWeight, fontWeight = _textCreateInfo_property_fontWeight === void 0 ? EFFECTS.spec.TextWeight.normal : _textCreateInfo_property_fontWeight, _textCreateInfo_property_fontStyle = _textCreateInfo_property.fontStyle, fontStyle = _textCreateInfo_property_fontStyle === void 0 ? EFFECTS.spec.FontStyle.normal : _textCreateInfo_property_fontStyle, _textCreateInfo_property_textAlign = _textCreateInfo_property.textAlign, textAlign = _textCreateInfo_property_textAlign === void 0 ? EFFECTS.spec.TextAlignment.left : _textCreateInfo_property_textAlign, text = _textCreateInfo_property.text, textColor = _textCreateInfo_property.color, tmp1 = _textCreateInfo_property.rotation, sourceRotation = tmp1 === void 0 ? 0 : tmp1, url = _textCreateInfo_property.fontUrl, outlineColor = _textCreateInfo_property.outlineColor, outlineWidth = _textCreateInfo_property.outlineWidth, outlineEnabled = _textCreateInfo_property.outlineEnabled, letterSpacing = _textCreateInfo_property.letterSpacing;
                             var rotation = Array.isArray(sourceRotation) ? [].concat(sourceRotation) : [
                                 0,
                                 0,
@@ -64609,7 +64631,7 @@ var PageDataUtils = /*#__PURE__*/ function() {
                                 fontSize: fontSize,
                                 textColor: resutlTextColor,
                                 fontWeight: fontWeight,
-                                letterSpace: 0,
+                                letterSpace: letterSpacing,
                                 textAlign: textAlign,
                                 fontStyle: fontStyle,
                                 textWidth: textWidth,
@@ -65616,6 +65638,51 @@ var PageDataUtils = /*#__PURE__*/ function() {
         var result = box.clone().scale(scale, center).translate(translation);
         return result;
     };
+    /**
+   * @description 快照当前所有视频元素的播放状态（播放/暂停 + 当前播放进度），用于属性刷新后恢复，
+   *  避免设置属性导致全量视频被自动播放或进度被重置回 0s
+   */ _proto.snapshotVideoPlayStates = function snapshotVideoPlayStates() {
+        var states = new Map();
+        var composition = this.getCurrentComposition();
+        for(var _iterator = _create_for_of_iterator_helper_loose(composition.items), _step; !(_step = _iterator()).done;){
+            var item = _step.value;
+            if (item.type === EFFECTS.spec.ItemType.video) {
+                var videoComponent = item.getComponent(VideoComponent);
+                if (!videoComponent) {
+                    continue;
+                }
+                //@ts-expect-error @赤芍 played 字段未在类型中声明，参见 rebuildCompositionItems 处用法
+                var played = !!videoComponent.played;
+                var time = videoComponent.getCurrentTime();
+                states.set(item.getInstanceId(), {
+                    played: played,
+                    time: time
+                });
+            }
+        }
+        return states;
+    };
+    /**
+   * @description 按快照恢复视频元素的播放状态（先 pause 再 seek，最后按原状态 play/pause，避免进度抖动）
+   */ _proto.restoreVideoPlayStates = function restoreVideoPlayStates(states) {
+        for(var _iterator = _create_for_of_iterator_helper_loose(states), _step; !(_step = _iterator()).done;){
+            var _step_value = _step.value, id = _step_value[0], _step_value_ = _step_value[1], played = _step_value_.played, time = _step_value_.time;
+            var playerItem = this.getPlayerItemById(id);
+            if ((playerItem == null ? void 0 : playerItem.type) !== EFFECTS.spec.ItemType.video) {
+                continue;
+            }
+            var videoComponent = playerItem.getComponent(VideoComponent);
+            if (!videoComponent) {
+                continue;
+            }
+            // 先暂停再 seek，避免播放状态下 seek 导致画面抖动
+            videoComponent.pauseVideo();
+            videoComponent.setCurrentTime(time);
+            if (played) {
+                videoComponent.playVideo();
+            }
+        }
+    };
     _proto.playVideoItem = function playVideoItem(id) {
         var playerItem = this.getPlayerItemById(id);
         if ((playerItem == null ? void 0 : playerItem.type) !== EFFECTS.spec.ItemType.video) {
@@ -67181,7 +67248,7 @@ var PageDataUtils = /*#__PURE__*/ function() {
     };
     _proto.autoLayoutPage = function autoLayoutPage() {
         return _async_to_generator(function(param) {
-            var _this, pageData, _param_mode, mode, ids, _param_focus, focus, _param_gap, gap, isPartialLayout, targetItems, layoutElements, moveInfos, anchor, _iterator, _step, moveInfo, sdkItem;
+            var _this, pageData, _param_mode, mode, ids, _param_focus, focus, _param_gap, gap, shift, isPartialLayout, targetItems, layoutElements, moveInfos, anchor, _iterator, _step, moveInfo, sdkItem;
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -67196,7 +67263,7 @@ var PageDataUtils = /*#__PURE__*/ function() {
                                 2
                             ];
                         }
-                        _param_mode = param.mode, mode = _param_mode === void 0 ? SDK.config.pageConfig.autoLayoutDefaultMode : _param_mode, ids = param.ids, _param_focus = param.focus, focus = _param_focus === void 0 ? true : _param_focus, _param_gap = param.gap, gap = _param_gap === void 0 ? SDK.config.pageConfig.autoLayoutDefaultGap : _param_gap;
+                        _param_mode = param.mode, mode = _param_mode === void 0 ? SDK.config.pageConfig.autoLayoutDefaultMode : _param_mode, ids = param.ids, _param_focus = param.focus, focus = _param_focus === void 0 ? true : _param_focus, _param_gap = param.gap, gap = _param_gap === void 0 ? SDK.config.pageConfig.autoLayoutDefaultGap : _param_gap, shift = param.shift;
                         isPartialLayout = !!(ids == null ? void 0 : ids.length);
                         // 1. 确定参与排布的顶层元素（过滤子元素）
                         targetItems = pageData.items.filter(function(item) {
@@ -67225,7 +67292,7 @@ var PageDataUtils = /*#__PURE__*/ function() {
                         // 4. 计算锚点偏移
                         // - 选中元素排布：以原始包围盒左上角为锚点
                         // - 全量排布：以视口中心为锚点
-                        anchor = isPartialLayout ? this.getPartialLayoutAnchor(layoutElements, moveInfos.boundingBox) : this.getGlobalLayoutAnchor(moveInfos.boundingBox);
+                        anchor = isPartialLayout ? this.getPartialLayoutAnchor(layoutElements, moveInfos.boundingBox) : this.getGlobalLayoutAnchor(moveInfos.boundingBox, shift);
                         _iterator = _create_for_of_iterator_helper_loose(moveInfos.items);
                         _state.label = 1;
                     case 1:
@@ -67268,7 +67335,7 @@ var PageDataUtils = /*#__PURE__*/ function() {
                         if (focus) {
                             this.setPageZoom(1, undefined, true);
                             this.setPageMove(new Vector2());
-                            this.viewportFit(undefined, moveInfos.boundingBox.translate(anchor));
+                            this.viewportFit(shift, moveInfos.boundingBox.translate(anchor));
                         }
                         return [
                             2
@@ -67292,8 +67359,9 @@ var PageDataUtils = /*#__PURE__*/ function() {
     /**
    * @description 计算全量排布的锚点偏移：以视口中心为锚点
    * @param layoutBoundingBox 排布算法输出的包围盒
-   */ _proto.getGlobalLayoutAnchor = function getGlobalLayoutAnchor(layoutBoundingBox) {
-        var viewCenter = new Vector2(this.sdk._container.offsetWidth / 2, this.sdk._container.offsetHeight / 2);
+   */ _proto.getGlobalLayoutAnchor = function getGlobalLayoutAnchor(layoutBoundingBox, shift) {
+        var _ref = shift != null ? shift : {}, _ref_top = _ref.top, top = _ref_top === void 0 ? 0 : _ref_top, _ref_bottom = _ref.bottom, bottom = _ref_bottom === void 0 ? 0 : _ref_bottom, _ref_left = _ref.left, left = _ref_left === void 0 ? 0 : _ref_left, _ref_right = _ref.right, right = _ref_right === void 0 ? 0 : _ref_right;
+        var viewCenter = new Vector2(this.sdk._container.offsetWidth / 2 + left - right, this.sdk._container.offsetHeight / 2 + top - bottom);
         var boundCenter = layoutBoundingBox.getCenter();
         return new Vector2(viewCenter.x - boundCenter.x, viewCenter.y - boundCenter.y);
     };
@@ -68895,6 +68963,8 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
    */ _this.maskSprite = null, _this._config = {}, _this.boxGraphics = new Graphics(), _this.type = 'mask', _this.mode = 'paint', /**
    * 蒙版工具独立的撤销重做实例
    */ _this._undoRedo = new GizmoUndoRedo(), /**
+   * 框选擦除进行中标记（按下到松开之间），用于实时选框描边的显示控制
+   */ _this._isBoxErasing = false, /**
    * 鼠标状态绘制结果
    */ _this.cursorResult = {
             type: 'normal',
@@ -68911,10 +68981,22 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
     var _proto = MaskGizmo.prototype;
     /**
    * 设置模式
-   * @param mode 模式类型：'paint' 表示涂抹，'erase' 表示擦除
+   * @param mode 模式类型：'paint' 笔刷涂抹、'erase' 笔刷逐笔擦除、'box-erase' 框选擦除、'box-paint' 框选涂抹
    */ _proto.setMode = function setMode(mode) {
         this.mode = mode;
     };
+    /**
+   * @description 判断点是否在包围盒内
+   */ _proto._isPointInBox = function _isPointInBox(p, box) {
+        return p.x >= box.min.x && p.x <= box.max.x && p.y >= box.min.y && p.y <= box.max.y;
+    };
+    /**
+   * @description 将屏幕坐标转换为包围盒内的归一化坐标 [0,1]（钳制在范围内）
+   */ _proto._toNormalized = function _toNormalized(p, box) {
+        var x = Math.max(0, Math.min(1, (p.x - box.min.x) / (box.max.x - box.min.x)));
+        var y = Math.max(0, Math.min(1, (p.y - box.min.y) / (box.max.y - box.min.y)));
+        return new Vector2(x, y);
+    };
     _proto.initialize = function initialize() {};
     _proto.preparationAction = function preparationAction(event) {
         if (!this.interactive) {
@@ -68933,6 +69015,26 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
         };
         // 更新鼠标位置
         this.result.point = new Vector2(event.offsetX, event.offsetY);
+        // 框选模式（框选擦除 / 框选涂抹）：仅在元素包围盒内按下才触发
+        if (this.mode === 'box-erase' || this.mode === 'box-paint') {
+            var box = this.result.box;
+            if (!box || !this._isPointInBox(this.result.point, box)) {
+                // 包围盒外按下：不触发框选，交由其它 gizmo
+                return undefined;
+            }
+            var start = this._toNormalized(this.result.point, box);
+            this.result.lines.push({
+                type: this.mode === 'box-paint' ? 'paint' : 'erase',
+                shape: 'rect',
+                brushSize: 0,
+                points: [
+                    start,
+                    start.clone()
+                ]
+            });
+            this._isBoxErasing = true;
+            return this.type;
+        }
         // 开启新画笔
         this.result.lines.push({
             type: this.mode,
@@ -68942,32 +69044,61 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
         return this.type;
     };
     _proto.action = function action(event) {
-        var // 记录鼠标划线位置
-        _this_result_lines_;
         if (!this.interactive || this.result.status === 'init') {
             return;
         }
         // 更新鼠标位置
         var box = this.result.box;
-        var point = new Vector2((event.offsetX - box.min.x) / (box.max.x - box.min.x), (event.offsetY - box.min.y) / (box.max.y - box.min.y));
-        (_this_result_lines_ = this.result.lines[this.result.lines.length - 1]) == null ? void 0 : _this_result_lines_.points.push(point);
+        var point = new Vector2(event.offsetX, event.offsetY);
+        this.result.point = point;
+        var lastLine = this.result.lines[this.result.lines.length - 1];
+        // 框选擦除：更新框选终点（钳制到包围盒内）
+        if ((lastLine == null ? void 0 : lastLine.shape) === 'rect') {
+            lastLine.points[1] = this._toNormalized(point, box);
+            return;
+        }
+        // 记录鼠标划线位置（笔刷模式）
+        var np = new Vector2((event.offsetX - box.min.x) / (box.max.x - box.min.x), (event.offsetY - box.min.y) / (box.max.y - box.min.y));
+        lastLine == null ? void 0 : lastLine.points.push(np);
     };
     _proto.endAction = function endAction() {
         if (!this.interactive) {
             return undefined;
         }
-        // 记录操作到 undoRedo（仅当画线有实际点时才记录）
         var lastLine = this.result.lines[this.result.lines.length - 1];
+        // 框选擦除：起点==终点视为空框选，移除；否则提交 undoRedo
+        if ((lastLine == null ? void 0 : lastLine.shape) === 'rect') {
+            this._isBoxErasing = false;
+            var _lastLine_points = lastLine.points, a = _lastLine_points[0], b = _lastLine_points[1];
+            var isEmpty = !!a && !!b && a.x === b.x && a.y === b.y;
+            if (this._oldLines && !isEmpty) {
+                var operation = {
+                    type: 'update',
+                    oldData: this._oldLines,
+                    newData: {
+                        lines: JSON.parse(JSON.stringify(this.result.lines))
+                    }
+                };
+                this._undoRedo.push(operation);
+                this._eventEmitter.emit('maskGizmoUndoRedoChange', operation);
+            } else {
+                // 空框选移除
+                this.result.lines.pop();
+            }
+            this._oldLines = undefined;
+            return this.type;
+        }
+        // 记录操作到 undoRedo（仅当画线有实际点时才记录）
         if (this._oldLines && lastLine && lastLine.points.length > 0) {
-            var operation = {
+            var operation1 = {
                 type: 'update',
                 oldData: this._oldLines,
                 newData: {
                     lines: JSON.parse(JSON.stringify(this.result.lines))
                 }
             };
-            this._undoRedo.push(operation);
-            this._eventEmitter.emit('maskGizmoUndoRedoChange', operation);
+            this._undoRedo.push(operation1);
+            this._eventEmitter.emit('maskGizmoUndoRedoChange', operation1);
         } else if ((lastLine == null ? void 0 : lastLine.points.length) === 0) {
             // 如果没有实际绘制点，移除空的线条
             this.result.lines.pop();
@@ -69092,6 +69223,17 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
         this.boxGraphics.lineStyle(boxLineWidth, boxLineColor, boxLineAlpha);
         this.boxGraphics.drawBox(box);
         this.boxGraphics.endFill();
+        // 框选擦除进行中：叠加当前拖动矩形的可视描边
+        var lastLine = this.result.lines[this.result.lines.length - 1];
+        if (this._isBoxErasing && (lastLine == null ? void 0 : lastLine.shape) === 'rect' && lastLine.points.length >= 2) {
+            var _lastLine_points = lastLine.points, a = _lastLine_points[0], b = _lastLine_points[1];
+            if (a && b) {
+                var selBox = new Box2(new Vector2(box.min.x + Math.min(a.x, b.x) * (box.max.x - box.min.x), box.min.y + Math.min(a.y, b.y) * (box.max.y - box.min.y)), new Vector2(box.min.x + Math.max(a.x, b.x) * (box.max.x - box.min.x), box.min.y + Math.max(a.y, b.y) * (box.max.y - box.min.y)));
+                this.boxGraphics.lineStyle(boxLineWidth, boxLineColor, boxLineAlpha);
+                this.boxGraphics.drawBox(selBox);
+                this.boxGraphics.endFill();
+            }
+        }
         // 1. 画线形（只用于遮罩，不直接显示
         for(var _iterator = _create_for_of_iterator_helper_loose(this.result.lines), _step; !(_step = _iterator()).done;){
             var line = _step.value;
@@ -69099,6 +69241,32 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
                 continue;
             }
             var lineGraphics = new Graphics();
+            // 矩形框选：填充矩形，paint 用 NORMAL 叠加，erase 用 DST_OUT 抠除
+            if (line.shape === 'rect') {
+                var a1 = line.points[0];
+                var b1 = line.points[1];
+                if (a1 && b1) {
+                    var w = box.max.x - box.min.x;
+                    var h = box.max.y - box.min.y;
+                    var x0 = Math.min(a1.x, b1.x) * w;
+                    var y0 = Math.min(a1.y, b1.y) * h;
+                    var x1 = Math.max(a1.x, b1.x) * w;
+                    var y1 = Math.max(a1.y, b1.y) * h;
+                    // 太小（纯点击）不渲染，避免 1px 擦除/涂抹点
+                    if (x1 - x0 > 0.5 || y1 - y0 > 0.5) {
+                        lineGraphics.beginFill(brushColor);
+                        lineGraphics.drawRect(x0, y0, x1 - x0, y1 - y0);
+                        lineGraphics.endFill();
+                        lineGraphics.blendMode = line.type === 'paint' ? BLEND_MODES.NORMAL : BLEND_MODES.DST_OUT;
+                        this._app.renderer.render(lineGraphics, {
+                            renderTexture: this.maskRenderTexture,
+                            clear: false
+                        });
+                    }
+                }
+                lineGraphics.destroy();
+                continue;
+            }
             lineGraphics.blendMode = line.type === 'paint' ? BLEND_MODES.NORMAL : BLEND_MODES.DST_OUT;
             lineGraphics.lineStyle({
                 width: line.brushSize * viewportParam.scale,
@@ -69142,14 +69310,24 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
         if (!point || !box) {
             return;
         }
-        if (point.x >= box.min.x && point.x <= box.max.x && point.y >= box.min.y && point.y <= box.max.y) {
-            var viewportParam = this._pageDataUtils.interactionUtils.viewportParam;
+        var inside = point.x >= box.min.x && point.x <= box.max.x && point.y >= box.min.y && point.y <= box.max.y;
+        if (!inside) {
+            return;
+        }
+        // 框选模式（框选擦除 / 框选涂抹）：crosshair
+        if (this.mode === 'box-erase' || this.mode === 'box-paint') {
             this.cursorResult = {
-                type: 'circle',
-                angle: 0,
-                radius: this.config.brushSize * viewportParam.scale / 2
+                type: 'box-select',
+                angle: 0
             };
+            return;
         }
+        var viewportParam = this._pageDataUtils.interactionUtils.viewportParam;
+        this.cursorResult = {
+            type: 'circle',
+            angle: 0,
+            radius: this.config.brushSize * viewportParam.scale / 2
+        };
     };
     _proto.close = function close() {
         this._config.maskImage = undefined;
@@ -69297,6 +69475,21 @@ var MaskGizmo = /*#__PURE__*/ function(Gizmo) {
             if (!line || line.points.length === 0) {
                 continue;
             }
+            // 矩形框选：填充矩形
+            if (line.shape === 'rect') {
+                var _line_points = line.points, a = _line_points[0], b1 = _line_points[1];
+                if (!a || !b1) {
+                    continue;
+                }
+                var x0 = Math.min(a.x, b1.x) * width;
+                var y0 = Math.min(a.y, b1.y) * height;
+                var x1 = Math.max(a.x, b1.x) * width;
+                var y1 = Math.max(a.y, b1.y) * height;
+                ctx.globalCompositeOperation = 'source-over';
+                ctx.fillStyle = line.type === 'paint' ? maskHexColor : maskBackgroundHexColor;
+                ctx.fillRect(x0, y0, Math.max(1, x1 - x0), Math.max(1, y1 - y0));
+                continue;
+            }
             ctx.lineWidth = line.brushSize * scale;
             ctx.lineCap = 'round';
             ctx.lineJoin = 'round';
@@ -71302,7 +71495,8 @@ var GestureHandler = /*#__PURE__*/ function() {
             'active-hand',
             'pointer',
             'text-create',
-            'frame-create'
+            'frame-create',
+            'box-select'
         ].includes(result.type)) {
             var cursor = cursorMap[result.type];
             if (cursor.type === 'svg') {
@@ -71474,6 +71668,7 @@ var GestureHandler = /*#__PURE__*/ function() {
             return;
         }
         this.maskGizmo.setMode(mode);
+        this.render();
     };
     _proto.openLoadingGizmo = function openLoadingGizmo(id, options) {
         var _this__emitter;
@@ -94768,7 +94963,7 @@ var SDK = /*#__PURE__*/ function() {
     };
     /**
    * @description 设置蒙版工具模式
-   * @param mode 模式类型：'paint' 表示涂抹，'erase' 表示擦除
+   * @param mode 模式类型：'paint' 笔刷涂抹、'erase' 笔刷逐笔擦除、'box-erase' 框选擦除、'box-paint' 框选涂抹
    */ _proto.setMaskGizmoMode = function setMaskGizmoMode(mode) {
         this._gestureHandler.setMaskGizmoMode(mode);
     };