Skip to main content

ElementHandle

ElementHandle 表示页面内的 DOM 元素。ElementHandle 可以通过 page.query_selector(selector, **kwargs) 方法创建。

Discouraged

不推荐使用 ElementHandle，请改用 Locator 对象和 web-first 断言。

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

ElementHandle 会阻止 DOM 元素被垃圾回收，除非使用 js_handle.dispose() 销毁句柄。当 ElementHandle 所在的 frame 导航时，它们会被自动销毁。

ElementHandle 实例可以作为参数传递给 page.eval_on_selector(selector, expression, **kwargs) 和 page.evaluate(expression, **kwargs) 方法。

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

element_handle.bounding_box()​

Added in: v1.8
  • 返回值: <NoneType|Dict>#
    • x <float> 元素的 x 坐标（像素）。
    • y <float> 元素的 y 坐标（像素）。
    • width <float> 元素的宽度（像素）。
    • height <float> 元素的高度（像素）。

此方法返回元素的边界框，如果元素不可见则返回 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)

element_handle.check(**kwargs)​

Added in: v1.8
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。Added in: v1.11#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

此方法通过执行以下步骤来选中元素：

  1. 确保元素是复选框或单选输入框。如果不是，此方法报错。如果元素已选中，此方法立即返回。
  2. 等待元素上的 actionability 检查，除非设置了 force 选项。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 点击元素的中心。
  5. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。
  6. 确保元素现在已被选中。如果不是，此方法报错。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

element_handle.click(**kwargs)​

Added in: v1.8
  • button <"left"|"right"|"middle"> 默认为 left。#
  • click_count <int> 默认为 1。参见 UIEvent.detail。#
  • delay <float> mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保操作期间只按下这些修饰符，然后恢复当前的修饰符。如果未指定，则使用当前按下的修饰符。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

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

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

如果元素在操作期间的任何时刻从 DOM 中分离，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

element_handle.content_frame()​

Added in: v1.8

对于引用 iframe 节点的元素句柄，返回内容 frame，否则返回 null。

element_handle.dblclick(**kwargs)​

Added in: v1.8
  • button <"left"|"right"|"middle"> 默认为 left。#
  • delay <float> mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保操作期间只按下这些修饰符，然后恢复当前的修饰符。如果未指定，则使用当前按下的修饰符。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

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

  1. 等待元素上的 actionability 检查，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.mouse 双击元素的中心，或指定的 position。
  4. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。注意，如果 dblclick() 的第一次点击触发了导航事件，此方法将抛出错误。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

note

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

element_handle.dispatch_event(type, **kwargs)​

Added in: v1.8

下面的代码片段在元素上派发 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})

element_handle.eval_on_selector(selector, expression, **kwargs)​

Added in: v1.9
  • selector <str> 要查询的选择器。有关详细信息，请参阅使用选择器。#
  • expression <str> 要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为一个函数，则自动调用该函数。#
  • arg <EvaluationArgument> 传递给 expression 的可选参数。#
  • 返回值: <Serializable>#

返回 expression 的返回值。

此方法在 ElementHandle 的子树中查找与指定选择器匹配的元素，并将其作为第一个参数传递给 expression。有关详细信息，请参阅使用选择器。如果没有元素匹配选择器，此方法报错。

如果 expression 返回 Promise，则 element_handle.eval_on_selector(selector, expression, **kwargs) 将等待 promise 解析并返回其值。

Examples:

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"

element_handle.eval_on_selector_all(selector, expression, **kwargs)​

Added in: v1.9
  • selector <str> 要查询的选择器。有关详细信息，请参阅使用选择器。#
  • expression <str> 要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为一个函数，则自动调用该函数。#
  • arg <EvaluationArgument> 传递给 expression 的可选参数。#
  • 返回值: <Serializable>#

返回 expression 的返回值。

此方法在 ElementHandle 的子树中查找与指定选择器匹配的所有元素，并将匹配元素数组作为第一个参数传递给 expression。有关详细信息，请参阅使用选择器。

