feat: Add target parameter to Scroll action for Win32 controller (#1082)

Copilot · MistEO · web-flow · commit 96f5e3e885c6 · 2026-01-20T22:52:18.000+08:00
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: MistEO &lt;18511905+MistEO@users.noreply.github.com&gt;
diff --git a/docs/en_us/3.1-PipelineProtocol.md b/docs/en_us/3.1-PipelineProtocol.md
@@ -977,6 +977,16 @@ Mouse wheel scroll.
 
 Additional properties for this action:
 
+- `target`: *true* | *string* | *array<int, 2>* | *array<int, 4>*  
+    Position of the scroll target. The mouse will first move to this position before scrolling. Optional, default is `true`.  
+  - *true*: Target is the position just recognized in this node (i.e., itself).  
+  - *string*: Fill in a node name; the target is the position recognized by a previously executed node.  
+  - *array<int, 2>*: Fixed coordinate point `[x, y]`.  
+  - *array<int, 4>*: Fixed coordinate area `[x, y, w, h]`, a random point will be selected within the rectangle (with higher probability towards the center and lower probability at the edges). Use [0, 0, 0, 0] for full screen.
+
+- `target_offset`: *array<int, 4>*  
+    Additional offset applied to `target` for the scroll position, each of the four values is added respectively. Optional, default is [0, 0, 0, 0].
+
 - `dx`: *int*  
     Horizontal scroll distance, positive values scroll right, negative values scroll left. Optional, default is 0.  
 
diff --git a/docs/zh_cn/3.1-任务流水线协议.md b/docs/zh_cn/3.1-任务流水线协议.md
@@ -985,6 +985,16 @@ Pipeline v2 时，将这些字段放到 `recognition.param` 中即可。
 
 该动作属性需额外部分字段：
 
+- `target`: *true* | *string* | *array<int, 2>* | *array<int, 4>*  
+    滚动目标的位置，鼠标会先移动到该位置再进行滚动。可选，默认 true 。  
+  - *true*: 目标为本节点中刚刚识别到的位置（即自身）。  
+  - *string*: 填写节点名，目标为之前执行过的某节点识别到的位置。  
+  - *array<int, 2>*: 固定坐标点 `[x, y]`。  
+  - *array<int, 4>*: 固定坐标区域 `[x, y, w, h]`，会在矩形内随机选取一点（越靠近中心概率越高，边缘概率相对较低），若希望全屏可设为 [0, 0, 0, 0] 。
+
+- `target_offset`: *array<int, 4>*  
+    在 `target` 的基础上额外移动再作为滚动目标，四个值分别相加。可选，默认 [0, 0, 0, 0] 。
+
 - `dx`: *int*  
     水平滚动距离，正值向右滚动，负值向左滚动。可选，默认 0 。  
 
diff --git a/source/MaaFramework/Controller/ControllerAgent.cpp b/source/MaaFramework/Controller/ControllerAgent.cpp
@@ -816,6 +816,12 @@ bool ControllerAgent::handle_scroll(const ScrollParam& param)
         return false;
     }
 
+    // Move to target position before scrolling
+    cv::Point point = preproc_touch_point(param.point);
+    if (!control_unit_->touch_move(0, point.x, point.y, 0)) {
+        LogWarn << "Failed to move to scroll position" << VAR(point);
+    }
+
     bool ret = control_unit_->scroll(param.dx, param.dy);
     return ret;
 }
diff --git a/source/MaaFramework/Controller/ControllerAgent.h b/source/MaaFramework/Controller/ControllerAgent.h
@@ -100,10 +100,11 @@ struct AppParam
 
 struct ScrollParam
 {
+    cv::Point point {};
     int dx = 0;
     int dy = 0;
 
-    MEO_TOJSON(dx, dy);
+    MEO_TOJSON(point, dx, dy);
 };
 
 struct ShellParam
