ElementHandle

• 继承自：JSHandle

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

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

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

ElementHandle 可以防止 DOM 元素被垃圾回收，除非通过 js_handle.dispose() 方法释放该句柄。当元素所在的框架发生导航时，ElementHandles 会自动被释放。

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

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

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

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

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

方法​

边界框​

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

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

返回

• NoneType | 字典#

  • x float

    元素的x坐标，单位为像素。

  • y float

    元素的y坐标，单位为像素。

  • width float

    元素的宽度，单位为像素。

  • height float

    元素的高度，单位为像素。

content_frame​

返回引用iframe节点的元素句柄的内容框架，否则返回null

用法

element_handle.content_frame()

返回

• NoneType | Frame#

owner_frame​

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

用法

element_handle.owner_frame()

返回

• NoneType | Frame#

等待元素状态​

当元素满足state状态时返回。

根据state参数的不同，该方法会等待其中一个actionability检查通过。如果在等待期间元素被分离，该方法会抛出异常，除非等待的是"hidden"状态。

• "visible" 等待元素变为可见状态。
• "hidden" 等待直到元素不可见或未附加。请注意，等待元素隐藏时，如果元素分离不会抛出错误。
• "stable" 等待直到元素既可见又稳定。
• "enabled" 等待直到元素变为enabled状态。
• "disabled" 等待直到元素不可用。
• "editable" 等待元素变为可编辑状态。

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

用法

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

参数

• state "visible" | "hidden" | "stable" | "enabled" | "disabled" | "editable"#

  要等待的状态，更多详情请参阅下文。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType#

已弃用​

检查​

该方法通过执行以下步骤来检查元素：

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

如果在操作过程中的任何时刻元素从DOM中分离，该方法会抛出异常。

当所有步骤在指定的timeout时间内未完成时，该方法会抛出TimeoutError。传递零超时将禁用此功能。

用法

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

参数

• force bool (可选)#

  是否绕过actionability检查。默认为false。

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• position Dict (可选) 添加于: v1.11#

  • x float

  • y float

  一个相对于元素内边距框左上角使用的点。如果未指定，则使用元素的某个可见点。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• trial bool (可选) 添加于: v1.11#

  当设置时，此方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作而无需实际执行的情况。

返回

• NoneType#

点击​

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

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 (可选)#

  是否绕过actionability检查。默认为false。

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

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

• no_wait_after bool (可选)#

  已弃用

  此选项在未来将默认设置为true。

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

• position Dict (可选)#

  • x float

  • y float

  一个相对于元素内边距框左上角使用的点。如果未指定，则使用元素的某个可见点。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• trial bool (可选) 添加于: v1.11#

  当设置时，此方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作而无需实际执行的情况。

返回

• NoneType#

双击​

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

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

如果在操作过程中的任何时刻元素从DOM中分离，该方法会抛出异常。

当所有步骤在指定的timeout时间内未完成时，该方法会抛出TimeoutError。传递零超时将禁用此功能。

用法

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

参数

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

  默认为 left。

• delay float (可选)#

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

• force bool (可选)#

  是否绕过actionability检查。默认为false。

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

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

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• position Dict (可选)#

  • x float

  • y float

  一个相对于元素内边距框左上角使用的点。如果未指定，则使用元素的某个可见点。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• trial bool (可选) 添加于: v1.11#

  当设置时，此方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作而无需实际执行的情况。

返回

• NoneType#

dispatch_event​

下面的代码片段会在元素上触发click事件。无论元素的可见状态如何，都会触发click事件。这相当于调用element.click()。

用法

element_handle.dispatch_event("click")

await element_handle.dispatch_event("click")

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

由于 event_init 是事件特定的，请参考事件文档以获取初始属性列表：

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• 事件
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

如果希望将实时对象传递到事件中，您也可以将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})

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

参数

• type str#

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

• event_init EvaluationArgument (可选)#

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

返回

• NoneType#

eval_on_selector​

返回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"

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

参数

• selector str#

  用于查询的选择器。

• expression str#

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

• arg EvaluationArgument (可选)#

  可选的参数传递给 expression。

返回

• Dict#

eval_on_selector_all​

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

feed_handle = await page.query_selector(".feed")
assert await feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"]

