参考 selenium 的`ActionChains`，本库也提供了自己的`ActionChains`。

动作链可以完成一系列交互行为，如鼠标移动、鼠标点击、键盘输入等。

语法比 selenium 更简洁易用，每个动作执行即生效，无须`perform()`。

多个动作可以用链式模式操作：

```python
ac.move_to(ele).click().type('some text')
```

也可以多个操作分开执行：

```python
ac.move_to(ele)
ac.click()
ac.type('some text')
```

这两种方式效果是一样的，每个动作总会依次执行。

# ✔ 创建对象

## 📍 导入

```python
from DrissionPage import ActionChains
```

## 📍 `ActionChains`

创建动作链对象非常简单，只要把`WebPage`对象或`ChromiumPage`对象传入即可。动作链只在这个页面上生效。

**◽ 参数：**

| 名称     | 类型                           | 默认  | 说明           |
| ------ | ---------------------------- | --- | ------------ |
| `page` | `WebPage`对象或`ChromiumPage`对象 | 无   | 动作链要操作的浏览器页面 |

**◽ 示例：**

```python
from DrissionPage import WebPage, ActionChains

page = WebPage()
ac = ActionChains(page)
```

# ✔ 移动鼠标

## 📍 `move_to()`

此方法用于移动鼠标到元素中点，或页面上的某个绝对坐标。可设置偏移量，当带偏移量时，偏移量相对于元素左上角坐标。

**◽ 参数：**

| 名称           | 类型                                        | 默认  | 说明                                      |
| ------------ | ----------------------------------------- | --- | --------------------------------------- |
| `ele_or_loc` | `ChrmoiumElement`、`str`、`Tuple[int, int]` | 无   | 元素对象、文本定位符或绝对坐标，坐标为`tuple`(int, int) 形式 |
| `offset_x`   | `int`                                     | 0   | x 轴偏移量，向右为正，向左为负                        |
| `offset_y`   | `int`                                     | 0   | y 轴偏移量，向下为正，向上为负                        |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

**◽ 示例：**

```python
ele = page('tag:a')
ac.move_to(ele_or_loc=ele)  # 使鼠标移动过到 ele 元素上
```

## 📍 `move()`

此方法用于使鼠标相对当前位置移动若干距离。

**◽ 参数：**

| 名称         | 类型    | 默认  | 说明               |
| ---------- | ----- | --- | ---------------- |
| `offset_x` | `int` | 0   | x 轴偏移量，向右为正，向左为负 |
| `offset_y` | `int` | 0   | y 轴偏移量，向下为正，向上为负 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

**◽ 示例：**

```python
ac.move(300, 0)  # 鼠标向右移动 300 像素
```

## 📍 `up()`

此方法用于使鼠标相对当前位置向上移动若干距离。

**◽ 参数：**

| 名称      | 类型    | 默认  | 说明       |
| ------- | ----- | --- | -------- |
| `pixel` | `int` | 无   | 鼠标移动的像素值 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

**◽ 示例：**

```python
ac.up(50)  # 鼠标向上移动 50 像素
```

## 📍 `down()`

此方法用于使鼠标相对当前位置向下移动若干距离。

**◽ 参数：**

| 名称      | 类型    | 默认  | 说明       |
| ------- | ----- | --- | -------- |
| `pixel` | `int` | 无   | 鼠标移动的像素值 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `left()`

此方法用于使鼠标相对当前位置向左移动若干距离。

**◽ 参数：**

| 名称      | 类型    | 默认  | 说明       |
| ------- | ----- | --- | -------- |
| `pixel` | `int` | 无   | 鼠标移动的像素值 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `right()`

此方法用于使鼠标相对当前位置向右移动若干距离。

**◽ 参数：**

| 名称      | 类型    | 默认  | 说明       |
| ------- | ----- | --- | -------- |
| `pixel` | `int` | 无   | 鼠标移动的像素值 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

# ✔ 鼠标按键

## 📍 `click()`

