playwright 自动化框架python教程(十三)[locator/query_selector/wait_for_selector..等方法]

page.locator()/page.locator().all()

• 返回类型

• page.locator() 返回一个 locator 对象，它是一个表示页面元素的抽象，提供了多种方法来操作这些元素。

• 惰性执行

      创建 locator 对象时并不会立即执行任何操作，只有当你调用 locator 上的方法时（如 .click(), .fill(), .nth() 等）才会执行相应的操作。

如果元素查询不到时，提示操作超时异常时。如

playwright._impl._errors.TimeoutError: Locator.click: Timeout 30000ms exceeded.
E           Call log:
E           waiting for locator("div[id=\"suggestion-list123\"] > *")

查询父元素下的所有子元素，例如:

def locator_calendar_fullCompose_suggestionList_allChild(page):
    dict1 = {"description": "Search location后显示的 suggestionList的所有内容",
             "locator": 'div[id="suggestion-list"]>*'}
    # 定义元素的索引，默认为0
    locator_str = dict1['locator']
    return page.locator(locator_str).all()

• 操作方法

   page.locator() 返回的对象提供了许多方法，如 .click(), .fill(), .press(), .evaluate() 等，可以直接在 locator 对象上调用这些方法来操作元素。

• 多元素操作

        可以使用 .all() 获取所有匹配的元素，或者使用 .nth(index) 来获取特定索引的元素。

如果.all()找不到时，返回空列表[]。

-----------------------------------------------------------------------------------------------------------

page.wait_for_selector()

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

方法签名

page.wait_for_selector(selector, state=None, timeout=None)

参数说明

• 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)

返回值

page.wait_for_selector()方法成功执行并且找到匹配的元素时，它返回一个 Locator 对象。Locator 对象允许你对页面上的元素执行各种操作，如点击、填写表单等。

匹配多个元素场景

page.wait_for_selector() 如果匹配多个元素时

注意事项

• 匹配多个元素：即使选择器匹配了多个元素，page.wait_for_selector() 也只会返回第一个匹配的元素。
• 需要所有元素：如果你需要对所有匹配的元素进行操作，可以使用 page.locator() 方法并调用 all() 方法来获取所有匹配的元素列表。

• # 创建定位器对象，并获取所有匹配的元素
  elements = page.locator('.myElement').all()

• 定位特定元素：需要使用page.locator ()处理
• 参照page.locator()方法

-----------------------------------------------------------------------------------------------------------

page.query_selector()/page.query_selector_all()

• 返回类型：page.query_selector() 返回一个 ElementHandle，该对象代表了页面上找到的第一个匹配元素。这个 ElementHandle 对象提供了多种方法来与页面上的元素进行交互，例如点击、填写表单字段等。
• 立即执行：调用 page.query_selector() 会立即执行操作，并返回匹配的第一个元素的 NodeHandle。如果查询不到返回None
• page.query_selector_all()如果查询不到，返回空列表[]

下面是 ElementHandle 的一些常用方法及其简要说明：

1. elementHandle.boundingBox()

• 功能：获取元素的边界框位置和尺寸。
• 返回：一个包含 {x, y, width, height} 的对象，如果元素不在视图内则返回 null。

2. elementHandle.click(options)

• 功能：模拟点击事件。
• 参数：options 是一个可选的对象，可以设置点击的位置、点击次数等。

3. elementHandle.dblclick(options)

• 功能：模拟双击事件。
• 参数：options 是一个可选的对象，可以设置点击的位置等。

4. elementHandle.hover()

• 功能：模拟鼠标悬停事件。

5. elementHandle.textContent()

• 功能：获取元素的文本内容。
• 返回：元素的文本内容作为字符串。

6. elementHandle.innerText()

• 功能：获取元素的内部文本。
• 返回：元素的内部文本作为字符串。

7. elementHandle.getAttribute(name)

• 功能：获取元素的属性值。
• 参数：name 是属性名。
• 返回：属性值作为字符串，如果不存在则返回 null。

8. elementHandle.fill(value)

• 功能：填充表单字段。
• 参数：value 是要填入的值。

9. elementHandle.type(text, options)

• 功能：模拟键盘输入。
• 参数：text 是要输入的文本；options 可以包含延迟等选项。

10. elementHandle.press(key, options)

• 功能：模拟按键按下和释放。
• 参数：key 是要按下的键；options 可以包含延迟等选项。

