Skip to main content

ElementHandle

ElementHandle 表示页内 DOM 元素。ElementHandles 可以使用 page.$(selector[, options]) 方法创建。

Discouraged

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

const hrefElement = await page.$('a');
await hrefElement.click();

ElementHandle 防止 DOM 元素被垃圾回收，除非使用 jsHandle.dispose() 处置句柄。当其源框架导航时，ElementHandles 会自动处置。

ElementHandle 实例可以用作 page.$eval(selector, pageFunction[, arg, options]) 和 page.evaluate(pageFunction[, arg]) 方法中的参数。

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

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

const handle = await page.$('text=Submit');
// ...
await handle.hover();
await handle.click();

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

const locator = page.getByText('Submit');
// ...
await locator.hover();
await locator.click();

elementHandle.$(selector)​

Added in: v1.9

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

elementHandle.$$(selector)​

Added in: v1.9

该方法在 ElementHandle 的子树中查找匹配指定选择器的所有元素。有关更多详细信息，请参阅使用选择器。如果没有元素匹配选择器，则返回空数组。

elementHandle.$eval(selector, pageFunction[, arg])​

Added in: v1.9

返回 pageFunction 的返回值。

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

如果 pageFunction 返回 Promise，则 elementHandle.$eval(selector, pageFunction[, arg]) 将等待 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');

elementHandle.$$eval(selector, pageFunction[, arg])​

Added in: v1.9

返回 pageFunction 的返回值。

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

如果 pageFunction 返回 Promise，则 elementHandle.$$eval(selector, pageFunction[, arg]) 将等待 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!']);

elementHandle.boundingBox()​

Added in: v1.8
  • returns: <Promise<null|Object>>#
    • x <number> 元素的 x 坐标（以像素为单位）。
    • y <number> 元素的 y 坐标（以像素为单位）。
    • width <number> 元素的宽度（以像素为单位）。
    • height <number> 元素的高度（以像素为单位）。

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

elementHandle.check([options])​

Added in: v1.8
  • options? <Object>
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • position? <Object> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。Added in: v1.11#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待元素准备好进行操作而不执行操作。Added in: v1.11#
  • returns: <Promise<void>>#

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

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

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

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

elementHandle.click([options])​

Added in: v1.8
  • options? <Object>
    • button? <"left"|"right"|"middle"> 默认为 left。#
    • clickCount? <number> 默认为 1。请参阅 UIEvent.detail。#
    • delay? <number> mousedown 和 mouseup 之间等待的时间（以毫秒为单位）。默认为 0。#
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要按下的修饰键。确保在操作期间仅按下这些修饰符，然后恢复当前修饰符。如果未指定，则使用当前按下的修饰符。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • position? <Object> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待元素准备好进行操作而不执行操作。Added in: v1.11#
  • returns: <Promise<void>>#

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

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

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

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

elementHandle.contentFrame()​

Added in: v1.8

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

elementHandle.dblclick([options])​

Added in: v1.8
  • options? <Object>
    • button? <"left"|"right"|"middle"> 默认为 left。#
    • delay? <number> mousedown 和 mouseup 之间等待的时间（以毫秒为单位）。默认为 0。#
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要按下的修饰键。确保在操作期间仅按下这些修饰符，然后恢复当前修饰符。如果未指定，则使用当前按下的修饰符。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • position? <Object> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待元素准备好进行操作而不执行操作。Added in: v1.11#
  • returns: <Promise<void>>#

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

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

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

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

note

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

elementHandle.dispatchEvent(type[, eventInit])​

Added in: v1.8

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

await elementHandle.dispatchEvent('click');

在底层，它根据给定的 type 创建一个事件实例，使用 eventInit 属性对其进行初始化，并在元素上分发它。事件默认是 composed、cancelable 和冒泡的。

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

如果你希望将活动对象传递给事件，也可以将 JSHandle 指定为属性值：

// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await elementHandle.dispatchEvent('dragstart', { dataTransfer });

elementHandle.fill(value[, options])​

