首页  思维导图  详情

Python+Playwright

2025-02-27 17:50:33   0  举报





AI智能生成

Python+Playwright框架，实现UI自动化

UI自动化框架分析

UI自动化

作者其他创作

大纲/内容

locator操作方法大全

定位元素

CSS选择器

使用 CSS 选择器定位元素

例如，`page.locator('.my-class')` 会定位到页面上所有具有 "my-class" 类的元素

XPath 表达式

使用 XPath 表达式来定位元素

例如，`page.locator('//div[@id="my-id"]')` 会定位到页面上所有 id 为 "my-id" 的 div 元素

文本内容

使用 `:text("my text")` 来定位包含特定文本的元素

例如，`page.locator(':text("Hello, World!")')` 会定位到页面上所有包含 "Hello, World!" 文本的元素

特性选择器

使用 `[attr=value]` 来定位具有特定属性值的元素

例如，`page.locator('input[name="username"]')` 会定位到页面上所有 name 属性为 "username" 的 input 元素

ID 选择器

使用 `#id` 来定位具有特定 id 的元素

例如，`page.locator('#my-id')` 会定位到页面上 id 为 "my-id" 的元素

例如，`page.locator("div[id^=w-e-textarea-]")` 会定位到页面上 id 为 "my-id" 的元素

通过属性定位

通过属性定位元素

element = page.locator("[data-testid='submit-button']")

操作元素

等待元素

等待元素出现

# 等待元素出现
page.locator("button.submit-btn").wait_for()

等待元素消失

# 等待元素消失
page.locator("button.loading").wait_for(state="hidden")

点击元素

# 点击元素 page.locator("button.submit-btn").click()

双击元素

悬停在元素上

# 鼠标悬停 page.locator("button.hover-me").hover()

在输入框中输入文本

# 在输入框中输入文本 page.locator("input[name='username']").fill("myusername")

键盘输入

# 键盘输入
page.locator("input[name='username']").press("Enter")

元素信息获取

查找页面上所有匹配的元素

使用 locator.all() 方法

# 查找所有匹配的元素
elements = page.locator("button").all()

# 遍历所有匹配的元素
for element in elements:
print(element.text_content())

使用 locator.count() 方法

# 获取匹配元素的数量
count = page.locator("button").count()
print(f"Number of buttons: {count}")

获取所有匹配元素的内部文本

使用 locator.all_inner_texts() 方法

获取所有匹配元素的文本内容

使用 locator.all_text_contents() 方法

获取元素属性

使用locator.get_attribute()方法

# 获取元素的属性值
value = page.locator("input[name='username']").get_attribute("value")
print(value)

匹配同时满足多个条件的元素

使用and_ 方法

# 创建 Locator
container_locator = page.locator("div.form-container")
button_locator = page.locator("button:text('Submit')")

# 使用 and_ 组合条件
target_button = container_locator.and_(button_locator)

# 操作目标按钮
target_button.click()

获取匹配元素集合中的第n个元素

使用locator.nth(0)方法

#匹配第一个元素

使用locator.first方法

#等于locator.nth(0)，获取第一个元素

使用locator.last方法

#获取最后一个元素

检查元素状态

检查元素是否存在

使用locator.is_visible()方法

# 检查元素是否存在 is_visible = page.locator("button.submit-btn").is_visible() print(is_visible)

全部方法

---Methods---

- `all`: 返回所有匹配的元素。
- `all_inner_texts`: 返回所有匹配元素的内部文本。
- `all_text_contents`: 返回所有匹配元素的文本内容。
- `and_`: 创建一个新的 `Locator`，它匹配同时满足当前 `Locator` 和另一个条件的元素。
- `blur`: 让匹配的元素失去焦点。
- `bounding_box`: 返回匹配元素的边界框。
- `check`: 勾选匹配的元素（如果它是一个复选框或单选框）。
- `clear`: 清除匹配元素的输入值（如果它是一个输入元素）。
- `click`: 点击匹配的元素。
- `count`: 返回匹配元素的数量。
- `dblclick`: 双击匹配的元素。
- `dispatch_event`: 在匹配的元素上分发一个事件。
- `drag_to`: 将匹配的元素拖动到另一个位置。
- `evaluate`: 在匹配的元素上执行一个 JavaScript 函数。
- `evaluate_all`: 在所有匹配的元素上执行一个 JavaScript 函数。
- `evaluate_handle`: 获取一个可以在匹配的元素上执行 JavaScript 的句柄。
- `fill`: 填充匹配元素的输入值（如果它是一个输入元素）。
- `filter`: 创建一个新的 `Locator`，它匹配满足一个函数的元素。
- `focus`: 让匹配的元素获取焦点。
- `frame_locator`: 返回匹配元素的 `FrameLocator`（如果它是一个 `iframe` 元素）。
- `get_attribute`: 获取匹配元素的属性值。
- `get_by_alt_text`: 创建一个新的 `Locator`，它匹配 `alt` 属性包含指定文本的元素。
- `get_by_label`: 创建一个新的 `Locator`，它匹配 `label` 属性包含指定文本的元素。
- `get_by_placeholder`: 创建一个新的 `Locator`，它匹配 `placeholder` 属性包含指定文本的元素。
- `get_by_role`: 创建一个新的 `Locator`，它匹配 `role` 属性包含指定文本的元素。
- `get_by_test_id`: 创建一个新的 `Locator`，它匹配 `data-testid` 属性包含指定文本的元素。
- `get_by_text`: 创建一个新的 `Locator`，它匹配文本包含指定文本的元素。
- `get_by_title`: 创建一个新的 `Locator`，它匹配 `title` 属性包含指定文本的元素。
- `highlight`: 高亮匹配的元素。
- `hover`: 将鼠标悬停在匹配的元素上。
- `inner_html`: 获取匹配元素的内部 HTML。
- `inner_text`: 获取匹配元素的内部文本。
- `input_value`: 获取匹配元素的输入值（如果它是一个输入元素）。
- `is_checked`: 检查匹配的元素是否被勾选（如果它是一个复选框或单选框）。
- `is_disabled`: 检查匹配的元素是否被禁用。
- `is_editable`: 检查匹配的元素是否可编辑。
- `is_enabled`: 检查匹配的元素是否启用。
- `is_hidden`: 检查匹配的元素是否隐藏。
- `is_visible`: 检查匹配的元素是否可见。
- `locator`: 创建一个新的 `Locator`，它匹配满足一个定位器的元素。
- `nth`: 创建一个新的 `Locator`，它匹配第 n 个元素。
- `or_`: 创建一个新的 `Locator`，它匹配满足当前 `Locator` 或另一个条件的元素。
- `press`: 在匹配的元素上按下一个键（如果它是一个输入元素）。
- `press_sequentially`: 在匹配的元素上按下一系列的键（如果它是一个输入元素）。
- `screenshot`: 对匹配的元素进行截图。
- `scroll_into_view_if_needed`: 如果需要，将匹配的元素滚动到视图中。
- `select_option`: 选择匹配的元素的一个选项（如果它是一个 `select` 元素）。
- `select_text`: 选择匹配的元素的文本（如果它是一个输入元素或 `textarea` 元素）。
- `set_checked`: 设置匹配的元素的勾选状态（如果它是一个复选框或单选框）。
- `set_input_files`: 设置匹配的元素的输入文件（如果它是一个文件输入元素）。
- `tap`: 在匹配的元素上进行触摸操作。
- `text_content`: 获取匹配元素的文本内容。
- `uncheck`: 取消勾选匹配的元素（如果它是一个复选框或单选框）。
- `wait_for`: 等待匹配的元素满足一个条件。

