ElementHandle
- 继承自: JSHandle
ElementHandle 代表页面中的 DOM 元素。ElementHandle 可以通过 page.$() 方法创建。
不鼓励使用 ElementHandle,请改用 Locator 对象和 web-first 断言。
const hrefElement = await page.$('a');
await hrefElement.click();
ElementHandle 阻止 DOM 元素被垃圾回收,除非使用 jsHandle.dispose() 释放句柄。当 ElementHandle 的原始帧被导航时,它会自动释放。
ElementHandle 实例可用作 page.$eval() 和 page.evaluate() 方法的参数。
Locator 和 ElementHandle 的区别在于 ElementHandle 指向一个特定的元素,而 Locator 捕获了如何检索元素的逻辑。
在下面的示例中,handle 指向页面上一个特定的 DOM 元素。如果该元素更改文本或被 React 用于渲染一个完全不同的组件,handle 仍然指向该 DOM 元素。这可能导致意外的行为。
const handle = await page.$('text=Submit');
// ...
await handle.hover();
await handle.click();
使用 locator,每次使用 element
时,都会使用选择器在页面中定位最新的 DOM 元素。因此在下面的代码片段中,底层 DOM 元素将被定位两次。
const locator = page.getByText('Submit');
// ...
await locator.hover();
await locator.click();
方法
boundingBox
v1.9 之前添加此方法返回元素的边界框,如果元素不可见,则返回 null
。边界框是相对于主帧视口计算的,主帧视口通常与浏览器窗口相同。
滚动会影响返回的边界框,类似于 Element.getBoundingClientRect。这意味着 x
和/或 y
可能为负。
子帧中的元素返回相对于主帧的边界框,与 Element.getBoundingClientRect 不同。
假设页面是静态的,使用边界框坐标执行输入是安全的。例如,以下代码片段应该单击元素的中心。
用法
const box = await elementHandle.boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
返回
contentFrame
v1.9 之前添加对于引用 iframe 节点的元素句柄,返回内容帧,否则返回 null
。
用法
await elementHandle.contentFrame();
返回
ownerFrame
v1.9 之前添加返回包含给定元素的帧。
用法
await elementHandle.ownerFrame();
返回
waitForElementState
v1.9 之前添加当元素满足 state 时返回。
根据 state 参数,此方法等待其中一项 可操作性 检查通过。此方法在等待时元素分离会抛出异常,除非等待 "hidden"
状态。
"visible"
等待直到元素 可见。"hidden"
等待直到元素 不可见 或未附加。请注意,等待隐藏时,元素分离不会抛出异常。"stable"
等待直到元素既 可见 又 稳定。"enabled"
等待直到元素 启用。"disabled"
等待直到元素 未启用。"editable"
等待直到元素 可编辑。
如果元素在 timeout 毫秒内不满足条件,此方法将抛出异常。
用法
await elementHandle.waitForElementState(state);
await elementHandle.waitForElementState(state, options);
参数
-
state
"visible" | "hidden" | "stable" | "enabled" | "disabled" | "editable"#要等待的状态,更多详情见下文。
-
options
Object (可选)-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
已弃用
$
添加于:v1.9请改用基于定位器的 page.locator()。阅读更多关于 定位器 的信息。
此方法在 ElementHandle
的子树中查找与指定选择器匹配的元素。如果没有元素匹配选择器,则返回 null
。
用法
await elementHandle.$(selector);
参数
返回
$$
添加于:v1.9请改用基于定位器的 page.locator()。阅读更多关于 定位器 的信息。
此方法在 ElementHandle
的子树中查找所有与指定选择器匹配的元素。如果没有元素匹配选择器,则返回空数组。
用法
await elementHandle.$$(selector);
参数
返回
$eval
添加于:v1.9此方法不等待元素通过可操作性检查,因此可能导致测试不稳定。请改用 locator.evaluate()、其他 Locator 辅助方法或 web-first 断言。
返回 pageFunction 的返回值。
此方法在 ElementHandle
的子树中查找与指定选择器匹配的元素,并将其作为第一个参数传递给 pageFunction。如果没有元素匹配选择器,该方法将抛出错误。
如果 pageFunction 返回一个 Promise,那么 elementHandle.$eval() 将等待 Promise 解决并返回其值。
用法
const tweetHandle = await page.$('.tweet');
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
参数
-
要查询的选择器。
-
pageFunction
函数(Element) | 字符串#要在页面上下文中执行的函数。
-
arg
EvaluationArgument (可选)#可选参数,用于传递给 pageFunction。
返回
$$eval
添加于:v1.9在大多数情况下,locator.evaluateAll()、其他 Locator 辅助方法和 web-first 断言做得更好。
返回 pageFunction 的返回值。
此方法在 ElementHandle
的子树中查找所有与指定选择器匹配的元素,并将其匹配的元素数组作为第一个参数传递给 pageFunction。
如果 pageFunction 返回一个 Promise,那么 elementHandle.$$eval() 将等待 Promise 解决并返回其值。
用法
<div class="feed">
<div class="tweet">Hello!</div>
<div class="tweet">Hi!</div>
</div>
const feedHandle = await page.$('.feed');
expect(await feedHandle.$$eval('.tweet', nodes =>
nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!'],
);
参数
-
要查询的选择器。
-
pageFunction
函数(数组<Element>) | 字符串#要在页面上下文中执行的函数。
-
arg
EvaluationArgument (可选)#可选参数,用于传递给 pageFunction。
返回
check
v1.9 之前添加请改用基于定位器的 locator.check()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤检查元素
- 确保元素是复选框或单选输入。如果不是,此方法将抛出异常。如果元素已选中,此方法将立即返回。
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 单击元素的中心。
- 确保元素现在已选中。如果不是,此方法将抛出异常。
如果在操作期间元素从 DOM 分离,此方法将抛出异常。
如果在指定 timeout 期间所有步骤都没有完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
用法
await elementHandle.check();
await elementHandle.check(options);
参数
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查,并跳过操作。默认为
false
。在不执行操作的情况下,等待元素准备好进行操作很有用。
-
返回
click
v1.9 之前添加请改用基于定位器的 locator.click()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤单击元素
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 单击元素的中心或指定的 position。
- 等待已启动的导航成功或失败,除非设置了 noWaitAfter 选项。
如果在操作期间元素从 DOM 分离,此方法将抛出异常。
如果在指定 timeout 期间所有步骤都没有完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
用法
await elementHandle.click();
await elementHandle.click(options);
参数
options
Object (可选)-
button
"left" | "right" | "middle" (可选)#默认为
left
。 -
默认为 1。参见 UIEvent.detail。
-
mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
数组<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项将来默认为
true
。发起导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择不等待。只有在特殊情况下(例如导航到无法访问的页面)才需要此选项。默认为
false
。 -
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查,并跳过操作。默认为
false
。在不执行操作的情况下,等待元素准备好进行操作很有用。
-
返回
dblclick
v1.9 之前添加请改用基于定位器的 locator.dblclick()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤双击元素
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 双击元素的中心或指定的 position。
如果在操作期间元素从 DOM 分离,此方法将抛出异常。
如果在指定 timeout 期间所有步骤都没有完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
elementHandle.dblclick()
会分派两次 click
事件和一次 dblclick
事件。
用法
await elementHandle.dblclick();
await elementHandle.dblclick(options);
参数
options
Object (可选)-
button
"left" | "right" | "middle" (可选)#默认为
left
。 -
mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
数组<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查,并跳过操作。默认为
false
。在不执行操作的情况下,等待元素准备好进行操作很有用。
-
返回
dispatchEvent
v1.9 之前添加请改用基于定位器的 locator.dispatchEvent()。阅读更多关于 定位器 的信息。
以下代码片段在元素上分派 click
事件。无论元素可见性状态如何,都会分派 click
。这相当于调用 element.click()。
用法
await elementHandle.dispatchEvent('click');
在底层,它根据给定的 type 创建一个事件实例,用 eventInit 属性初始化它,并在元素上分派它。事件默认是 composed
、cancelable
和冒泡的。
由于 eventInit 是事件特定的,请参阅事件文档以获取初始属性列表
- DeviceMotionEvent
- DeviceOrientationEvent
- DragEvent
- Event
- FocusEvent
- KeyboardEvent
- MouseEvent
- PointerEvent
- TouchEvent
- WheelEvent
您还可以指定 JSHandle
作为属性值,如果您希望将实时对象传递到事件中
// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await elementHandle.dispatchEvent('dragstart', { dataTransfer });
参数
-
DOM 事件类型:
"click"
、"dragstart"
等。 -
eventInit
EvaluationArgument (可选)#可选的事件特定初始化属性。
返回
fill
v1.9 之前添加请改用基于定位器的 locator.fill()。阅读更多关于 定位器 的信息。
此方法等待 可操作性 检查,聚焦元素,填充它,并在填充后触发 input
事件。请注意,您可以传递空字符串以清除输入字段。
如果目标元素不是 <input>
、<textarea>
或 [contenteditable]
元素,此方法将抛出错误。但是,如果元素位于具有关联 control 的 <label>
元素内,则将填充该 control。
要发送细粒度的键盘事件,请使用 locator.pressSequentially()。
用法
await elementHandle.fill(value);
await elementHandle.fill(value, options);
参数
-
要为
<input>
、<textarea>
或[contenteditable]
元素设置的值。 -
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
focus
v1.9 之前添加请改用基于定位器的 locator.focus()。阅读更多关于 定位器 的信息。
调用元素上的 focus。
用法
await elementHandle.focus();
返回
getAttribute
v1.9 之前添加请改用基于定位器的 locator.getAttribute()。阅读更多关于 定位器 的信息。
返回元素属性值。
用法
await elementHandle.getAttribute(name);
参数
返回
hover
v1.9 之前添加请改用基于定位器的 locator.hover()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤将鼠标悬停在元素上
- 等待对元素进行 可操作性 检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 将鼠标悬停在元素的中心或指定的 position 上。
如果在操作期间元素从 DOM 分离,此方法将抛出异常。
如果在指定 timeout 期间所有步骤都没有完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
用法
await elementHandle.hover();
await elementHandle.hover(options);
参数
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
数组<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
noWaitAfter
布尔值 (可选)新增于: v1.28#已弃用此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查,并跳过操作。默认为
false
。在不执行操作的情况下,等待元素准备好进行操作很有用。
-
返回
innerHTML
v1.9 之前添加请改用基于定位器的 locator.innerHTML()。阅读更多关于 定位器 的信息。
返回 element.innerHTML
。
用法
await elementHandle.innerHTML();
返回
innerText
v1.9 之前添加请改用基于定位器的 locator.innerText()。阅读更多关于 定位器 的信息。
返回 element.innerText
。
用法
await elementHandle.innerText();
返回
inputValue
添加于:v1.13请改用基于定位器的 locator.inputValue()。阅读更多关于 定位器 的信息。
返回选定的 <input>
、<textarea>
或 <select>
元素的 input.value
。
对非输入元素抛出异常。但是,如果元素位于具有关联 control 的 <label>
元素内,则返回 control 的值。
用法
await elementHandle.inputValue();
await elementHandle.inputValue(options);
参数
options
Object (可选)-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
isChecked
v1.9 之前添加请改用基于定位器的 locator.isChecked()。阅读更多关于 定位器 的信息。
返回元素是否已选中。如果元素不是复选框或单选输入,则抛出异常。
用法
await elementHandle.isChecked();
返回
isDisabled
v1.9 之前添加请改用基于定位器的 locator.isDisabled()。阅读更多关于 定位器 的信息。
返回元素是否已禁用,与 启用 相反。
用法
await elementHandle.isDisabled();
返回
isEditable
v1.9 之前添加请改用基于定位器的 locator.isEditable()。阅读更多关于 定位器 的信息。
返回元素是否 可编辑。
用法
await elementHandle.isEditable();
返回
isEnabled
v1.9 之前添加请改用基于定位器的 locator.isEnabled()。阅读更多关于 定位器 的信息。
返回元素是否 启用。
用法
await elementHandle.isEnabled();
返回
isHidden
v1.9 之前添加请改用基于定位器的 locator.isHidden()。阅读更多关于 定位器 的信息。
返回元素是否隐藏,与 可见 相反。
用法
await elementHandle.isHidden();
返回
isVisible
v1.9 之前添加请改用基于定位器的 locator.isVisible()。阅读更多关于 定位器 的信息。
返回元素是否 可见。
用法
await elementHandle.isVisible();
返回
press
v1.9 之前添加请改用基于定位器的 locator.press()。阅读更多关于 定位器 的信息。
聚焦元素,然后使用 keyboard.down() 和 keyboard.up()。
key 可以指定预期的 keyboardEvent.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"
。当与修饰符一起指定时,修饰符在按下后续键时被按下并保持。
用法
await elementHandle.press(key);
await elementHandle.press(key, options);
参数
-
要按下的键的名称或要生成的字符,例如
ArrowLeft
或a
。 -
options
Object (可选)-
keydown
和keyup
之间等待的时间(毫秒)。默认为 0。 -
已弃用
此选项将来默认为
true
。发起导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择不等待。只有在特殊情况下(例如导航到无法访问的页面)才需要此选项。默认为
false
。 -
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
screenshot
v1.9 之前添加请改用基于定位器的 locator.screenshot()。阅读更多关于 定位器 的信息。
此方法捕获页面截图,裁剪到此特定元素的大小和位置。如果元素被其他元素覆盖,它将不会实际显示在截图中。如果元素是可滚动容器,则只有当前滚动的内容才会显示在截图中。
此方法等待 可操作性 检查,然后将元素滚动到视图中,然后截取屏幕截图。如果元素从 DOM 分离,此方法将抛出错误。
返回包含捕获的屏幕截图的缓冲区。
用法
await elementHandle.screenshot();
await elementHandle.screenshot(options);
参数
options
Object (可选)-
animations
"disabled" | "allow" (可选)#设置为
"disabled"
时,停止 CSS 动画、CSS 过渡和 Web 动画。动画的处理方式因其持续时间而异- 有限动画会快进到完成,因此它们会触发
transitionend
事件。 - 无限动画会取消到初始状态,然后在截图后重新播放。
默认为
"allow"
,保持动画不变。 - 有限动画会快进到完成,因此它们会触发
-
caret
"hide" | "initial" (可选)#设置为
"hide"
时,截图将隐藏文本插入符号。设置为"initial"
时,文本插入符号行为不会更改。默认为"hide"
。 -
指定截图时应遮盖的定位器。被遮盖的元素将被覆盖一个粉红色方框
#FF00FF
(可通过 maskColor 自定义),完全覆盖其边界框。遮盖也适用于不可见元素,请参阅 仅匹配可见元素 以禁用此功能。 -
指定遮盖元素的覆盖框颜色,采用 CSS 颜色格式。默认颜色为粉红色
#FF00FF
。 -
隐藏默认的白色背景并允许捕获透明截图。不适用于
jpeg
图像。默认为false
。 -
保存图像的文件路径。截图类型将从文件扩展名推断。如果 path 是相对路径,则它相对于当前工作目录解析。如果未提供路径,则图像不会保存到磁盘。
-
图像质量,介于 0-100 之间。不适用于
png
图像。 -
scale
"css" | "device" (可选)#设置为
"css"
时,截图在页面上每个 css 像素对应一个物理像素。对于高 DPI 设备,这会使截图较小。使用"device"
选项会为每个设备像素生成一个物理像素,因此高 DPI 设备的截图会大一倍甚至更大。默认为
"device"
。 -
制作截图时应用的样式表文本。您可以在此处隐藏动态元素,使元素不可见或更改其属性以帮助您创建可重复的截图。此样式表会穿透 Shadow DOM 并应用于内部帧。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
type
"png" | "jpeg" (可选)#指定截图类型,默认为
png
。
-
返回
scrollIntoViewIfNeeded
v1.9 之前添加请改用基于定位器的 locator.scrollIntoViewIfNeeded()。阅读更多关于 定位器 的信息。
此方法等待 可操作性 检查,然后尝试将元素滚动到视图中,除非它根据 IntersectionObserver 的 ratio
定义完全可见。
当 elementHandle
不指向与文档或 ShadowRoot 连接 的元素时,抛出异常。
有关其他滚动方式,请参阅 滚动。
用法
await elementHandle.scrollIntoViewIfNeeded();
await elementHandle.scrollIntoViewIfNeeded(options);
参数
options
Object (可选)-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
selectOption
v1.9 之前添加请改用基于定位器的 locator.selectOption()。阅读更多关于 定位器 的信息。
此方法等待 可操作性 检查,等待所有指定选项出现在 <select>
元素中并选择这些选项。
如果目标元素不是 <select>
元素,此方法将抛出错误。但是,如果元素位于具有关联 control 的 <label>
元素内,则将使用该 control。
返回已成功选择的选项值数组。
一旦所有提供的选项都已选中,将触发 change
和 input
事件。
用法
// Single selection matching the value or label
handle.selectOption('blue');
// single selection matching the label
handle.selectOption({ label: 'Blue' });
// multiple selection
handle.selectOption(['red', 'green', 'blue']);
参数
-
values
null | 字符串 | ElementHandle | 数组<字符串> | 对象 | 数组<ElementHandle> | 数组<对象>#要选择的选项。如果
<select>
具有multiple
属性,则选择所有匹配的选项,否则只选择与传入选项之一匹配的第一个选项。字符串值同时匹配值和标签。如果所有指定属性都匹配,则认为选项匹配。 -
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
selectText
v1.9 之前添加请改用基于定位器的 locator.selectText()。阅读更多关于 定位器 的信息。
此方法等待 可操作性 检查,然后聚焦元素并选择其所有文本内容。
如果元素位于具有关联 control 的 <label>
元素内,则聚焦并选择 control 中的文本。
用法
await elementHandle.selectText();
await elementHandle.selectText(options);
参数
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
setChecked
添加于:v1.15请改用基于定位器的 locator.setChecked()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤选中或取消选中元素
- 确保元素是复选框或单选输入。如果不是,此方法将抛出异常。
- 如果元素已经处于正确的选中状态,此方法将立即返回。
- 等待对匹配元素进行 可操作性 检查,除非设置了 force 选项。如果在检查期间元素分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 单击元素的中心。
- 确保元素现在已选中或未选中。如果不是,此方法将抛出异常。
如果在指定 timeout 期间所有步骤都没有完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
用法
await elementHandle.setChecked(checked);
await elementHandle.setChecked(checked, options);
参数
-
是否选中或取消选中复选框。
-
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查,并跳过操作。默认为
false
。在不执行操作的情况下,等待元素准备好进行操作很有用。
-
返回
setInputFiles
v1.9 之前添加请改用基于定位器的 locator.setInputFiles()。阅读更多关于 定位器 的信息。
将文件输入的当前值设置为这些文件路径或文件。如果某些 filePaths
是相对路径,则它们将相对于当前工作目录进行解析。对于空数组,清除选定的文件。对于具有 [webkitdirectory]
属性的输入,仅支持单个目录路径。
此方法期望 ElementHandle 指向一个 input 元素。但是,如果该元素位于具有关联 控件 的 <label>
元素内,则目标为该控件。
用法
await elementHandle.setInputFiles(files);
await elementHandle.setInputFiles(files, options);
参数
files
string | Array<string> | Object | Array<Object>#options
Object (可选)-
已弃用
此选项无效。
此选项无效。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
tap
v1.9 之前添加请改用基于定位器的 locator.tap()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤来点击元素
- 等待对元素执行可操作性检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.touchscreen 点击元素的中心,或指定的 position。
如果在操作期间元素从 DOM 分离,此方法将抛出异常。
如果所有步骤在指定的 timeout 期间未完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
elementHandle.tap()
要求浏览器上下文的 hasTouch
选项设置为 true。
用法
await elementHandle.tap();
await elementHandle.tap(options);
参数
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查,并跳过操作。默认为
false
。在不执行操作的情况下,等待元素准备好进行操作很有用。
-
返回
textContent
v1.9 之前添加请改用基于定位器的 locator.textContent()。阅读更多关于 定位器 的信息。
返回 node.textContent
。
用法
await elementHandle.textContent();
返回
type
v1.9 之前添加在大多数情况下,您应该使用 locator.fill()。仅当页面上有特殊的键盘处理时,您才需要一个一个地按下按键 - 在这种情况下,请使用 locator.pressSequentially()。
聚焦元素,然后为文本中的每个字符发送一个 keydown
、keypress
/input
和 keyup
事件。
要按特殊键,例如 Control
或 ArrowDown
,请使用 elementHandle.press()。
用法
参数
-
要输入到聚焦元素的文本。
-
options
Object (可选)-
按键之间等待的时间,以毫秒为单位。默认为 0。
-
已弃用
此选项无效。
此选项无效。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回
uncheck
v1.9 之前添加请改用基于定位器的 locator.uncheck()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤检查元素
- 确保元素是复选框或单选输入。如果不是,此方法将抛出异常。如果元素已经未选中,此方法将立即返回。
- 等待对元素执行可操作性检查,除非设置了 force 选项。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 单击元素的中心。
- 确保元素现在未选中。如果不是,此方法将抛出异常。
如果在操作期间元素从 DOM 分离,此方法将抛出异常。
如果所有步骤在指定的 timeout 期间未完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
用法
await elementHandle.uncheck();
await elementHandle.uncheck(options);
参数
options
Object (可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查,并跳过操作。默认为
false
。在不执行操作的情况下,等待元素准备好进行操作很有用。
-
返回
waitForSelector
v1.9 之前添加请改用断言可见性的 Web 断言或基于定位器的 locator.waitFor()。
当选择器满足 state 选项时,返回由选择器指定的元素。如果等待 hidden
或 detached
,则返回 null
。
等待相对于元素句柄的 选择器 满足 state 选项(要么在 DOM 中出现/消失,要么变为可见/隐藏)。如果在调用方法时 选择器 已经满足条件,则该方法将立即返回。如果选择器在 超时 毫秒内不满足条件,则该函数将抛出异常。
用法
await page.setContent(`<div><span></span></div>`);
const div = await page.$('div');
// Waiting for the 'span' selector relative to the div.
const span = await div.waitForSelector('span', { state: 'attached' });
此方法不适用于跨导航,请改用 page.waitForSelector()。
参数
-
要查询的选择器。
-
options
Object (可选)-
state
"attached" | "detached" | "visible" | "hidden" (可选)#默认为
'visible'
。可以是以下之一:'attached'
- 等待元素出现在 DOM 中。'detached'
- 等待元素不在 DOM 中。'visible'
- 等待元素具有非空的边界框且没有visibility:hidden
。请注意,没有任何内容或具有display:none
的元素具有空的边界框,不被视为可见。'hidden'
- 等待元素从 DOM 中分离,或具有空的边界框或visibility:hidden
。这与'visible'
选项相反。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素,则调用将抛出异常。
-
最大等待时间(毫秒)。默认为
0
- 无超时。默认值可以通过配置中的actionTimeout
选项更改,或通过使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
-
返回