Added in: v1.8
  • value <string> 要为 <input>、<textarea> 或 [contenteditable] 元素设置的值。#
  • options? <Object>
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。 Added in: v1.13#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
  • returns: <Promise<void>>#

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

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

要发送细粒度的键盘事件，请使用 elementHandle.type(text[, options])。

elementHandle.focus()​

Added in: v1.8

在元素上调用 focus。

elementHandle.getAttribute(name)​

Added in: v1.8

返回元素属性值。

elementHandle.hover([options])​

Added in: v1.8
  • options? <Object>
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要按下的修饰键。确保在操作期间仅按下这些修饰符，然后恢复当前修饰符。如果未指定，则使用当前按下的修饰符。#
    • position? <Object> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待元素准备好进行操作而不执行操作。Added in: v1.11#
  • returns: <Promise<void>>#

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

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

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

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

elementHandle.innerHTML()​

Added in: v1.8

返回 element.innerHTML。

elementHandle.innerText()​

Added in: v1.8

返回 element.innerText。

elementHandle.inputValue([options])​

Added in: v1.13

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

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

elementHandle.isChecked()​

Added in: v1.8

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

elementHandle.isDisabled()​

Added in: v1.8

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

elementHandle.isEditable()​

Added in: v1.8

返回元素是否 可编辑。

elementHandle.isEnabled()​

Added in: v1.8

返回元素是否 启用。

elementHandle.isHidden()​

Added in: v1.8

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

elementHandle.isVisible()​

Added in: v1.8

返回元素是否 可见。

elementHandle.ownerFrame()​

Added in: v1.8

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

elementHandle.press(key[, options])​

Added in: v1.8
  • key <string> 要按下的键名或要生成的字符，例如 ArrowLeft 或 a。#
  • options? <Object>
    • delay? <number> keydown 和 keyup 之间等待的时间（以毫秒为单位）。默认为 0。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
  • returns: <Promise<void>> 聚焦元素，然后使用 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 等。

也支持以下修改快捷键：Shift, Control, Alt, Meta, ShiftLeft。

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

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

也支持 key: "Control+o" 或 key: "Control+Shift+T" 等快捷键。当使用修饰符指定时，修饰符被按下并保持，同时按下后续键。

elementHandle.screenshot([options])​

Added in: v1.8

  • options? <Object>

    • animations? <"disabled"|"allow"> 当设置为 "disabled" 时，停止 CSS 动画、CSS 过渡和 Web 动画。根据动画的持续时间，动画会得到不同的处理：#

      • 有限动画快进到完成，因此它们将触发 transitionend 事件。
      • 无限动画取消到初始状态，然后在截图后重新播放。

      默认为 "allow"，保持动画不变。#

    • caret? <"hide"|"initial"> 当设置为 "hide" 时，截图将隐藏文本插入符号。当设置为 "initial" 时，文本插入符号行为将不会更改。默认为 "hide"。#

    • mask? <Array<Locator>> 指定截图时应遮罩的定位器。被遮罩的元素将被粉红色框 #FF00FF 覆盖，完全覆盖其边界框。#

    • omitBackground? <boolean> 隐藏默认的白色背景，并允许捕获具有透明度的截图。不适用于 jpeg 图像。默认为 false。#

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

    • quality? <number> 图像质量，介于 0-100 之间。不适用于 png 图像。#

    • scale? <"css"|"device"> 当设置为 "css" 时，截图将在页面上的每个 css 像素对应一个像素。对于高 dpi 设备，这将使截图保持较小。使用 "device" 选项将为每个设备像素生成一个像素，因此高 dpi 设备的截图将大两倍甚至更大。#

      默认为 "device"。

    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#

    • type? <"png"|"jpeg"> 指定截图类型，默认为 png。#

  • returns: <Promise<Buffer>>#

此方法捕获页面的截图，剪裁到此特定元素的大小和位置。如果元素被其他元素覆盖，则在截图中实际上不可见。如果元素是可滚动容器，则只有当前滚动的内容在截图中可见。

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

返回捕获的截图的缓冲区。