---Properties---

- `first`: 返回第一个匹配的元素。
- `last`: 返回最后一个匹配的元素。
- `page`: 返回关联的 `Page` 对象。

这些方法和属性使 `Locator` 对象能够执行各种操作，包括查找元素、与元素交互、获取元素的信息等。

page.wait_for_selector()
等待某个元素可见/可用

page.wait_for_selector() 方法主要用于等待页面上的某个元素变得可用或可见。它会阻塞脚本执行，直到满足指定条件为止。

方法：page.wait_for_selector(selector, state=None, timeout=None)

例如：def delete_note(self):
self.add_note("新增要被删除的笔记", is_private=False)
time.sleep(1)
self.delete_note_btn.click()
self.pl_page.wait_for_selector(".el-message-box", timeout=5000)
self.sys_confirm_btn.click()

selector: CSS 选择器字符串，用于匹配页面上的元素。

state (可选):
指定元素的状态。可以是 'attached', 'detached', 'visible', 'hidden'。默认为 'visible'。

'attached': 等待元素被附加到文档树中。

'detached': 等待元素从文档树中被移除。

'visible': 等待元素变得可见。

'hidden': 等待元素变得不可见。

timeout (可选):
设置等待的最大时间（以毫秒为单位）。如果超时仍未达到指定状态，则会抛出一个超时异常。默认值为 30000 毫秒（30 秒）。

示例：
# 等待元素变得可见
page.wait_for_selector('#myElement', state='visible')

# 等待元素被附加到 DOM
page.wait_for_selector('#myElement', state='attached')

# 设置超时时间为 5 秒
page.wait_for_selector('#myElement', timeout=5000)

elements组件封装的类和方法

BaseElement
基础元素类

BaseElement 是基础元素类，封装了网页元素的通用操作和行为

参数：
required：标记该元素是否是必填项。
index：当页面中有多个相同元素时，指定选择第几个（默认第一个）。
father：父元素，可以是 Locator、Page 或其他 BaseElement 实例。
功能：
初始化元素的属性，如 _ele（元素本身）、_belong_to（所属实例）、pl_page（页面对象）等。
设置元素的超时时间 _to_be_xx_timeout，用于 expect 方法的超时检查。

wait_loading_disappear 方法

等待页面中的 loading 状态消失，最多等待 10 秒

元素操作方法

click：点击元素

#通过 click 方法，触发提交按钮的点击事件
submit_button = BaseElement(locator="button#submit")
submit_button.click()

fill：填充输入框

#通过 fill 方法，向输入框填充用户名 test_use
username_input = BaseElement(locator="input#username")
username_input.fill("test_user")

hover：鼠标悬停在元素上

#通过 hover 方法，将鼠标悬停在菜单上，触发子菜单的显示
menu = BaseElement(locator="div#menu")
menu.hover()

text：获取元素的文本内容

#相当于locator.inner_text().strip()，获取文本，并去空格
text_content = page.msg.text # 注意没有()
print(text_content)

is_clickable：检查元素是否可点击

#通过 is_clickable 方法，判断按钮是否可点击，避免在不可点击时执行点击操作
button = BaseElement(locator="button#submit")
if button.is_clickable():
button.click()
else:
print("按钮不可点击")

is_editable：检查元素是否可编辑

#通过 is_editable 方法，判断输入框是否允许输入内容
input_field = BaseElement(locator="input#username")
if input_field.is_editable():
input_field.fill("test_user")
else:
print("输入框不可编辑")

_locator_to_be_visible：检查元素是否可见

#通过 _locator_to_be_visible 方法，验证弹窗是否在页面上显示
popup = BaseElement(locator="div#popup")
if popup._locator_to_be_visible():
print("弹窗可见")
else:
print("弹窗不可见")

OtherElement
其他元素类

OtherElement 是 BaseElement 的子类，用于定位不在具体封装元素类型中的元素

参数：
name：元素的文本内容。
placeholder：元素的占位符。
locator：元素的定位器。
describe：元素的描述信息（必填）。
exact：是否精确匹配文本或占位符。
功能：
根据提供的 name、placeholder 或 locator 定位元素。
如果未提供 describe，则抛出异常。

通过 name 定位元素

#通过 name="username" 定位输入框，并填充内容 test_user
username_input = OtherElement(name="username", describe="用户名输入框")
username_input.fill("test_user")