如果 expression 返回 Promise，则 element_handle.eval_on_selector_all(selector, expression, **kwargs) 将等待 promise 解析并返回其值。

Examples:

<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!"]

element_handle.fill(value, **kwargs)​

Added in: v1.8
  • value <str> 要为 <input>、<textarea> 或 [contenteditable] 元素设置的值。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。Added in: v1.13#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType>#

此方法等待 actionability 检查，聚焦元素，填充它，并在填充后触发 input 事件。注意，可以传递空字符串来清空输入框。

如果目标元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法报错。但是，如果元素位于具有关联 control 的 <label> 元素内，则改为填充该控件。

要发送细粒度的键盘事件，请使用 element_handle.type(text, **kwargs)。

element_handle.focus()​

Added in: v1.8

在元素上调用 focus。

element_handle.get_attribute(name)​

Added in: v1.8

返回元素属性值。

element_handle.hover(**kwargs)​

Added in: v1.8
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保操作期间只按下这些修饰符，然后恢复当前的修饰符。如果未指定，则使用当前按下的修饰符。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

此方法通过执行以下步骤悬停在元素上：

  1. 等待元素上的 actionability 检查，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.mouse 将鼠标悬停在元素的中心，或指定的 position。
  4. 等待发起的导航成功或失败，除非设置了 noWaitAfter 选项。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

element_handle.inner_html()​

Added in: v1.8

返回 element.innerHTML。

element_handle.inner_text()​

Added in: v1.8

返回 element.innerText。

element_handle.input_value(**kwargs)​

Added in: v1.13

返回所选 <input>、<textarea> 或 <select> 元素的 input.value。

对于非输入元素抛出错误。但是，如果元素位于具有关联 control 的 <label> 元素内，则返回控件的值。

element_handle.is_checked()​

Added in: v1.8

返回元素是否被选中。如果元素不是 checkbox 或 radio input，则抛出错误。

element_handle.is_disabled()​

Added in: v1.8

返回元素是否被禁用，与 enabled 相反。

element_handle.is_editable()​

Added in: v1.8

返回元素是否 editable。

element_handle.is_enabled()​

Added in: v1.8

返回元素是否 enabled。

element_handle.is_hidden()​

Added in: v1.8

返回元素是否隐藏，与 visible 相反。

element_handle.is_visible()​

Added in: v1.8

返回元素是否 visible。

element_handle.owner_frame()​

Added in: v1.8

返回包含给定元素的 frame。

element_handle.press(key, **kwargs)​

Added in: v1.8
  • key <str> 要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a。#
  • delay <float> keydown 和 keyup 之间等待的时间（毫秒）。默认为 0。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType>#

聚焦元素，然后使用 keyboard.down(key) 和 keyboard.up(key)。

key 可以指定预期的 keyboardEvent.key 值或要为其生成文本的单个字符。可以在此处找到 key 值的超集。键的示例包括：

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

如果是以下修饰键，则按住该键而不释放：

Shift、Control、Alt、Meta、ShiftLeft 等。

按住 Shift 将键入与大写 key 对应的文本。

如果 key 是单个字符，则区分大小写，因此值 a 和 A 将生成不同的相应文本。

还支持诸如 key: "Control+o" 或 key: "Control+Shift+T" 之类的快捷键。当指定修饰符时，按下修饰符并在按下后续键时保持按住。

简单地按一个键：

element_handle.press("Enter")

但是，可以使用 Control+O 快捷键打开文件：

element_handle.press("Control+O")
element_handle.press("Shift+Select all")

快捷键（如 KeyA）映射到代码（如 KeyA）。

note

对于像 Control+A 这样的文本操作快捷键，请使用 page.keyboard.press(key, **kwargs)。

element_handle.query_selector(selector)​

Added in: v1.9

此方法在 ElementHandle 的子树中查找与指定选择器匹配的元素。有关详细信息，请参阅使用选择器。如果没有元素匹配选择器，返回 null。

element_handle.query_selector_all(selector)​

Added in: v1.9