参数

• selector str#

  用于查询的选择器。

• expression str#

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

• arg EvaluationArgument (可选)#

  可选的参数传递给 expression。

返回

• Dict#

fill​

该方法会等待可操作性检查，聚焦元素，填充内容并在填充后触发input事件。请注意，您可以传递空字符串来清空输入框。

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

要发送精细的键盘事件，请使用 locator.press_sequentially()。

用法

element_handle.fill(value)
element_handle.fill(value, **kwargs)

参数

• value str#

  要为、或[contenteditable]元素设置的值。

• force bool (可选) 添加于: v1.13#

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

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType#

focus​

在元素上调用focus。

用法

element_handle.focus()

返回

• NoneType#

get_attribute​

返回元素的属性值。

用法

element_handle.get_attribute(name)

参数

• name str#

  要获取值的属性名称。

返回

• NoneType | str#

悬停​

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

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

如果在操作过程中元素从DOM中分离，该方法会抛出异常。

当所有步骤在指定的timeout时间内未完成时，该方法会抛出TimeoutError。传递零超时将禁用此功能。

用法

element_handle.hover()
element_handle.hover(**kwargs)

参数

• force bool (可选)#

  是否绕过actionability检查。默认为false。

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

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

• no_wait_after bool (可选) 添加于: v1.28#

  已弃用

  此选项无效。

  此选项无效。

• position Dict (可选)#

  • x float

  • y float

  一个相对于元素内边距框左上角使用的点。如果未指定，则使用元素的某个可见点。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• trial bool (可选) 添加于: v1.11#

  当设置时，此方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作而无需实际执行的情况。

返回

• NoneType#

inner_html​

Returns the element.innerHTML.

用法

element_handle.inner_html()

返回

• str#

inner_text​

返回 element.innerText。

用法

element_handle.inner_text()

返回

• str#

输入值​

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

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

用法

element_handle.input_value()
element_handle.input_value(**kwargs)

参数

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• str#

is_checked​

返回元素是否被选中。如果元素不是复选框或单选输入，则会抛出错误。

用法

element_handle.is_checked()

返回

• bool#

is_disabled​

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

用法

element_handle.is_disabled()

返回

• bool#

is_editable​

返回该元素是否可编辑。

用法

element_handle.is_editable()

返回

• bool#

is_enabled​

返回元素是否启用。

用法

element_handle.is_enabled()

返回

• bool#

is_hidden​

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

用法

element_handle.is_hidden()

返回

• bool#

is_visible​

返回元素是否可见。

用法

element_handle.is_visible()

返回

• bool#

按下​

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

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, 等。

还支持以下修改快捷键：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。

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

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

诸如key: "Control+o"、key: "Control++或key: "Control+Shift+T"之类的快捷键也同样支持。当指定修饰键时，修饰键会被按下并保持按住状态，同时后续的键被按下。

用法

element_handle.press(key)
element_handle.press(key, **kwargs)

参数

• key str#

  要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a。

• delay float (可选)#

  在keydown和keyup之间等待的时间，单位为毫秒。默认为0。

• no_wait_after bool (可选)#

  已弃用

  此选项在未来将默认设置为true。

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

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType#

query_selector​

该方法在ElementHandle的子节点树中查找与指定选择器匹配的元素。如果没有元素匹配该选择器，则返回null。

用法

element_handle.query_selector(selector)

参数

• selector str#

  用于查询的选择器。

返回

• NoneType | ElementHandle#

query_selector_all​

该方法在ElementHandle子树中查找所有匹配指定选择器的元素。如果没有元素匹配选择器，则返回空数组。

用法

element_handle.query_selector_all(selector)

参数

• selector str#

  用于查询的选择器。

返回

• 列表[元素句柄]#

截图​

该方法会截取页面的屏幕截图，裁剪为此特定元素的大小和位置。如果该元素被其他元素覆盖，则在屏幕截图中实际上不可见。如果该元素是可滚动容器，则屏幕截图中仅显示当前滚动的内容。

该方法在截取屏幕截图前会等待可操作性检查，然后将元素滚动到视图中。如果元素已从DOM中分离，该方法将抛出错误。

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

用法

element_handle.screenshot()
element_handle.screenshot(**kwargs)