elementHandle.scrollIntoViewIfNeeded([options])​

Added in: v1.8

此方法等待 actionability 检查，然后尝试将元素滚动到视图中，除非它根据 IntersectionObserver 的 ratio 定义完全可见。

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

elementHandle.selectOption(values[, options])​

Added in: v1.8
  • values <null|string|ElementHandle|Array<string>|Object|Array<ElementHandle>|Array<Object>> 要选择的选项。如果 <select> 具有 multiple 属性，则选择所有匹配的选项，否则仅选择匹配传递选项之一的第一个选项。字符串值等效于 {value:'string'}。如果所有指定属性都匹配，则认为选项匹配。#
    • value? <string> 通过 option.value 匹配。可选。
    • label? <string> 通过 option.label 匹配。可选。
    • index? <number> 通过索引匹配。可选。
  • options? <Object>
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。 Added in: v1.13#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
  • returns: <Promise<Array<string>>>#

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

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

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

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

// single selection matching the value
handle.selectOption('blue');

// single selection matching the label
handle.selectOption({ label: 'Blue' });

// multiple selection
handle.selectOption(['red', 'green', 'blue']);

elementHandle.selectText([options])​

Added in: v1.8

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

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

elementHandle.setChecked(checked[, options])​

Added in: v1.15
  • checked <boolean> 是否选中或取消选中复选框。#
  • options? <Object>
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • position? <Object> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待元素准备好进行操作而不执行操作。#
  • returns: <Promise<void>>#

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

  1. 确保元素是复选框或单选输入。如果不是，此方法将抛出错误。
  2. 如果元素已经具有正确的选中状态，此方法将立即返回。
  3. 等待匹配元素上的 actionability 检查，除非设置了 force 选项。如果在检查期间元素分离，则重试整个操作。
  4. 如果需要，将元素滚动到视图中。
  5. 使用 page.mouse 单击元素的中心。
  6. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。
  7. 确保元素现在已选中或取消选中。如果不是，此方法将抛出错误。

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

elementHandle.setInputFiles(files[, options])​

Added in: v1.8

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

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

elementHandle.tap([options])​

Added in: v1.8
  • options? <Object>
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要按下的修饰键。确保在操作期间仅按下这些修饰符，然后恢复当前修饰符。如果未指定，则使用当前按下的修饰符。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • position? <Object> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待元素准备好进行操作而不执行操作。Added in: v1.11#
  • returns: <Promise<void>>#

此方法通过执行以下步骤轻触元素：

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

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

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

note

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

elementHandle.textContent()​

Added in: v1.8

返回 node.textContent。

elementHandle.type(text[, options])​

Added in: v1.8
  • text <string> 要输入到聚焦元素的文本。#
  • options? <Object>
    • delay? <number> 按键之间等待的时间（以毫秒为单位）。默认为 0。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
  • returns: <Promise<void>>#

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

要按特殊键，如 Control 或 ArrowDown，请使用 elementHandle.press(key[, options])。

await elementHandle.type('Hello'); // Types instantly
await elementHandle.type('World', {delay: 100}); // Types slower, like a user

输入文本字段然后提交表单的示例：

const elementHandle = await page.$('input');
await elementHandle.type('some text');
await elementHandle.press('Enter');

elementHandle.uncheck([options])​

Added in: v1.8
  • options? <Object>
    • force? <boolean> 是否绕过 actionability 检查。默认为 false。#
    • noWaitAfter? <boolean> 启动导航的操作将等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（例如导航到无法访问的页面）才需要此选项。默认为 false。#
    • position? <Object> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。 Added in: v1.11#
    • timeout? <number> 最长等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待元素准备好进行操作而不执行操作。Added in: v1.11#
  • returns: <Promise<void>>#

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

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

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

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

elementHandle.waitForElementState(state[, options])​

Added in: v1.8

当元素满足 state 时返回。

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

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

elementHandle.waitForSelector(selector[, options])​

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

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

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

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' });
note

此方法不适用于导航，请改用 page.waitForSelector(selector[, options])。