此方法用于单击鼠标左键，单击前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要点击的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `r_click()`

此方法用于单击鼠标右键，单击前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要点击的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `m_click()`

此方法用于单击鼠标中键，单击前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要点击的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `hold()`

此方法用于按住鼠标左键不放，按住前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要按住的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `release()`

此方法用于释放鼠标左键，释放前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要释放的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `r_hold()`

此方法用于按住鼠标右键不放，按住前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要按住的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `r_release()`

此方法用于释放鼠标右键，释放前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要释放的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `m_hold()`

此方法用于按住鼠标中键不放，按住前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要按住的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `m_release()`

此方法用于释放鼠标中键，释放前可先移动到元素上。

**◽ 参数：**

| 名称       | 类型                      | 默认     | 说明             |
| -------- | ----------------------- | ------ | -------------- |
| `on_ele` | `ChromiumElement`、`str` | `None` | 要释放的元素对象或文本定位符 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

# ✔ 滚动滚轮

## 📍 `scroll()`

此方法用于滚动鼠标滚轮，滚动前可先移动到元素上。

**◽ 参数：**

| 名称        | 类型                      | 默认     | 说明                  |
| --------- | ----------------------- | ------ | ------------------- |
| `delta_x` | `int`                   | 0      | 滚轮 x 轴变化值，向右为正，向左为负 |
| `delta_y` | `str`                   | 0      | 滚轮 y 轴变化值，向下为正，向上为负 |
| `on_ele`  | `ChromiumElement`、`str` | `None` | 要滚动的元素对象或文本定位符      |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

# ✔ 键盘按键

## 📍 `key_down()`

此方法用于按下键盘按键，特殊字符见 Keys。

**◽ 参数：**

| 名称    | 类型    | 默认  | 说明   |
| ----- | ----- | --- | ---- |
| `key` | `str` | 无   | 按键键值 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

**◽ 示例：**

```python
from DrissionPage.keys import Keys

ac.key_down(Keys.CTRL)  # 按下 ctrl 键
```

## 📍 `key_up()`

此方法用于提起键盘按键，特殊字符见 Keys。

**◽ 参数：**

| 名称    | 类型    | 默认  | 说明   |
| ----- | ----- | --- | ---- |
| `key` | `str` | 无   | 按键键值 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

## 📍 `type()`

此方法用于输入一段文本。

**◽ 参数：**

| 名称     | 类型    | 默认  | 说明     |
| ------ | ----- | --- | ------ |
| `text` | `str` | 无   | 要输入的文本 |

**◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

# ✔ 等待

## 📍 `wait()`

此方法用于在动作链中插入停顿。

**◽ 参数：**

| 名称       | 类型      | 默认  | 说明   |
| -------- | ------- | --- | ---- |
| `second` | `float` | 无   | 等待秒数 |

 **◽ 返回：**

| 类型             | 说明      |
| -------------- | ------- |
| `ActionChains` | 动作链对象本身 |

**◽ 示例：**

```python
ac.wait(3)  # 停顿 3 秒
```

# ✔ 示例

## 📍 模拟输入 ctrl+a

```python
from DrissionPage import ChromiumPage, ActionChains
from DrissionPage.keys import Keys

# 创建页面
page = ChromiumPage()
# 创建动作链对象
ac = ActionChains(page)

# 鼠标移动到<input>元素上
ac.move_to('tag:input')
# 点击鼠标，使光标落到元素中
ac.click()
# 按下 ctrl 键
ac.key_down(Keys.CTRL)
# 输入 a
ac.type('a')
# 提起 ctrl 键
ac.key_up(Keys.CTRL)
```

## 📍 拖拽元素

```python
from DrissionPage import ChromiumPage, ActionChains
from DrissionPage.keys import Keys

# 创建页面
page = ChromiumPage()
# 创建动作链对象
ac = ActionChains(page)

# 左键按住元素
ac.hold('#div1')
# 向右移动鼠标300像素
ac.right(300)
# 释放左键
ac.release()
```