参数

• animations "disabled" | "allow" (可选)#

  当设置为"disabled"时，会停止CSS动画、CSS过渡和Web动画。动画会根据其持续时间受到不同的处理：

  • 有限动画会被快进到完成状态，因此会触发transitionend事件。
  • 无限循环动画会被取消回到初始状态，截图完成后会重新播放。

  默认为"allow"，表示保持动画原样不做处理。

• caret "hide" | "initial" (可选)#

  当设置为"hide"时，截图将隐藏文本光标。当设置为"initial"时，文本光标行为将保持不变。默认为"hide"。

• mask List[Locator] (可选)#

  指定在截图时应被遮罩的定位器。被遮罩的元素将被一个粉红色盒子#FF00FF（可通过mask_color自定义）完全覆盖其边界框。该遮罩也会应用于不可见元素，如需禁用此功能请参阅Matching only visible elements。

• mask_color str (可选) 添加于: v1.35#

  指定被遮罩元素的覆盖框颜色，使用CSS颜色格式。默认颜色为粉色#FF00FF。

• omit_background bool (可选参数)#

  隐藏默认的白色背景，允许捕获带透明度的截图。不适用于jpeg格式的图片。默认为false。

• path Union[str, pathlib.Path] (可选)#

  保存图片的文件路径。截图类型将从文件扩展名推断。如果path是相对路径，则相对于当前工作目录解析。如果未提供路径，图片将不会保存到磁盘。

• quality int (可选)#

  图像质量，介于0-100之间。不适用于png图像。

• scale "css" | "device" (可选)#

  当设置为"css"时，截图将对应页面上的每个CSS像素生成一个像素。对于高DPI设备，这将保持截图较小。使用"device"选项将为每个设备像素生成一个像素，因此高DPI设备的截图会是两倍甚至更大。

  默认为"device"。

• style str (可选) 添加于: v1.41#

  在截图时应用的样式表文本。在这里您可以隐藏动态元素、使元素不可见或更改其属性，以帮助创建可重复的截图。此样式表穿透Shadow DOM并应用于内部框架。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• type "png" | "jpeg" (可选)#

  指定截图类型，默认为png。

返回

• bytes#

scroll_into_view_if_needed​

该方法等待可操作性检查，然后尝试将元素滚动到视图中，除非它完全可见，如IntersectionObserver的ratio所定义。

当elementHandle未指向连接到Document或ShadowRoot的元素时抛出错误。

查看scrolling获取其他滚动方式。

用法

element_handle.scroll_into_view_if_needed()
element_handle.scroll_into_view_if_needed(**kwargs)

参数

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType#

select_option​

该方法会等待可操作性检查，直到所有指定选项出现在元素中并选择这些选项。

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

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

在选择完所有提供的选项后，触发change和input事件。

用法

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

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

参数

• force bool (可选) 添加于: v1.13#

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

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• element ElementHandle | List[ElementHandle] (可选)#

  要选择的选项元素。可选。

• index int | List[int] (可选)#

  按索引选择的选项。可选。

• value str | List[str] (可选)#

  按值选择的选项。如果<select>具有multiple属性，则选择所有给定的选项，否则只选择与传入选项匹配的第一个选项。可选参数。

• label str | List[str] (可选)#

  通过标签选择选项。如果<select>元素具有multiple属性，则会选中所有匹配的选项；否则只选中第一个与传入选项匹配的选项。此为可选参数。

返回

• List[str]#

select_text​

该方法等待可操作性检查，然后聚焦元素并选择其所有文本内容。

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

用法

element_handle.select_text()
element_handle.select_text(**kwargs)

参数

• force bool (可选) 添加于: v1.13#

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

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType#

set_checked​

该方法通过执行以下步骤来勾选或取消勾选元素：

1. 确保元素是复选框或单选输入框。如果不是，该方法会抛出异常。
2. 如果元素已经处于正确的选中状态，该方法会立即返回。
3. 等待对匹配元素执行可操作性检查，除非设置了force选项。如果在检查期间元素被分离，则会重试整个操作。
4. 如果需要，将元素滚动到视图中。
5. 使用 page.mouse 点击元素的中心位置。
6. 确保元素现在已被选中或取消选中。如果没有，此方法将抛出异常。