此方法在 ElementHandle 的子树中查找与指定选择器匹配的所有元素。有关详细信息，请参阅使用选择器。如果没有元素匹配选择器，返回空列表。

element_handle.screenshot(**kwargs)​

Added in: v1.8
  • animations <"disabled"|"allow"> 停止 CSS 动画时，CSS 属性将更新为初始值。默认为 allow。#
  • caret <"hide"|"initial"> 截图时，是否隐藏文本插入符号。默认为 hide。#
  • clip <Dict> 指定页面剪裁区域的对象。包含 x、y、width 和 height。#
    • x <float> 剪裁区域左上角的 x 坐标。
    • y <float> 剪裁区域左上角的 y 坐标。
    • width <float> 剪裁区域的宽度。
    • height <float> 剪裁区域的高度。
  • mask <List[Locator]> 指定截图时需要遮罩的定位器。遮罩元素会被覆盖在粉红色的 #FF00FF 框上，以此掩盖截图上的变化。Added in: v1.11#
  • omit_background <bool> 隐藏默认的白色背景，并允许捕获透明背景的截图。这不适用于 jpeg 图像。默认为 false。#
  • path <Union[str, pathlib.Path]> 保存图像的文件路径。截图类型将从文件扩展名推断出。如果 path 是相对路径，则相对于当前工作目录解析。#
  • quality <int> 图像质量，介于 0-100 之间。不适用于 png 图像。#
  • scale <"css"|"device"> 默认为 css，此时截图将具有单个像素对应的每个 css 像素。如果设置为 device，截图将具有单个像素对应的每个设备像素，因此高 dpi 设备的截图将是原来的两倍大（取决于 devicePixelRatio）。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • type <"png"|"jpeg"> 指定截图类型，可以是 png 或 jpeg。默认为 png。#
  • 返回值: <bytes>#

此方法捕获页面的屏幕截图，剪切到元素的大小和位置。如果元素从 DOM 中分离，此方法抛出错误。

返回捕获的屏幕截图的缓冲区。如果元素是可滚动容器，则只有当前滚动的内容在屏幕截图中可见。

此方法等待 actionability 检查，然后在截取屏幕截图之前将元素滚动到视图中。如果元素从 DOM 中分离，此方法将抛出错误。

返回包含捕获的屏幕截图的缓冲区。

element_handle.scroll_into_view_if_needed(**kwargs)​

Added in: v1.8

此方法等待 actionability 检查，然后尝试滚动元素以使其显现在视口中，除非它完全可见。

如果 element_handle 没有指向 连接 到 Document 或 ShadowRoot 的元素，则抛出错误。

element_handle.select_option(**kwargs)​

Added in: v1.8
  • force <bool> 是否跳过 actionability 检查。默认为 false。Added in: v1.13#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • element <ElementHandle|List[ElementHandle]> 要选择的选项。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则只选择第一个选项。匹配的选项必须完全等同于 id。#
  • index <int|List[int]> 要选择的选项索引。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则只选择第一个选项。#
  • value <str|List[str]> 要选择的选项值。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则只选择第一个选项。#
  • label <str|List[str]> 要选择的选项标签。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则只选择第一个选项。#
  • 返回值: <List[str]>#

返回所选选项输入值的列表。

此方法等待 actionability 检查，等待所有指定的选项出现在 <select> 中，并选择这些选项。

如果目标元素不是 <select> 元素，此方法抛出错误。但是，如果元素位于具有关联 control 的 <label> 元素内，则改为在控件上使用此方法。

返回已成功选择的选项值的数组。

一旦选择了所有提供的选项，将触发 change 和 input 事件。

# single selection matching the value
handle.select_option("blue")
# single selection matching both the label
handle.select_option(label="blue")
# multiple selection
handle.select_option(value=["red", "green", "blue"])

element_handle.select_text(**kwargs)​

Added in: v1.8

此方法等待 actionability 检查，然后聚焦元素并选择其所有文本内容。

如果元素位于具有关联 control 的 <label> 元素内，则聚焦并选中控件中的文本。