通过 placeholder 定位元素

#通过 placeholder="请输入搜索内容" 定位搜索框，并输入关键词自动化测试
search_box = OtherElement(placeholder="请输入搜索内容", describe="全局搜索框")
search_box.fill("自动化测试")

通过 locator 定位元素

#通过 locator="button#submit" 定位按钮，并添加描述 "提交按钮"
submit_button = OtherElement(locator="button#submit", describe="提交按钮")
submit_button.click()

结合使用

结合 placeholder 和 is_editable 方法

#定位一个具有 placeholder 属性的输入框并检查是否可编辑
email_input = OtherElement(placeholder="请输入邮箱地址", describe="邮箱输入框")
if email_input.is_editable():
email_input.fill("test@example.com")
else:
print("输入框不可编辑")

结合 locator 和 hover 方法

#定位一个菜单项并悬停鼠标以显示子菜单
menu_item = OtherElement(locator="div#menu-item", describe="主菜单项")
menu_item.hover()

结合 name 和 _locator_to_be_visible 方法

#定位一个弹窗并检查是否可见
popup = OtherElement(name="popup", describe="确认弹窗")
if popup._locator_to_be_visible():
print("弹窗可见")
else:
print("弹窗不可见")

MessageElement
消息提示-元素类

MessageElement 是 BaseElement 的子类，用于处理页面中的消息提示元素

功能：继承 BaseElement 的初始化方法。

定位消息提示元素（通过 message_css 选择器），message_css = ".el-message__content"

使用示例

# 检查页面中的成功消息提示
# 假设页面中有一个成功消息提示，CSS 选择器为 ".success-message"
success_message = MessageElement(message_css=".success-message", describe="成功消息提示")

# 获取消息内容
message_text = success_message.__get__()
print(f"消息内容: {message_text}")

AreaElement
地区选择器（如省市区选择器）-功能类

AreaElement类是一个封装了地区选择器功能的类，继承自BaseElement。它用于处理网页中地区选择器的交互操作，支持通过name、placeholder或locator` 定位元素，并提供了选择地区和清除地区的方法。

参数：
name：元素的 name 属性。
placeholder：元素的 placeholder 属性。
locator：元素的定位器。
is_hover：是否需要

方法：
select（"北京市-北京市-东城区"/["北京市", "北京市", "东城区"）
clear()

通过 name 定位元素

#页面上有一个地区选择器，其 name 属性为 "area"
# 初始化地区选择器元素
area_selector = AreaElement(name="area", describe="地区选择器")

# 选择地区
area_selector.select("北京市-北京市-东城区")

# 清除已选择的地区
area_selector.clear()

通过 placeholder 定位元素

# 页面上有一个地区选择器，其 placeholder 属性为 "请选择地区
# 初始化地区选择器元素
area_selector = AreaElement(placeholder="请选择地区", describe="地区选择器")

# 选择地区
area_selector.select(["广东省", "广州市", "天河区"])

# 清除已选择的地区
area_selector.clear()

通过 locator 定位元素

# 页面上有一个地区选择器，其 CSS 选择器为 "input#area-selector"
# 初始化地区选择器元素
area_selector = AreaElement(locator="input#area-selector", describe="地区选择器", is_hover=True)

# 选择地区
area_selector.select("上海市-上海市-浦东新区")

# 清除已选择的地区
area_selector.clear()

方法 select

根据地区链选择地区

可以是字符串（如 "北京市-北京市-东城区"）或列表（如 ["北京市", "北京市", "东城区"]）

方法 clear

清除已选择的地区

# 初始化地区选择器元素 area_selector = AreaElement(locator="input#area-selector", describe="地区选择器", is_hover=True) # 选择地区 area_selector.select("北京市-北京市-东城区") # 清除已选择的地区 area_selector.clear()

结合使用

结合 locator 和 is_hover 方法

# 页面上有一个地区选择器，其 CSS 选择器为 "div.area-selector"，需要通过鼠标悬停展开下一级地区
# 初始化地区选择器元素
area_selector = AreaElement(locator="div.area-selector", describe="地区选择器", is_hover=True)

# 选择地区
area_selector.select("四川省-成都市-武侯区")

# 清除已选择的地区
area_selector.clear()

ButtonElement
按钮-元素类

ButtonElement类是一个封装了按钮元素的类，继承自BaseElement

参数： name：通过按钮的文本内容（text）定位。 placeholder：通过按钮的 placeholder 属性定位。 locator：通过按钮的 CSS 选择器或 XPath 定位。 describe：按钮的描述信息（必填），用于标识按钮的用途。 exact：布尔值，表示是否精确匹配文本内容（默认 True）。 **kwargs：其他参数，传递给父类 BaseElement。

通过 name 定位按钮

# 页面上有一个按钮，其文本内容为 "提交"
# 初始化按钮元素
submit_button = ButtonElement(name="提交", describe="提交按钮")

# 点击按钮
submit_button.click()

通过 placeholder 定位按钮

# 页面上有一个按钮，其 placeholder 属性为 "搜索"
# 初始化按钮元素
search_button = ButtonElement(placeholder="搜索", describe="搜索按钮")

# 点击按钮
search_button.click()

通过 locator 定位按钮

# 页面上有一个按钮，其 CSS 选择器为 "button#confirm"
# 初始化按钮元素
confirm_button = ButtonElement(locator="button#confirm", describe="确认按钮")

# 点击按钮
confirm_button.click()

结合 name 和 exact 参数

# 页面上有一个按钮，其文本内容为 "保存并继续"，需要使用模糊匹配定位
# 初始化按钮元素
save_button = ButtonElement(name="保存", exact=False, describe="保存按钮")

# 点击按钮
save_button.click()

CardElement
卡片（Card）-元素类

CardElement类是一个封装了页面中卡片（Card）元素操作的类，继承自BaseElement。它用于处理页面中分成若干个部分的卡片（如新增、编辑页面中的各个部分），支持通过name、locator` 或默认索引定位卡片元素