当所有步骤在指定的timeout时间内未完成时，该方法会抛出TimeoutError。传递零超时将禁用此功能。

用法

element_handle.set_checked(checked)
element_handle.set_checked(checked, **kwargs)

参数

• checked bool#

  是否勾选或取消勾选该复选框。

• force bool (可选)#

  是否绕过actionability检查。默认为false。

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• position Dict (可选)#

  • x float

  • y float

  一个相对于元素内边距框左上角使用的点。如果未指定，则使用元素的某个可见点。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• trial bool (可选)#

  当设置时，此方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作而无需实际执行的情况。

返回

• NoneType#

set_input_files​

将文件输入的值设置为这些文件路径或文件。如果某些filePaths是相对路径，则它们会相对于当前工作目录进行解析。对于空数组，会清除已选文件。对于具有[webkitdirectory]属性的输入，仅支持单个目录路径。

该方法期望ElementHandle指向一个input元素。但是，如果该元素位于具有关联control的元素内，则会改为定位到该控件。

用法

element_handle.set_input_files(files)
element_handle.set_input_files(files, **kwargs)

参数

• files Union[str, pathlib.Path] | List[Union[str, pathlib.Path]] | Dict | List[Dict]#

  • name str

    文件名

  • mimeType str

    文件类型

  • buffer bytes

    文件内容

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType#

点击​

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

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

如果在操作过程中元素从DOM中分离，该方法会抛出异常。

当所有步骤在指定的timeout时间内未完成时，该方法会抛出TimeoutError。传递零超时将禁用此功能。

用法

element_handle.tap()
element_handle.tap(**kwargs)

参数

• force bool (可选)#

  是否绕过actionability检查。默认为false。

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

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

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• position Dict (可选)#

  • x float

  • y float

  一个相对于元素内边距框左上角使用的点。如果未指定，则使用元素的某个可见点。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• trial bool (可选) 添加于: v1.11#

  当设置时，此方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作而无需实际执行的情况。

返回

• NoneType#

text_content​

返回 node.textContent。

用法

element_handle.text_content()

返回

• NoneType | str#

类型​

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

要按下特殊键，如Control或ArrowDown，请使用element_handle.press()。

用法

参数

• text str#

  要输入到聚焦元素中的文本。

• delay float (可选参数)#

  按键之间的等待时间，以毫秒为单位。默认为0。

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType#

取消勾选​

该方法通过执行以下步骤来检查元素：

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

如果在操作过程中元素从DOM中分离，该方法会抛出异常。

当所有步骤在指定的timeout时间内未完成时，该方法会抛出TimeoutError。传递零超时将禁用此功能。

用法

element_handle.uncheck()
element_handle.uncheck(**kwargs)

参数

• force bool (可选)#

  是否绕过actionability检查。默认为false。

• no_wait_after bool (可选)#

  已弃用

  此选项无效。

  此选项无效。

• position Dict (可选) 添加于: v1.11#

  • x float

  • y float

  一个相对于元素内边距框左上角使用的点。如果未指定，则使用元素的某个可见点。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

• trial bool (可选) 添加于: v1.11#

  当设置时，此方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作而无需实际执行的情况。

返回

• NoneType#

wait_for_selector​

当元素满足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")

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

参数

• selector str#

  用于查询的选择器。

• state "attached" | "detached" | "visible" | "hidden" (可选)#

  默认为 'visible'。可以是以下任一选项：

  • 'attached' - 等待元素出现在DOM中。
  • 'detached' - 等待元素在DOM中不存在。
  • 'visible' - 等待元素具有非空边界框且不包含visibility:hidden。请注意，没有任何内容或带有display:none的元素具有空边界框，不被视为可见。
  • 'hidden' - 等待元素从DOM中分离，或具有空边界框或visibility:hidden。这与'visible'选项相反。

• strict bool (可选) 添加于: v1.15#

  当为true时，要求选择器必须解析为单个元素。如果给定的选择器解析出多个元素，调用将抛出异常。

• timeout float (可选)#

  最大时间，单位为毫秒。默认为 30000 (30秒)。传入 0 表示禁用超时。默认值可以通过使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法进行修改。

返回

• NoneType | ElementHandle#