diff --git a/source/MaaFramework/Resource/PipelineDumper.cpp b/source/MaaFramework/Resource/PipelineDumper.cpp
@@ -394,6 +394,8 @@ PipelineV2::JAction PipelineDumper::dump_act(Action::Type type, const Action::Pa
     case Action::Type::Scroll: {
         const auto& p = std::get<Action::ScrollParam>(param);
         act.param = PipelineV2::JScroll {
+            .target = dump_target(p.target),
+            .target_offset = dump_rect(p.target.offset),
             .dx = p.dx,
             .dy = p.dy,
         };
diff --git a/source/MaaFramework/Resource/PipelineParser.cpp b/source/MaaFramework/Resource/PipelineParser.cpp
@@ -1411,6 +1411,11 @@ bool PipelineParser::parse_app_info(const json::value& input, Action::AppParam&
 
 bool PipelineParser::parse_scroll(const json::value& input, Action::ScrollParam& output, const Action::ScrollParam& default_value)
 {
+    if (!parse_action_target(input, "target", output.target, default_value.target)) {
+        LogError << "failed to parse_action_target" << VAR(input);
+        return false;
+    }
+
     if (!get_and_check_value(input, "dx", output.dx, default_value.dx)) {
         LogError << "failed to get_and_check_value dx" << VAR(input);
         return false;
diff --git a/source/MaaFramework/Resource/PipelineTypes.h b/source/MaaFramework/Resource/PipelineTypes.h
@@ -216,6 +216,7 @@ struct AppParam
 
 struct ScrollParam
 {
+    Target target;
     int dx = 0;
     int dy = 0;
 };
diff --git a/source/MaaFramework/Resource/PipelineTypesV2.h b/source/MaaFramework/Resource/PipelineTypesV2.h
@@ -270,10 +270,12 @@ struct JStopTask
 
 struct JScroll
 {
+    JTarget target;
+    JRect target_offset {};
     int dx = 0;
     int dy = 0;
 
-    MEO_TOJSON(dx, dy);
+    MEO_TOJSON(target, target_offset, dx, dy);
 };
 
 struct JCommand
diff --git a/source/MaaFramework/Task/Component/Actuator.cpp b/source/MaaFramework/Task/Component/Actuator.cpp
@@ -115,7 +115,7 @@ ActionResult
         return stop_app(std::get<AppParam>(pipeline_data.action_param), pipeline_data.name);
 
     case Type::Scroll:
-        return scroll(std::get<ScrollParam>(pipeline_data.action_param), pipeline_data.name);
+        return scroll(std::get<ScrollParam>(pipeline_data.action_param), reco_hit, pipeline_data.name);
 
     case Type::StopTask:
         return stop_task(pipeline_data.name);
@@ -455,21 +455,22 @@ ActionResult Actuator::input_text(const MAA_RES_NS::Action::InputTextParam& para
     };
 }
 
-ActionResult Actuator::scroll(const MAA_RES_NS::Action::ScrollParam& param, const std::string& name)
+ActionResult Actuator::scroll(const MAA_RES_NS::Action::ScrollParam& param, const cv::Rect& box, const std::string& name)
 {
     if (!controller()) {
         LogError << "Controller is null";
         return {};
     }
 
-    MAA_CTRL_NS::ScrollParam ctrl_param { .dx = param.dx, .dy = param.dy };
+    cv::Point point = rand_point(get_target_rect(param.target, box));
+    MAA_CTRL_NS::ScrollParam ctrl_param { .point = point, .dx = param.dx, .dy = param.dy };
     bool ret = controller()->scroll(ctrl_param);
 
     return ActionResult {
         .action_id = action_id_,
         .name = name,
         .action = "Scroll",
-        .box = cv::Rect {},
+        .box = box,
         .success = ret,
         .detail = json::value(ctrl_param),
     };
diff --git a/source/MaaFramework/Task/Component/Actuator.h b/source/MaaFramework/Task/Component/Actuator.h
@@ -47,7 +47,7 @@ class Actuator : public NonCopyable
     ActionResult key_down(const MAA_RES_NS::Action::KeyParam& param, const std::string& name);
     ActionResult key_up(const MAA_RES_NS::Action::KeyParam& param, const std::string& name);
     ActionResult input_text(const MAA_RES_NS::Action::InputTextParam& param, const std::string& name);
-    ActionResult scroll(const MAA_RES_NS::Action::ScrollParam& param, const std::string& name);
+    ActionResult scroll(const MAA_RES_NS::Action::ScrollParam& param, const cv::Rect& box, const std::string& name);
     ActionResult shell(const MAA_RES_NS::Action::ShellParam& param, const std::string& name);
 
     ActionResult start_app(const MAA_RES_NS::Action::AppParam& param, const std::string& name);
diff --git a/source/binding/NodeJS/src/apis/pipeline.d.ts b/source/binding/NodeJS/src/apis/pipeline.d.ts
@@ -327,6 +327,8 @@ declare global {
         type ActionStopTask = {}
 
         type ActionScroll = {
+            target?: true | NodeName | Rect
+            target_offset?: Rect
             dx?: number
             dy?: number
         }
diff --git a/source/binding/Python/maa/pipeline.py b/source/binding/Python/maa/pipeline.py
@@ -253,6 +253,8 @@ class JStopTask:
 
 @dataclass
 class JScroll:
+    target: JTarget = True
+    target_offset: JRect = (0, 0, 0, 0)
     dx: int = 0
     dy: int = 0
 
diff --git a/test/python/pipeline_test.py b/test/python/pipeline_test.py
@@ -66,6 +66,7 @@
     JInputText,
     JStartApp,
     JStopApp,
+    JScroll,
     JCommand,
     JShell,
     JCustomAction,
@@ -693,6 +694,27 @@ def _test_action_types(self, context: Context):
         assert_eq(param.custom_action, "MyCustomAction", "custom_action")
         assert_eq(param.custom_action_param, {"data": 123}, "custom_action_param")
 
+        # Scroll
+        new_ctx.override_pipeline(
+            {
+                "ActScroll": {
+                    "action": "Scroll",
+                    "target": [100, 200, 50, 50],
+                    "target_offset": [10, 10, 0, 0],
+                    "dx": 0,
+                    "dy": -360,
+                }
+            }
+        )
+        obj = new_ctx.get_node_object("ActScroll")
+        assert_eq(obj.action.type, JActionType.Scroll, "Scroll type")
+        param = obj.action.param
+        assert_true(isinstance(param, JScroll), "Scroll param")
+        assert_eq(param.target, [100, 200, 50, 50], "target")
+        assert_eq(param.target_offset, [10, 10, 0, 0], "target_offset")
+        assert_eq(param.dx, 0, "dx")
+        assert_eq(param.dy, -360, "dy")
+
         print("    PASS: action types parsing")
 
     def _test_node_attributes(self, context: Context):
diff --git a/tools/pipeline.schema.json b/tools/pipeline.schema.json
@@ -2536,6 +2536,18 @@
         "Scroll": {
             "type": "object",
             "properties": {
+                "target": {
+                    "title": "Target Property",
+                    "description": "滚动目标的位置，鼠标会先移动到该位置再进行滚动。可选，默认 true 。",
+                    "$ref": "#/$defs/jsonTarget",
+                    "markdownDescription": "*true* | *string* | *array<int, 4>*\n\n滚动目标的位置，鼠标会先移动到该位置再进行滚动。可选，默认 true 。\n\n- *true*: 目标为本节点中刚刚识别到的位置（即自身）。\n\n- *string*: 填写节点名，目标为之前执行过的某节点识别到的位置。\n\n- *array<int, 4>*: 目标为固定坐标区域内随机一点，[x, y, w, h]，若希望全屏可设为 [0, 0, 0, 0] 。"
+                },
+                "target_offset": {
+                    "title": "Target Offset Property",
+                    "description": "在 `target` 的基础上额外移动再作为滚动目标，四个值分别相加。可选，默认 [0, 0, 0, 0] 。",
+                    "$ref": "#/$defs/jsonRect",
+                    "markdownDescription": "*array<int, 4>*\n\n在 `target` 的基础上额外移动再作为滚动目标，四个值分别相加。可选，默认 [0, 0, 0, 0] 。"
+                },
                 "dx": {
                     "title": "Scroll Dx Property",
                     "description": "水平滚动距离，正值向右滚动，负值向左滚动。可选，默认 0。建议使用 120 的整数倍（WHEEL_DELTA）。",

Original file line number	Diff line number	Diff line change
`@@ -816,6 +816,12 @@ bool ControllerAgent::handle_scroll(const ScrollParam& param)`
`816`	`816`	`return false;`
`817`	`817`	`}`
`818`	`818`
	`819`	`+ // Move to target position before scrolling`
	`820`	`+ cv::Point point = preproc_touch_point(param.point);`
	`821`	`+ if (!control_unit_->touch_move(0, point.x, point.y, 0)) {`
	`822`	`+ LogWarn << "Failed to move to scroll position" << VAR(point);`
	`823`	`+ }`
	`824`	`+`
`819`	`825`	`bool ret = control_unit_->scroll(param.dx, param.dy);`
`820`	`826`	`return ret;`
`821`	`827`	`}`
Original file line number	Diff line number	Diff line change
`@@ -216,6 +216,7 @@ struct AppParam`
`216`	`216`
`217`	`217`	`struct ScrollParam`
`218`	`218`	`{`
	`219`	`+ Target target;`
`219`	`220`	`int dx = 0;`
`220`	`221`	`int dy = 0;`
`221`	`222`	`};`