element_handle.set_checked(checked, **kwargs)​

Added in: v1.15
  • checked <bool> 是否选中元素。默认为 true。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

此方法选中或取消选中元素。如果元素已处于所需状态，则此方法立即返回。

通过执行以下步骤来选中或取消选中元素：

  1. 确保元素是复选框或单选输入框。如果不是，此方法报错。
  2. 等待元素上的 actionability 检查，除非设置了 force 选项。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 点击元素的中心。
  5. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。
  6. 确保元素现在已被选中或取消选中。如果不是，此方法报错。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

element_handle.set_input_files(files, **kwargs)​

Added in: v1.8

将文件输入的值设置为这些文件路径或文件。如果某些 filePaths 是相对路径，则它们相对于当前工作目录解析。对于空数组，清除选定的文件。

此方法期望 ElementHandle 指向 input element。但是，如果元素位于具有关联 control 的 <label> 元素内，则指向该控件。

element_handle.tap(**kwargs)​

Added in: v1.8
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

此方法通过执行以下步骤来点击（taps）元素：

  1. 等待元素上的 actionability 检查，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.touchscreen 点击（tap）元素的中心或指定的 position。
  4. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

note

elementHandle.tap() 要求将浏览器上下文的 hasTouch 选项设置为 true。

element_handle.text_content()​

Added in: v1.8

返回 node.textContent。

element_handle.type(text, **kwargs)​

Added in: v1.8
  • text <str> 要输入到聚焦元素的文本。#
  • delay <float> 按键之间的等待时间（毫秒）。默认为 0。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType>#

聚焦元素，然后为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。

要按特殊键，如 Control 或 ArrowDown，请使用 element_handle.press(key, **kwargs)。

element_handle.type("hello") # types instantly
element_handle.type("world", delay=100) # types slower, like a user

在一个文本框中输入并提交表单的示例：

element_handle = page.query_selector("input")
element_handle.type("some text")
element_handle.press("Enter")

element_handle.uncheck(**kwargs)​

Added in: v1.8
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

此方法通过执行以下步骤来取消选中元素：

  1. 确保元素是复选框或单选输入框。如果不是，此方法报错。如果元素已经取消选中，此方法立即返回。
  2. 等待元素上的 actionability 检查，除非设置了 force 选项。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 点击（tap）元素的中心。
  5. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。
  6. 确保元素现在已取消选中。如果不是，此方法报错。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

element_handle.wait_for_element_state(state, **kwargs)​

Added in: v1.8

当元素满足 state 时返回。

根据 state 参数，此方法等待 actionability 检查之一通过。除非等待 "hidden" 状态，否则如果在等待时元素分离，此方法将报错。

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

element_handle.wait_for_selector(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要查询的选择器。有关详细信息，请参阅使用选择器。#
  • state <"attached"|"detached"|"visible"|"hidden"> 默认为 'visible'。可以是以下之一：#
    • 'attached' - 等待元素出现在 DOM 中。
    • 'detached' - 等待元素从 DOM 中消失。
    • 'visible' - 等待元素具有非空边界框且没有 visibility:hidden。请注意，没有任何内容或具有 display:none 的元素具有空边界框，并且不被视为可见。
    • 'hidden' - 等待元素从 DOM 中分离，或具有空边界框或 visibility:hidden。这与 'visible' 选项相反。
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.15#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType|ElementHandle>#

返回由选择器指定的元素，当该元素满足 state 选项时。如果在等待 hidden 或 detached，则返回 null。

等待相对于元素句柄的 selector 满足 state 选项（出现在/消失于 DOM，或 变得可见/隐藏）。如果在调用方法时 selector 已经满足条件，该方法将立即返回。如果选择器在 timeout 毫秒内不满足条件，函数将抛出错误。

page.set_content("<div><span></span></div>")
div = page.query_selector("div")
# waiting for the "span" selector relative to the div.
span = div.wait_for_selector("span", state="attached")
note

此方法不适用于跨导航操作，请改用 page.wait_for_selector(selector, **kwargs)。