跳到主要内容

ElementHandle

ElementHandle 表示页面内的 DOM 元素。可以使用 page.query_selector() 方法创建 ElementHandle。

不推荐

不推荐使用 ElementHandle，请改用 Locator 对象和 Web-优先断言。

href_element = page.query_selector("a")
href_element.click()

ElementHandle 会阻止 DOM 元素被垃圾回收，除非使用 js_handle.dispose() 方法释放该句柄。ElementHandle 会在其源框架导航时自动释放。

ElementHandle 实例可用作 page.eval_on_selector() 和 page.evaluate() 方法的参数。

Locator 和 ElementHandle 的区别在于，ElementHandle 指向特定的元素，而 Locator 捕获如何检索元素的逻辑。

在下面的示例中，`handle` 指向页面上的特定 DOM 元素。如果该元素更改文本或被 React 用于渲染完全不同的组件，`handle` 仍然指向该特定的 DOM 元素。这可能导致意外行为。

handle = page.query_selector("text=Submit")
handle.hover()
handle.click()

使用 `locator` 时，每次使用 `element`，都会使用选择器在页面中定位最新的 DOM 元素。因此在下面的代码片段中，底层 DOM 元素将被定位两次。

locator = page.get_by_text("Submit")
locator.hover()
locator.click()

方法​

bounding_box​

在 v1.9 之前添加 elementHandle.bounding_box

此方法返回元素的边界框，如果元素不可见则返回 `null`。边界框是相对于主框架视口计算的，通常与浏览器窗口相同。

滚动会影响返回的边界框，类似于 Element.getBoundingClientRect。这意味着 `x` 和/或 `y` 可能为负值。

来自子框架的元素返回相对于主框架的边界框，这与 Element.getBoundingClientRect 不同。

假设页面是静态的，可以使用边界框坐标执行输入。例如，下面的代码片段应该点击元素的中心。

用法

box = element_handle.bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

返回值

  • NoneType | Dict#

    • x float

      元素的 x 坐标（像素）。

    • y float

      元素的 y 坐标（像素）。

    • width float

      元素的宽度（像素）。

    • height float

      元素的高度（像素）。

content_frame​

在 v1.9 之前添加 elementHandle.content_frame

返回引用 iframe 节点的元素的 content frame，否则返回 `null`。

用法

element_handle.content_frame()

返回值

owner_frame​

在 v1.9 之前添加 elementHandle.owner_frame

返回包含给定元素的框架。

用法

element_handle.owner_frame()

返回值

wait_for_element_state​

在 v1.9 之前添加 elementHandle.wait_for_element_state

当元素满足 state 条件时返回。

根据 state 参数，此方法会等待一项 可操作性 检查通过。在等待过程中如果元素被分离，此方法会抛出异常，除非等待 `"hidden"` 状态。

  • "visible" 等待直到元素 可见。
  • "hidden" 等待直到元素 不可见 或未 attached。注意，等待 hidden 状态时如果元素分离不会抛出异常。
  • "stable" 等待直到元素既 可见 又 稳定。
  • "enabled" 等待直到元素 可用。
  • "disabled" 等待直到元素 禁用。
  • "editable" 等待直到元素 可编辑。

如果元素在 timeout 毫秒内不满足条件，此方法将抛出异常。

用法

element_handle.wait_for_element_state(state)
element_handle.wait_for_element_state(state, **kwargs)

参数

返回值

已废弃​

check​

在 v1.9 之前添加 elementHandle.check
不推荐

请改用基于 Locator 的 locator.check()。阅读更多关于 Locators 的信息。

此方法通过执行以下步骤检查元素

  1. 确保元素是复选框或单选输入。如果不是，此方法会抛出异常。如果元素已被选中，此方法立即返回。
  2. 等待元素的 可操作性 检查通过，除非设置了 force 选项。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 点击元素的中心。
  5. 确保元素现已被选中。如果不是，此方法抛出异常。

如果在操作期间元素从 DOM 分离，此方法抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，此方法将抛出 TimeoutError。传入零超时可禁用此功能。

用法

element_handle.check()
element_handle.check(**kwargs)

参数

  • force bool (可选)#

    是否绕过 可操作性 检查。默认为 `false`。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)新增于: v1.11#

    相对于元素 padding box 左上角的坐标点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大等待时间，单位为毫秒。默认为 `30000` (30 秒)。传入 `0` 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)新增于: v1.11#

    设置为 `true` 时，此方法仅执行 可操作性 检查并跳过实际操作。默认为 `false`。在不执行操作的情况下等待直到元素准备就绪时很有用。

返回值

click​

在 v1.9 之前添加 elementHandle.click
不推荐

请改用基于 Locator 的 locator.click()。阅读更多关于 Locators 的信息。

此方法通过执行以下步骤点击元素

  1. 等待元素的 可操作性 检查通过，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.mouse 点击元素的中心或指定的 position。
  4. 等待已启动的导航成功或失败，除非设置了 no_wait_after 选项。

如果在操作期间元素从 DOM 分离，此方法抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，此方法将抛出 TimeoutError。传入零超时可禁用此功能。

用法

element_handle.click()
element_handle.click(**kwargs)