类属性 card_css 和 card_css1 类型：类属性（str）作用：定义卡片的 CSS 选择器，用于定位页面中的卡片元素。说明： card_css = ".yh-card"：适用于财税平台工程项目管理页面的卡片定位。 card_css1 = ".DetailCard"：适用于项目端页面的卡片定位。 card_title_css 和 card_title_css1 类型：类属性（str）作用：定义卡片标题的 CSS 选择器，用于定位卡片标题元素。说明： card_title_css = ".yh-title"：适用于财税平台工程项目管理页面的卡片标题定位。 card_title_css1 = ".cardTitle .left"：适用于项目端页面的卡片标题定位。

决定了这个封装的类，能不能用的上

参数：
name：通过卡片的名称（标题）定位。
locator：通过卡片的 CSS 选择器或 XPath 定位。
describe：卡片的描述信息（必填），用于标识卡片的用途。

通过 name 定位卡片

# 假设页面上有多个卡片，每个卡片都有一个标题（如 "项目信息"、"财务信息" 等），我们需要通过卡片的标题定位到具体的卡片元素
# 初始化 CardElement 实例，通过 name 定位卡片
project_info_card = CardElement(name="项目信息", describe="项目信息卡片")

# 对卡片进行操作，例如点击或获取内容
project_info_card.click() # 点击卡片
print(project_info_card.inner_text()) # 获取卡片的文本内容

通过 locator 定位卡片

# 假设我们有一个网页，其中包含多个卡片元素，每个卡片都有一个唯一的 locator（如 CSS 选择器或 XPath）。我们可以通过 locator 定位卡片并与之交互
# 初始化卡片元素
card = AreaElement(locator="div.card", describe="卡片元素")

# 点击卡片
card.click()

RadioElement
单选框的操作类

RadioElement 类，该类继承自 BaseElement，主要用于处理单选框（Radio Button）的交互操作

类属性
text_css：用于定位单选框文本的 CSS 选择器。
click_css：用于定位单选框点击区域的 CSS 选择器
text_css = ".el-radio__label"
click_css = ".el-radio__input"

决定了这个封装的类，能不能用的上

参数： name：单选框的名称，用于通过标签定位。 placeholder：单选框的占位符，用于通过占位符定位。 locator：单选框的定位器，用于直接定位。 describe：描述信息。 **kwargs：其他参数，传递给父类 BaseElement。

通过 name 定位元素

# 通过名称定位单选框
radio_by_name = RadioElement(name="名称")

通过 placeholder 定位元素

# 通过占位符定位单选框
radio_by_placeholder = RadioElement(placeholder="请选择名称")

通过 locator 定位元素

# 通过自定义定位器定位单选框 radio_by_locator = RadioElement(locator=".custom-radio")

方法：check

# 假设单选框的文本分别为 "Male"、"Female" 和 "Other"
# 通过名称定位单选框
radio_by_name = RadioElement(name="名称")
# 选择 "Male" 单选框
radio_by_name.check("Male")

# 通过占位符定位单选框
radio_by_placeholder = RadioElement(placeholder="请选择名称")
# 选择 "Female" 单选框
radio_by_placeholder.check("Female")

# 通过自定义定位器定位单选框
radio_by_locator = RadioElement(locator=".custom-radio")
# 选择 "Other" 单选框
radio_by_locator.check("Other")

CheckboxElement
复选框的操作类

该类继承自 RadioElement，主要用于处理复选框（Checkbox）的交互操作

类属性
text_css：用于定位单选框文本的 CSS 选择器。
click_css：用于定位单选框点击区域的 CSS 选择器
text_css = ".el-checkbox__label"
click_css = ".el-checkbox__input"

决定了这个封装的类，能不能用的上

参数：
name：单选框的名称，用于通过标签定位。
placeholder：单选框的占位符，用于通过占位符定位。
locator：单选框的定位器，用于直接定位。
describe：描述信息。

方法： check

1. check(self, value: Union[str, int, List[str], List[int]], uncheck=False)
功能：根据传入的值勾选或取消勾选复选框，支持单个或多个操作。
参数：
value：支持单个字符串（匹配文本）、数字（匹配序号）、字符串列表或数字列表（匹配多个）。
uncheck：默认为 False，表示勾选操作；为 True 时表示取消勾选操作。
返回值：返回 self._belong_to，可能是父对象或上下文对象。

# 假设复选框的文本分别为 "Option 1"、"Option 2" 和 "Option 3"
# 勾选 "Option 1"
checkbox_element.check("Option 1")

# 勾选序号为 1 的复选框（即 "Option 2"）
checkbox_element.check(1)

# 勾选多个复选框（通过文本）
checkbox_element.check(["Option 1", "Option 3"])

# 勾选多个复选框（通过序号）
checkbox_element.check([0, 2])

# 取消勾选 "Option 1"
checkbox_element.check("Option 1", uncheck=True)

# 取消勾选序号为 1 的复选框（即 "Option 2"）
checkbox_element.check(1, uncheck=True)

方法：uncheck

# 取消勾选指定的复选框。
# 取消勾选 "Option 1"
checkbox_element.uncheck("Option 1")

# 取消勾选序号为 1 的复选框（即 "Option 2"）
checkbox_element.uncheck(1)

# 取消勾选多个复选框（通过文本）
checkbox_element.uncheck(["Option 1", "Option 3"])

# 取消勾选多个复选框（通过序号）
checkbox_element.uncheck([0, 2])

方法： is_checked

# 判断指定的复选框是否处于选中状态
# 判断 "Option 1" 是否选中
is_checked = checkbox_element.is_checked("Option 1")
print(is_checked) # 输出 True 或 False

# 判断序号为 1 的复选框（即 "Option 2"）是否选中
is_checked = checkbox_element.is_checked(1)
print(is_checked) # 输出 True 或 False

DateElement
日期选择-操作类