11. elementHandle.evaluate(pageFunction, ...args)

• 功能：在页面上下文中执行函数。
• 参数：pageFunction 是在页面上下文中执行的函数；...args 是传递给 pageFunction 的参数。

12. elementHandle.screenshot(options)

• 功能：对元素进行截图。
• 参数：options 包含截图的各种选项，如路径、质量等。

13. elementHandle.boxModel()

• 功能：获取元素的盒模型信息。
• 返回：一个包含元素盒模型信息的对象。

14. elementHandle.dispose()

• 功能：释放 ElementHandle。

15. elementHandle.contentFrame()

• 功能：获取元素所在的 Frame。
• 返回：Frame 对象，如果元素不在任何帧中，则返回 null。

16. elementHandle.isIntersectingViewport()

• 功能：检查元素是否与视口相交。
• 返回：布尔值，如果元素与视口相交则为 true。

17. elementHandle.isVisible()

• 功能：检查元素是否可见。
• 返回：布尔值，如果元素可见则为 true。

18. elementHandle.isEditable()

• 功能：检查元素是否可编辑。
• 返回：布尔值，如果元素可编辑则为 true。

19. elementHandle.isDisabled()

• 功能：检查元素是否被禁用。
• 返回：布尔值，如果元素被禁用则为 true。

20. elementHandle.isDetached()

• 功能：检查元素是否从 DOM 中移除。
• 返回：布尔值，如果元素已从 DOM 中移除则为 true。

21. elementHandle.waitForFunction(pageFunction, options, ...args)

• 功能：等待指定条件满足。
• 参数：pageFunction 是在页面上下文中执行的函数；options 可以包含超时等选项；...args 是传递给 pageFunction 的参数。

22. elementHandle.waitForSelector(selector, options)

• 功能：等待子元素出现。
• 参数：selector 是子元素的选择器；options 可以包含超时等选项。

23. elementHandle.waitForXPath(xpath, options)

• 功能：等待子元素通过 XPath 出现。
• 参数：xpath 是 XPath 表达式；options 可以包含超时等选项。

以上就是 ElementHandle 中一些常用的 API 方法。请注意，这些方法的具体实现可能会随 Playwright 版本的不同而略有差异。建议参考最新的文档以获取最准确的信息。

-----------------------------------------------------------------------------------------------------------

scroll_into_view_if_needed()

用于将页面中的某个元素滚动到可视区域，如果该元素不在当前可视区域内的话。这对于自动化测试特别有用

参数传递

scroll_into_view_if_needed() 方法还接受一个可选的参数对象，用于控制滚动的行为。例如，你可以设置 block 和 inline 属性来指定滚动的方向：

elementLocator.scroll_into_view_if_needed({
  block: 'center', // 可以是 'start', 'center', 'end'
  inline: 'center' // 可以是 'start', 'center', 'end'
});

这里 block 控制垂直方向的滚动位置，inline 控制水平方向的滚动位置。

page.mouse.wheel(x,y)

page.mouse.wheel(x, y, delta_x=0, delta_y=0)

参数说明

• x: 鼠标指针的 X 坐标（相对于页面的左边缘）。
• y: 鼠标指针的 Y 坐标（相对于页面的顶部边缘）。
• delta_x (可选): 水平方向上的滚动距离（单位为像素）。正值表示向右滚动，负值表示向左滚动。默认为 0。
• delta_y (可选): 垂直方向上的滚动距离（单位为像素）。正值表示向下滚动，负值表示向上滚动。默认为 0。

page.mouse.move(x,y)

移动到坐标位置（x,y）

page.wait_for_timeout(milliseconds)

page.wait_for_timeout(milliseconds);

其中 milliseconds 是要等待的毫秒数。

wait_for_load_state()

wait_for_load_state() 用于等待页面达到某种加载状态。这个方法可以根据页面的实际加载情况来决定何时继续执行下一步操作，因此比简单的延时更加智能和可靠。

用法

await page.wait_for_load_state(state);

其中 state 是要等待的页面加载状态，可以是 'load', 'domcontentloaded', 或者 'networkidle'。

• 'load'：等待页面及其所有子资源加载完成（如图片、样式表等）。
• 'domcontentloaded'：等待 DOM 加载完成，但不包括图像、字体等外部资源。
• 'networkidle'：等待页面及其所有子资源加载完成，并且没有新的网络请求开始后的 500 毫秒内。