参数

  • button "left" | "right" | "middle" (可选)#

    默认为 `left`。

  • click_count int (可选)#

    默认为 1。参见 UIEvent.detail。

  • delay float (可选)#

    mousedown 和 `mouseup` 之间等待的时间，单位为毫秒。默认为 0。

  • force bool (可选)#

    是否绕过 可操作性 检查。默认为 `false`。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

    要按下的修饰键。确保操作期间只按下这些修饰键，然后恢复当前的修饰键。如果未指定，则使用当前按下的修饰键。在 Windows 和 Linux 上，"ControlOrMeta" 解析为 "Control"，在 macOS 上解析为 "Meta"。

  • no_wait_after bool (可选)#

    已废弃

    此选项在将来会默认为 `true`。

    启动导航的操作会等待这些导航发生以及页面开始加载。您可以通过设置此标志来选择不等待。仅在导航到不可访问的页面等特殊情况下才需要此选项。默认为 `false`。

  • position Dict (可选)#

    相对于元素 padding box 左上角的坐标点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大等待时间，单位为毫秒。默认为 `30000` (30 秒)。传入 `0` 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)新增于: v1.11#

    设置为 `true` 时，此方法仅执行 可操作性 检查并跳过实际操作。默认为 `false`。在不执行操作的情况下等待直到元素准备就绪时很有用。

返回值

dblclick​

在 v1.9 之前添加 elementHandle.dblclick
不推荐

请改用基于 Locator 的 locator.dblclick()。阅读更多关于 Locators 的信息。

此方法通过执行以下步骤双击元素

  1. 等待元素的 可操作性 检查通过，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.mouse 双击元素的中心或指定的 position。

如果在操作期间元素从 DOM 分离，此方法抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，此方法将抛出 TimeoutError。传入零超时可禁用此功能。

注意

elementHandle.dblclick() 会派发两个 `click` 事件和一个 `dblclick` 事件。

用法

element_handle.dblclick()
element_handle.dblclick(**kwargs)

参数

  • button "left" | "right" | "middle" (可选)#

    默认为 `left`。

  • delay float (可选)#

    mousedown 和 `mouseup` 之间等待的时间，单位为毫秒。默认为 0。

  • force bool (可选)#

    是否绕过 可操作性 检查。默认为 `false`。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

    要按下的修饰键。确保操作期间只按下这些修饰键，然后恢复当前的修饰键。如果未指定，则使用当前按下的修饰键。在 Windows 和 Linux 上，"ControlOrMeta" 解析为 "Control"，在 macOS 上解析为 "Meta"。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素 padding box 左上角的坐标点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大等待时间，单位为毫秒。默认为 `30000` (30 秒)。传入 `0` 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)新增于: v1.11#

    设置为 `true` 时，此方法仅执行 可操作性 检查并跳过实际操作。默认为 `false`。在不执行操作的情况下等待直到元素准备就绪时很有用。

返回值

dispatch_event​

在 v1.9 之前添加 elementHandle.dispatch_event
不推荐

请改用基于 Locator 的 locator.dispatch_event()。阅读更多关于 Locators 的信息。

下面的代码片段在元素上派发 `click` 事件。无论元素的可见性如何，`click` 事件都会被派发。这等同于调用 element.click()。

用法

element_handle.dispatch_event("click")

底层实现是根据给定的 type 创建一个事件实例，使用 event_init 属性初始化，然后在元素上派发。默认情况下，事件是 `composed`、`cancelable` 且会冒泡。

由于 event_init 特定于事件，请参阅事件文档了解初始化属性列表

如果想将实时对象传递到事件中，也可以指定 `JSHandle` 作为属性值

# note you can only create data_transfer in chromium and firefox
data_transfer = page.evaluate_handle("new DataTransfer()")
element_handle.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

参数

  • type str#

    DOM 事件类型：`"click"`、`"dragstart"` 等。

  • event_init EvaluationArgument (可选)#

    可选的事件特定初始化属性。

返回值

eval_on_selector​

新增于: v1.9 elementHandle.eval_on_selector
不推荐

此方法不会等待元素通过可操作性检查，因此可能导致测试不稳定。请改用 locator.evaluate()、其他 Locator 辅助方法或 Web-优先断言。

返回 expression 的返回值。

此方法在 `ElementHandle` 的子树中查找匹配指定选择器的元素，并将其作为第一个参数传递给 expression。如果没有元素匹配选择器，此方法将抛出错误。

如果 expression 返回一个 Promise，则 element_handle.eval_on_selector() 会等待 Promise 解决并返回其值。

用法

tweet_handle = page.query_selector(".tweet")
assert tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100"
assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") == "10"

参数

  • selector str#

    要查询的选择器。

  • expression str#

    要在浏览器上下文中评估的 JavaScript 表达式。如果表达式评估为一个函数，该函数会自动调用。

  • arg EvaluationArgument (可选)#

    要传递给 expression 的可选参数。

返回值

eval_on_selector_all​

新增于: v1.9 elementHandle.eval_on_selector_all
不推荐

在大多数情况下，locator.evaluate_all()、其他 Locator 辅助方法和 Web-优先断言会做得更好。

返回 expression 的返回值。

此方法在 `ElementHandle` 的子树中查找匹配指定选择器的所有元素，并将匹配元素的数组作为第一个参数传递给 expression。

如果 expression 返回一个 Promise，则 element_handle.eval_on_selector_all() 会等待 Promise 解决并返回其值。

用法

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>
feed_handle = page.query_selector(".feed")
assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"]

参数

  • selector str#

    要查询的选择器。

  • expression str#

    要在浏览器上下文中评估的 JavaScript 表达式。如果表达式评估为一个函数，该函数会自动调用。

  • arg EvaluationArgument (可选)#

    要传递给 expression 的可选参数。

返回值

fill​

在 v1.9 之前添加 elementHandle.fill
不推荐

请改用基于 Locator 的 locator.fill()。阅读更多关于 Locators 的信息。

此方法等待 可操作性 检查通过，聚焦元素，填充内容并在填充后触发一个 `input` 事件。请注意，可以传入空字符串以清除输入字段。

如果目标元素不是 ``、`