DateElement类是用于处理日期选择器交互的类，继承自BaseElement`。它支持单个日期选择、日期范围选择，并提供了一系列方法来操作日期选择器

参数：
name：通过标签名称定位日期选择器。
placeholder：通过占位符定位日期选择器。
locator：通过自定义定位器（如 CSS 选择器或 XPath）定位日期选择器。
describe：描述信息。
has_foot：面板下方是否有“此刻”、“确定”等按钮。
aria_controls_id：日期选择器面板的 aria-controls 属性值。

类属性
panel_header_css = "#{id_} div.el-date-picker__header"
panel_range_header_cas = "#{id_} div.el-date-range-picker__header" # 查询区域两个日期选择器，头部css
prev_year_aria_label = "前一年" # get_by_label，也可以用于有aria-label属性的元素
prev_year_css = ".d-arrow-left"
prev_month_aria_label = "上个月"

next_year_aria_label = "后一年"
next_year_css = ".d-arrow-right"
next_month_aria_label = "下个月"

panel_content_css = "#{id_} table" # 里面是个日期表
content_days_css = "td" # 面板中呈现出来的所有日子单元格直接用td标签定位，因为判断日子是否置灰的属性在td的class里面

when_it_is_not_input_tag_css = ".el-form-item__label"
when_is_is_not_input_tag_target_css = ".el-date-editor--daterange"

通过 name 定位元素

date_element = DateElement(name="选择日期", has_foot=True)

方法： now

#如果面板下方有“此刻”按钮，则点击它。
date_element = DateElement(name="选择日期", has_foot=True)
date_element.now()

方法：confirm

# 如果面板下方有“此刻”按钮，则点击它。
date_element = DateElement(name="选择日期", has_foot=True)
date_element.now()
# 点击“确定”按钮
date_element.confirm()

方法：select

# 选择指定的日期或日期范围
date_element = DateElement(name="选择日期")
# 选择单个日期
date_element.select("2024-05-31")

# 选择日期范围
date_element.select(["2024-05-31", "2024-06-31"])

TimeElement
时间选择-操作类

处理时间选择器的交互操作，支持单个时间或时间范围的选择。

类属性：
time_css = ".el-date-editor" # 时间选择器的 CSS 选择器
panel_css = ".el-time-panel__content" # 时间选择器面板的 CSS 选择器
# 先考虑时、分，秒后续有场景再扩张
time_hour_minute_css = ".el-time-spinner__wrapper" # 时、分滑动区域都是一样的class，# 通过索引区分，时间选择器中小时和分钟滑动区域的 CSS 选择器

footer_cancel_css = ".cancel"
footer_confirm_css = ".confirm"

参数：
name：通过标签名称定位日期选择器。
placeholder：通过占位符定位日期选择器。
locator：通过自定义定位器（如 CSS 选择器或 XPath）定位日期选择器。
describe：描述信息。
is_single = True # 表示时间选择器是否是开始结束时间一起出现，True代表只有一个，默认True

方法：select

# 假设需要选择时间范围 ["08:00", "12:30"]
time_element = TimeElement(name="选择时间范围")
time_element.select(["08:00", "12:30"])
# 假设需要选择时间 "14:30:45"
time_element = TimeElement(name="选择时间")
time_element.select("14:30:45")
# 假设需要选择时间范围 ["08:00:00", "12:30:45"]
time_element = TimeElement(name="选择时间范围")
time_element.select(["08:00:00", "12:30:45"])

DateTimeElement
日期时间选择-操作类

结合 DateElement 和 TimeElement，处理日期时间选择器的交互操作

参数：
name：通过标签名称定位元素。
placeholder：通过占位符定位元素。
locator：通过自定义定位器（如 CSS 选择器或 XPath）定位元素。
describe：描述信息。

方法： now

# 假设页面中存在一个日期时间选择器，标签名称为 "会议时间"。
# 初始化 DateTimeElement 实例
datetime_element = DateTimeElement(name="会议时间")

# 调用 now 方法选择当前日期时间
datetime_element.now()

方法：select

选择单个日期时间

datetime_element = DateTimeElement(name="会议时间") # 选择 2024-05-31 14:30:45 datetime_element.select("2024-05-31 14:30:45")

选择日期时间范围

datetime_element = DateTimeElement(name="选择时间范围") # 选择范围 ["2024-05-31 08:00", "2024-06-01 18:30"] datetime_element.select(["2024-05-31 08:00", "2024-06-01 18:30"])

格式要求：字符串格式必须为 "YYYY-MM-DD HH:MM" 或 "YYYY-MM-DD HH:MM:SS"。列表/元组必须包含两个日期时间字符串。

DateMonthElement
月份选择-操作类

继承自 DateElement，专门处理月份选择器的交互操作

方法：与 DateElement 相同

DateYearElement
年份选择-操作类

继承自 DateElement，专门处理月份选择器的交互操作

方法：与 DateElement 相同

DialogElement
对话框（弹框）-操作类

继承自 BaseElement，用于操作页面中的对话框（弹窗）

方法： close

# 关闭当前弹窗
dialog = DialogElement(locator=".el-dialog")
dialog.close() # 关闭弹窗

DrawerElement
抽屉弹框-操作类

DrawerElement 类用于操作页面中的抽屉弹框（Drawer），支持通过名称或索引定位抽屉，并提供了一些关键方法来处理抽屉的显示和操作

类属性：
# drawer_css：用于定位抽屉弹框的 CSS 选择器
drawer_css = ".el-drawer.rtl.open"
# 用于定位抽屉标题的第一种 CSS 选择器
drawer_title_css_first = ".el-drawer__header"
# 用于定位抽屉标题的第二种 CSS 选择器
drawer_title_css_second = ".title-header"

参数： name：抽屉的标题名称（可选）。 describe：描述信息（可选）。

通过 name 定位元素

drawer = DrawerElement(name="用户信息", describe="用户信息抽屉")

确保 name 参数与抽屉标题完全匹配（区分大小写）

DropdownElement
下拉选择器-操作类

DropdownElement 类，继承自 BaseElement，用于操作页面中的下拉选择器（Dropdown），支持通过名称或自定义定位器来定位下拉选择器，并提供选择特定选项的方法。

类属性：
# css：用于定位下拉选择器的 CSS 选择器
css = ".el-dropdown"
# trigger_css：用于定位下拉选择器触发按钮的 CSS 选择器
trigger_css = ".el-tooltip__trigger"

方法： select

功能：选择下拉选择器中的特定选项。参数： value：要选择的选项文本。 exact：是否精确匹配选项文本（默认为 True）

# 精确匹配选项 dropdown.select("广东省") # 模糊匹配选项 dropdown.select("广东", exact=False)

# 假设页面有一个标题为“选择省份”的下拉选择器
# 初始化下拉选择器实例，通过名称定位
dropdown = DropdownElement(name="选择省份")

# 选择选项 "广东省"
dropdown.select("广东省")

# 假设页面有一个自定义定位器的下拉选择器
# 初始化下拉选择器实例，通过自定义定位器定位
dropdown = DropdownElement(locator=".custom-dropdown")

# 模糊匹配选项 "广东"
dropdown.select("广东", exact=False)

InputElement
输入（选择）框-操作类

InputElement 类，继承自 BaseElement，用于操作页面中的输入框（Input），支持通过名称、占位符或自定义定位器来定位输入框，并提供选择特定选项和清除输入的方法

方法： select

# 假设页面有一个名称为“用户名”的输入框，也带有实时搜索结果
# 初始化输入框实例，通过名称定位
input_element = InputElement(name="用户名")

# 选择选项 "张三"
input_element.select("张三")

方法： clear

# 假设页面有一个名称为“用户名”的输入框，需要清除其内容
# 初始化输入框实例，通过自定义定位器定位
input_element = InputElement(locator=".custom-input")

# 清除输入框内容
input_element.clear()

MapElement
地图-元素类

MapElement 类，继承自 BaseElement，用于操作页面中的地图元素，支持通过自定义定位器来定位地图，并提供多种操作方法，如移动地图、随机移动、绘制图形和右键点击

方法：move_map

功能：在地图范围内移动地图

参数： direction：移动方向，可选值为 "left", "right", "up", "down"（默认为 "left"）。 pix：每次移动的像素距离（默认为 100）。 times：移动次数（默认为 1）。

定位地图并移动

# 初始化地图实例，通过自定义定位器定位
map_element = MapElement(locator=".map-container")

# 向右移动地图 50 像素，重复 2 次
map_element.move_map(direction="right", pix=50, times=2)

方法：random_move_map

功能：在地图范围内随机移动

随机移动地图

# 初始化地图实例，通过自定义定位器定位
map_element = MapElement(locator=".map-container")

# 随机移动地图
map_element.random_move_map()

方法：draw

功能：在地图上绘制图形。
参数：
edges：图形的边数（默认为 4），支持 3 到 6 条边。

在地图上绘制图形

# 初始化地图实例，通过自定义定位器定位
map_element = MapElement(locator=".map-container")

# 绘制一个五边形
map_element.draw(edges=5)

方法：right_click

功能：在地图上右键点击鼠标。参数： x：相对于地图中心的 x 偏移量（可选）。 y：相对于地图中心的 y 偏移量（可选）。

在地图上右键点击

# 初始化地图实例，通过自定义定位器定位
map_element = MapElement(locator=".map-container")

# 在地图中心右侧 50 像素，下方 30 像素处右键点击
map_element.right_click(x=50, y=30)

OriginalElement
原生方法-定位元素类

OriginalElement 类，继承自 BaseElement，用于通过 Playwright 的原生方法定位页面中的元素，支持通过自定义的定位字符串来定位元素，并确保元素可见。

继承自 BaseElement 和 Locator，共享基础元素操作方法和定位器功能

通过 CSS 选择器定位元素

# 初始化元素实例，通过 CSS 选择器定位 original_element = OriginalElement(locator_str="pl_page.locator('.container .input')", describe="输入框") # 访问元素时自动触发定位 element = original_element

# 价格排序
price_sort_button = OriginalElement("""pl_page.locator(".video-changes .right").get_by_text("价格")""")

# 已学人数 video_study_amount = OriginalElement("""pl_page.locator(".item-content .item-study span").nth(0)""")

RadioElement
单选按钮-元素类

RadioElement ，继承自 BaseElement，类用于操作页面中的单选按钮（Radio Button），支持通过名称、占位符或自定义定位器来定位单选按钮组，并提供选择特定单选按钮的方法

类属性：
# text_css：用于定位单选按钮文本的 CSS 选择器
text_css = ".el-radio__label"
# click_css：用于定位单选按钮点击区域的 CSS 选择器
click_css = ".el-radio__input"

参数： name：单选按钮组的名称（可选）。 placeholder：单选按钮组的占位符（可选）。 locator：自定义定位器（可选）。 describe：描述信息（可选）

方法： check

功能：选择单选按钮组中的特定单选按钮。参数： value：需要选择的单选按钮的名称。

# 初始化单选按钮组实例，通过名称定位
radio_element = RadioElement(name="性别", describe="性别选择单选按钮组")

# 选择选项 "男"
radio_element.check("男")

SelectElement
下拉选择器-元素类

SelectElement 类，继承自 BaseElement，用于操作页面中的下拉选择器（Select），支持通过名称、占位符或自定义定位器来定位下拉选择器，并提供多种方法来选择选项、处理搜索树结构和清除选择

参数： name：下拉选择器的名称（可选）。 placeholder：下拉选择器的占位符（可选）。 locator：自定义定位器（可选）。 describe：描述信息（可选）。

方法： options_count

功能：获取下拉框选项个数

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

count = select_element.options_count()

方法： options

功能：获取下拉列表中的所有值

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

options = select_element.options()

方法： select_from_query

功能：针对下拉框是搜索树的情况，先填充搜索文本，再选择匹配的选项。
参数：
query：搜索文本

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

select_element.select_from_query("模式一")

方法： select

功能：选择下拉框中的特定选项。
参数：
value：支持单个字符串（选择文本匹配的）、数字（选择具体序号），字符串列表/数字列表（选择多个）。
auto_trigger：是否需要自动触发选项弹窗（默认为 True）

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

# 选择单个选项
select_element.select("模式一")

# 选择多个选项
select_element.select(["模式一", "模式二"])

方法： fill

功能：存在允许输入，然后树里面是实时搜索结果的场景。参数： value：搜索文本。 auto_select：是否自动选择搜索结果（默认为 True）

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

select_element.fill("模式一")

方法：select_tree

功能：针对下拉框是树形结构的场景。参数： tree_chain：树链，可以是字符串（如 "111-222-333"）或列表（如 ["111", "222", "333"]）。 from_：调用来源（默认为空字符串）

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

select_element.select_tree("111-222-333")

方法： click

功能：点击触发下拉选择器展开的元素。参数： timeout：超时时间（默认为 None）

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

select_element.click()

方法： clear

功能：清除下拉选择器中的选择

# 访问实例时自动触发下拉选择器定位
select_element = SelectElement(name="合同模式")

select_element.clear()

TableElement
列表/表格-元素类

TableElement类，继承自 BaseElement，用于操作页面中的表格元素，支持通过名称、占位符或自定义定位器来定位表格，并提供多种方法来操作表格中的数据

类属性：
# table_css：用于定位表格的 CSS 选择器
table_css = ".el-table__inner-wrapper"
# t_head_css：用于定位表格表头的 CSS 选择器
t_head_css = ".el-table__header"
# t_body_css：用于定位表格主体的 CSS 选择器
t_body_css = ".el-table__body"

参数： name：表格的名称（可选）。 placeholder：表格的占位符（可选）。 locator：自定义定位器（可选）。 describe：描述信息（可选）。

方法： row_num

功能：返回当前加载的行数

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 获取表格行数
row_count = table_element.row_num
print(f"表格行数: {row_count}")

方法： get_row_value

功能：获取指定行的数据。参数： row_index：行号（默认为 0）

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 获取第二行的数据
row_data = table_element.get_row_value(row_index=1)
print(f"第二行数据: {row_data}")

方法： get_value

功能：获取指定行指定列的值。参数： col_name：列名。 row_index：行号（默认为 0）

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 获取第二行“姓名”列的值
value = table_element.get_value(col_name="姓名", row_index=1)
print(f"第二行‘姓名’列的值: {value}")

方法： click_value

功能：点击指定行指定列的值。参数： col_name：列名。 row_index：行号（默认为 0）

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 点击第二行“姓名”列的值
table_element.click_value(col_name="姓名", row_index=1)

方法：click_cell

功能：点击指定行指定列的单元格。参数： col_name：列名。 row_index：行号（默认为 0

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 点击第二行“姓名”列的单元格
table_element.click_cell(col_name="姓名", row_index=1)

方法： click_operator

功能：点击指定行操作栏中的按钮。参数： operator_name：操作按钮名称。 row_index：行号（默认为 0）。 col_name：操作列的列名（默认为“操作”）

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 点击第二行“操作”列中的“编辑”按钮
table_element.click_operator(operator_name="编辑", row_index=1)

方法： get_row_index_by_text

功能：通过列名和文本获取行号。参数： col_name：列名。 text：需要匹配/包含的文本。 exact：是否完全匹配（默认为 True）。 all_index：是否返回所有符合条件的行号（默认为 False）

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 获取包含“张三”的行号
row_index = table_element.get_row_index_by_text(col_name="姓名", text="张三")
print(f"包含‘张三’的行号: {row_index}")

方法： have_text

功能：判断表格中是否存在特定文本。
参数：
text：需要匹配/包含的文本。
exact：是否完全匹配（默认为 True）
返回布尔值

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 判断表格中是否存在“张三”
exists = table_element.have_text(text="张三")
print(f"表格中是否存在‘张三’: {exists}")

方法： check_all

功能：通过勾选表头的 checkbox 勾选所有行

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 勾选所有行
table_element.check_all()

方法： check_row

功能：勾选指定行。参数： row_index：行号（默认为 0）

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 勾选第二行
table_element.check_row(row_index=1)

方法： is_row_checked

功能：判断指定行是否被勾选。
参数：
row_index：行号（默认为 0）
返回布尔值

# 访问实例时自动触发表格定位
table_element = TableElement(name="用户列表")

# 判断第二行是否被勾选
is_checked = table_element.is_row_checked(row_index=1)
print(f"第二行是否被勾选: {is_checked}")

EditTableElement
在线表格-元素类

EditTableElement 类继承自 TableElement，专门用于操作可编辑的表格。它提供了对单元格内各种元素（如下拉框、输入框、开关和上传文件等）进行编辑的方法

继承自 TableElement，共享 TableElement 的所有功能，并提供额外的编辑方法

方法： cell_select

功能：选择单元格中的下拉框选项。参数： col_name：列名。 value：需要选择的选项值（支持单个字符串、数字、字符串列表、数字列表）。 row_index：行号（默认为 0）

# 初始化可编辑表格实例，通过名称定位
edit_table_element = EditTableElement(name="用户列表")

# 选择第二行“状态”列中的“启用”选项
edit_table_element.cell_select(col_name="状态", value="启用", row_index=1)

方法： cell_fill

功能：填写单元格中的输入框或文本区域。参数： col_name：列名。 value：需要填入的值。 row_index：行号（默认为 0）

# 初始化可编辑表格实例，通过名称定位
edit_table_element = EditTableElement(name="用户列表")

# 填写第二行“备注”列中的内容
edit_table_element.cell_fill(col_name="备注", value="测试备注", row_index=1)

方法： click_cell_switch

功能：点击单元格中的开关。参数： col_name：列名。 row_index：行号（默认为 0）

# 初始化可编辑表格实例，通过名称定位 edit_table_element = EditTableElement(name="用户列表") # 点击第二行“启用”列中的开关 edit_table_element.click_cell_switch(col_name="启用", row_index=1)

方法： cell_upload_files

功能：上传文件到单元格中的上传元素。参数： col_name：列名。 file_path：文件路径（支持单个文件路径或文件路径列表）。 row_index：行号（默认为 0）

# 初始化可编辑表格实例，通过名称定位 edit_table_element = EditTableElement(name="用户列表") # 上传文件到第二行“附件”列中 edit_table_element.cell_upload_files(col_name="附件", file_path="path/to/file.pdf", row_index=1)

方法： select_cell_date

功能：选择单元格中的日期。参数： col_name：列名。 date：需要选择的日期（支持单个日期字符串、日期列表或日期元组）。 row_index：行号（默认为 0）

# 初始化可编辑表格实例，通过名称定位 edit_table_element = EditTableElement(name="用户列表") # 选择第二行“日期”列中的日期 edit_table_element.select_cell_date(col_name="日期", date="2024-05-31", row_index=1)

VirtualTableElement
虚拟表格-元素类

VirtualTableElement 类继承自 TableElement，专门用于操作虚拟表格（Virtual Table）。虚拟表格通常没有分页功能，且其 HTML 结构与普通表格不同

比如：数字财税的工程量清单

继承自 TableElement，共享 TableElement 的所有功能，并提供额外的展开和折叠行的方法

类属性：
# table_css：用于定位虚拟表格的 CSS 选择器
table_css = ".vxe-table--main-wrapper"

# t_head_css：用于定位虚拟表格表头的 CSS 选择器
t_head_css = ".vxe-table--header"

# t_body_css：用于定位虚拟表格主体的 CSS 选择器
t_body_css = ".vxe-table--body"

方法： expand_row

功能：展开指定行。参数： row_index：行号（默认为 0）。 expand_col_index：展开按钮所在的列索引（默认为 0）

# 初始化虚拟表格实例，通过名称定位 virtual_table_element = VirtualTableElement(name="项目列表") # 展开第二行 virtual_table_element.expand_row(row_index=1)

方法： collapse_row

功能：折叠指定行。参数： row_index：行号（默认为 0）。 expand_col_index：展开按钮所在的列索引（默认为 0）

# 初始化虚拟表格实例，通过名称定位 virtual_table_element = VirtualTableElement(name="项目列表") # 折叠第二行 virtual_table_element.collapse_row(row_index=1)

展开和折叠多行

# 初始化虚拟表格实例，通过名称定位 virtual_table_element = VirtualTableElement(name="项目列表") # 展开前两行 for i in range(2): virtual_table_element.expand_row(row_index=i) # 折叠前两行 for i in range(2): virtual_table_element.collapse_row(row_index=i)

结合其他操作

# 初始化虚拟表格实例，通过名称定位 virtual_table_element = VirtualTableElement(name="项目列表") # 获取表格行数 row_count = virtual_table_element.row_num print(f"表格行数: {row_count}") # 获取第二行的数据 row_data = virtual_table_element.get_row_value(row_index=1) print(f"第二行数据: {row_data}") # 展开第二行 virtual_table_element.expand_row(row_index=1) # 折叠第二行 virtual_table_element.collapse_row(row_index=1) # 点击第二行“操作”列中的“编辑”按钮 virtual_table_element.click_operator(operator_name="编辑", row_index=1, col_name="操作")

TreeElement
树形结构-元素类

TreeElement 类，继承自 BaseElement，用于操作页面中的树形结构元素（如文件夹树、组织架构树等），支持通过名称或自定义定位器来定位树，并提供选择特定节点的方法

类属性：
# tree_css：用于定位树的 CSS 选择器
tree_css = ".el-tree"

# node_name_css：用于定位树节点名称的 CSS 选择器
node_name_css = ".el-tree-node__content"

参数： name：树的第一个根节点文本（可选）。 locator：自定义定位器（可选）。 describe：描述信息（可选）。

方法： select

功能：选择树中的特定节点。参数： node_chain：节点链，可以是字符串（用 - 分隔）或列表

# 初始化树形结构实例，通过名称定位 tree_element = TreeElement(name="项目看板") # 选择路径为“项目看板-子节点1-子节点11”的节点 tree_element.select(node_chain="项目看板-子节点1-子节点11")

# 初始化树形结构实例，通过名称定位 tree_element = TreeElement(name="项目看板") # 选择路径为["项目看板", "子节点1", "子节点11"]的节点 tree_element.select(node_chain=["项目看板", "子节点1", "子节点11"])

# 初始化树形结构实例，通过自定义定位器定位 tree_element = TreeElement(locator=".custom-tree-class") # 选择路径为“项目看板-子节点1-子节点11”的节点 tree_element.select(node_chain="项目看板-子节点1-子节点11")

UploadElement
文件上传控件-元素类

继承自 BaseElement，共享基础元素操作方法，用于操作页面中的文件上传控件，支持通过名称、占位符或自定义定位器来定位上传控件，并提供上传文件的方法

类属性：
# upload_css：用于定位文件上传控件的 CSS 选择器

upload_css = ".el-upload"

参数：
name：上传控件的名称（可选）。
placeholder：上传控件的占位符文本（可选）。
locator：自定义定位器（可选）。
describe：描述信息（可选）

方法： upload_files

功能：上传文件，可以是一个文件路径，也可以是路径列表。参数： file_path：文件路径，可以是绝对路径或相对路径。如果是相对路径，则相对于 settings 中的 UPLOAD_FILES_DIR 目录

初始化上传控件实例并上传单个文件

# 初始化上传控件实例，通过名称定位 upload_element = UploadElement(name="上传附件") # 上传单个文件 upload_element.upload_files("path/to/file.pdf")

初始化上传控件实例并上传多个文件

# 初始化上传控件实例，通过名称定位 upload_element = UploadElement(name="上传附件") # 上传多个文件 upload_element.upload_files(["path/to/file1.pdf", "path/to/file2.pdf"])