ElementHandle

расширяет: JSHandle

ElementHandle представляет собой элемент DOM на странице. ElementHandles могут быть созданы с помощью метода Page.querySelector().

Не рекомендуется

Использование ElementHandle не рекомендуется, вместо этого используйте объекты Locator и утверждения, ориентированные на веб.

ElementHandle hrefElement = page.querySelector("a");
hrefElement.click();

ElementHandle предотвращает сборку мусора для DOM-элемента, если только дескриптор не будет удален с помощью JSHandle.dispose(). ElementHandles автоматически удаляются, когда их исходный фрейм переходит на другую страницу.

Экземпляры ElementHandle могут использоваться в качестве аргумента в методах Page.evalOnSelector() и Page.evaluate().

Разница между Locator и ElementHandle заключается в том, что ElementHandle указывает на конкретный элемент, в то время как Locator захватывает логику того, как получить элемент.

В примере ниже дескриптор указывает на конкретный DOM-элемент на странице. Если этот элемент изменяет текст или используется React для рендеринга совершенно другого компонента, дескриптор все равно указывает на этот самый DOM-элемент. Это может привести к неожиданным поведениям.

ElementHandle handle = page.querySelector("text=Submit");
handle.hover();
handle.click();

С локатором каждый раз, когда используется element, актуальный DOM-элемент находится на странице с использованием селектора. Таким образом, в приведенном ниже фрагменте подлежащий DOM-элемент будет найден дважды.

Locator locator = page.getByText("Submit");
locator.hover();
locator.click();

Методы

boundingBox

Добавлено до v1.9

elementHandle.boundingBox

Этот метод возвращает ограничивающий прямоугольник элемента или null, если элемент не виден. Ограничивающий прямоугольник рассчитывается относительно области просмотра основного фрейма, которая обычно совпадает с окном браузера.

Прокрутка влияет на возвращаемый ограничивающий прямоугольник, аналогично Element.getBoundingClientRect. Это означает, что x и/или y могут быть отрицательными.

Элементы из дочерних фреймов возвращают ограничивающий прямоугольник относительно основного фрейма, в отличие от Element.getBoundingClientRect.

Предполагая, что страница статична, безопасно использовать координаты ограничивающего прямоугольника для выполнения ввода. Например, следующий фрагмент должен кликнуть в центр элемента.

Использование

BoundingBox box = elementHandle.boundingBox();
page.mouse().click(box.x + box.width / 2, box.y + box.height / 2);

Возвращает

null | BoundingBox#
- x double
  
  x-координата элемента в пикселях.
- y double
  
  y-координата элемента в пикселях.
- width double
  
  ширина элемента в пикселях.
- height double
  
  высота элемента в пикселях.

contentFrame

Добавлено до v1.9

elementHandle.contentFrame

Возвращает фрейм содержимого для дескрипторов элементов, ссылающихся на узлы iframe, или null в противном случае.

Использование

ElementHandle.contentFrame();

Возвращает

null | Frame #

ownerFrame

Добавлено до v1.9

elementHandle.ownerFrame

Возвращает фрейм, содержащий данный элемент.

Использование

ElementHandle.ownerFrame();

Возвращает

null | Frame #

waitForElementState

Добавлено до v1.9

elementHandle.waitForElementState

Возвращает, когда элемент удовлетворяет state.

В зависимости от параметра state, этот метод ожидает, пока один из проверок actionability не пройдет. Этот метод выбрасывает исключение, когда элемент отсоединяется во время ожидания, если только не ожидается состояние "hidden".

"visible" Ожидание, пока элемент не станет видимым.
"hidden" Ожидание, пока элемент не станет невидимым или не будет отсоединен. Обратите внимание, что ожидание скрытия не выбрасывает исключение, когда элемент отсоединяется.
"stable" Ожидание, пока элемент не станет одновременно видимым и стабильным.
"enabled" Ожидание, пока элемент не станет включенным.
"disabled" Ожидание, пока элемент не станет не включенным.
"editable" Ожидание, пока элемент не станет редактируемым.

Если элемент не удовлетворяет условию в течение setTimeout миллисекунд, этот метод выбрасывает исключение.

Использование

ElementHandle.waitForElementState(state);
ElementHandle.waitForElementState(state, options);

Аргументы

state enum ElementState { VISIBLE, HIDDEN, STABLE, ENABLED, DISABLED, EDITABLE }#

Состояние, которое нужно ожидать, см. ниже для более подробной информации.
options ElementHandle.WaitForElementStateOptions (опционально)
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().

Возвращает

void #

Устаревшие

check

Добавлено до v1.9

elementHandle.check

Не рекомендуется

Используйте основанный на локаторах Locator.check() вместо этого. Подробнее о локаторах.

Этот метод проверяет элемент, выполняя следующие шаги:

Убедитесь, что элемент является флажком или радиокнопкой. Если нет, этот метод выбрасывает исключение. Если элемент уже отмечен, этот метод возвращается немедленно.
Ожидание проверок actionability на элементе, если только не установлен параметр setForce.
Прокрутите элемент в вид, если это необходимо.
Используйте Page.mouse(), чтобы кликнуть в центр элемента.
Убедитесь, что элемент теперь отмечен. Если нет, этот метод выбрасывает исключение.

Если элемент отсоединяется от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Когда все шаги в совокупности не завершены в течение указанного setTimeout, этот метод выбрасывает TimeoutError. Передача нулевого тайм-аута отключает это.

Использование

ElementHandle.check();
ElementHandle.check(options);

Аргументы

options ElementHandle.CheckOptions (опционально)
- setForce boolean (опционально)#
  
  Нужно ли обходить проверки actionability. По умолчанию false.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- setPosition Position (опционально) Добавлено в: v1.11#
  - setX double
  - setY double
  Точка, используемая относительно верхнего левого угла элемента. Если не указано, используется видимая точка элемента.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().
- setTrial boolean (опционально) Добавлено в: v1.11#
  
  Когда установлено, этот метод выполняет только проверки actionability и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения.

Возвращает

void #

click

Добавлено до v1.9

elementHandle.click

Не рекомендуется

Используйте основанный на локаторах Locator.click() вместо этого. Подробнее о локаторах.

Этот метод кликает по элементу, выполняя следующие шаги:

Ожидание проверок actionability на элементе, если только не установлен параметр setForce.
Прокрутите элемент в вид, если это необходимо.
Используйте Page.mouse(), чтобы кликнуть в центр элемента или в указанную setPosition.
Ожидание, пока инициированные навигации либо завершатся успешно, либо потерпят неудачу, если только не установлен параметр setNoWaitAfter.

Если элемент отсоединяется от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Использование

ElementHandle.click();
ElementHandle.click(options);

Аргументы

options ElementHandle.ClickOptions (опционально)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (опционально)#
  
  По умолчанию left.
- setClickCount int (опционально)#
  
  по умолчанию 1. См. UIEvent.detail.
- setDelay double (опционально)#
  
  Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
- setForce boolean (опционально)#
  
  Нужно ли обходить проверки actionability. По умолчанию false.
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (опционально)#
  
  Модификаторные клавиши для нажатия. Гарантирует, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы обратно. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается в "Control" на Windows и Linux и в "Meta" на macOS.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Этот параметр по умолчанию будет true в будущем.
  
  Действия, инициирующие навигации, ожидают, пока эти навигации не произойдут и страницы не начнут загружаться. Вы можете отказаться от ожидания, установив этот флаг. Вам понадобится этот параметр только в исключительных случаях, таких как навигация на недоступные страницы. По умолчанию false.
- setPosition Position (опционально)#
  - setX double
  - setY double
  Точка, используемая относительно верхнего левого угла элемента. Если не указано, используется видимая точка элемента.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().
- setTrial boolean (опционально) Добавлено в: v1.11#
  
  Когда установлено, этот метод выполняет только проверки actionability и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения.

Возвращает

void #

dblclick

Добавлено до v1.9

elementHandle.dblclick

Не рекомендуется

Используйте основанный на локаторах Locator.dblclick() вместо этого. Подробнее о локаторах.

Этот метод выполняет двойной клик по элементу, выполняя следующие шаги:

Ожидание проверок actionability на элементе, если только не установлен параметр setForce.
Прокрутите элемент в вид, если это необходимо.
Используйте Page.mouse(), чтобы выполнить двойной клик в центр элемента или в указанную setPosition.

Если элемент отсоединяется от DOM в любой момент во время действия, этот метод выбрасывает исключение.

примечание

elementHandle.dblclick() генерирует два события click и одно событие dblclick.

Использование

ElementHandle.dblclick();
ElementHandle.dblclick(options);

Аргументы

options ElementHandle.DblclickOptions (опционально)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (опционально)#
  
  По умолчанию left.
- setDelay double (опционально)#
  
  Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
- setForce boolean (опционально)#
  
  Нужно ли обходить проверки actionability. По умолчанию false.
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (опционально)#
  
  Модификаторные клавиши для нажатия. Гарантирует, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы обратно. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается в "Control" на Windows и Linux и в "Meta" на macOS.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- setPosition Position (опционально)#
  - setX double
  - setY double
  Точка, используемая относительно верхнего левого угла элемента. Если не указано, используется видимая точка элемента.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().
- setTrial boolean (опционально) Добавлено в: v1.11#
  
  Когда установлено, этот метод выполняет только проверки actionability и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения.

Возвращает

void #

dispatchEvent

Добавлено до v1.9

elementHandle.dispatchEvent

Не рекомендуется

Используйте основанный на локаторах Locator.dispatchEvent() вместо этого. Подробнее о локаторах.

Приведенный ниже фрагмент генерирует событие click на элементе. Независимо от состояния видимости элемента, click генерируется. Это эквивалентно вызову element.click().

Использование

elementHandle.dispatchEvent("click");

Внутри создается экземпляр события на основе указанного type, инициализируется с помощью свойств eventInit и генерируется на элементе. События по умолчанию composed, cancelable и всплывают.

Поскольку eventInit является специфичным для события, пожалуйста, обратитесь к документации по событиям для списков начальных свойств:

Вы также можете указать JSHandle в качестве значения свойства, если хотите, чтобы живые объекты передавались в событие:

// Обратите внимание, что вы можете создать DataTransfer только в Chromium и Firefox
JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
elementHandle.dispatchEvent("dragstart", arg);

Аргументы

type String #

Тип DOM-события: "click", "dragstart", и т.д.
eventInit EvaluationArgument (опционально)#

Опциональные свойства инициализации, специфичные для события.

Возвращает

void #

evalOnSelector

Добавлено в: v1.9

elementHandle.evalOnSelector

Не рекомендуется

Этот метод не ожидает, пока элемент пройдет проверки actionability, и поэтому может привести к нестабильным тестам. Используйте Locator.evaluate(), другие вспомогательные методы Locator или утверждения, ориентированные на веб.

Возвращает возвращаемое значение expression.

Метод находит элемент, соответствующий указанному селектору в поддереве ElementHandle, и передает его в качестве первого аргумента в expression. Если ни один элемент не соответствует селектору, метод выбрасывает ошибку.

Если expression возвращает Promise, то ElementHandle.evalOnSelector() будет ожидать разрешения промиса и возвращать его значение.

Использование

ElementHandle tweetHandle = page.querySelector(".tweet");
assertEquals("100", tweetHandle.evalOnSelector(".like", "node => node.innerText"));
assertEquals("10", tweetHandle.evalOnSelector(".retweets", "node => node.innerText"));

Аргументы

selector String #

Селектор для запроса.
expression String #

JavaScript-выражение для выполнения в контексте браузера. Если выражение оценивается как функция, функция автоматически вызывается.
arg EvaluationArgument (опционально)#

Опциональный аргумент для передачи в expression.

Возвращает

Object #

evalOnSelectorAll

Добавлено в: v1.9

elementHandle.evalOnSelectorAll

Не рекомендуется

В большинстве случаев Locator.evaluateAll(), другие вспомогательные методы Locator и утверждения, ориентированные на веб, выполняют работу лучше.

Возвращает возвращаемое значение expression.

Метод находит все элементы, соответствующие указанному селектору в поддереве ElementHandle, и передает массив найденных элементов в качестве первого аргумента в expression.

Если expression возвращает Promise, то ElementHandle.evalOnSelectorAll() будет ожидать разрешения промиса и возвращать его значение.

Использование

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>

ElementHandle feedHandle = page.querySelector(".feed");
assertEquals(Arrays.asList("Hello!", "Hi!"), feedHandle.evalOnSelectorAll(".tweet", "nodes => nodes.map(n => n.innerText)"));

Аргументы

selector String #

Селектор для запроса.
expression String #

JavaScript-выражение для выполнения в контексте браузера. Если выражение оценивается как функция, функция автоматически вызывается.
arg EvaluationArgument (опционально)#

Опциональный аргумент для передачи в expression.

Возвращает

Object #

fill

Добавлено до v1.9

elementHandle.fill

Не рекомендуется

Используйте основанный на локаторах Locator.fill() вместо этого. Подробнее о локаторах.

Этот метод ожидает проверок actionability, фокусируется на элементе, заполняет его и генерирует событие input после заполнения. Обратите внимание, что вы можете передать пустую строку, чтобы очистить поле ввода.

Если целевой элемент не является <input>, <textarea> или [contenteditable] элементом, этот метод выбрасывает ошибку. Однако, если элемент находится внутри элемента <label>, который имеет связанный control, будет заполнен именно этот элемент управления.

Для отправки более детализированных событий клавиатуры используйте Locator.pressSequentially().

Использование

ElementHandle.fill(value);
ElementHandle.fill(value, options);

Аргументы

value String #

Значение для установки для элемента <input>, <textarea> или [contenteditable].
options ElementHandle.FillOptions (опционально)
- setForce boolean (опционально) Добавлено в: v1.13#
  
  Нужно ли обходить проверки actionability. По умолчанию false.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() методы.

Возвращает

void #

focus

Добавлено до v1.9

elementHandle.focus

Не рекомендуется

Используйте основанный на локаторах метод Locator.focus() вместо этого. Подробнее о локаторах.

Вызывает focus на элементе.

Использование

ElementHandle.focus();

Возвращает

void #

getAttribute

Добавлено до v1.9

elementHandle.getAttribute

Не рекомендуется

Используйте основанный на локаторах метод Locator.getAttribute() вместо этого. Подробнее о локаторах.

Возвращает значение атрибута элемента.

Использование

ElementHandle.getAttribute(name);

Аргументы

name String #

Имя атрибута, для которого нужно получить значение.

Возвращает

null | String #

hover

Добавлено до v1.9

elementHandle.hover

Не рекомендуется

Используйте основанный на локаторах метод Locator.hover() вместо этого. Подробнее о локаторах.

Этот метод наводит курсор на элемент, выполняя следующие шаги:

Ожидает проверки действительности элемента, если не установлена опция setForce.
Прокручивает элемент в видимую область, если это необходимо.
Использует Page.mouse() для наведения на центр элемента или указанную позицию setPosition.

Если элемент отсоединяется от DOM в любой момент во время действия, этот метод выбрасывает исключение.

Если все шаги не завершены в течение указанного времени setTimeout, этот метод выбрасывает TimeoutError. Установка нулевого таймаута отключает это.

Использование

ElementHandle.hover();
ElementHandle.hover(options);

Аргументы

options ElementHandle.HoverOptions (опционально)
- setForce boolean (опционально)#
  
  Нужно ли обходить проверки действительности. По умолчанию false.
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (опционально)#
  
  Модификаторные клавиши для нажатия. Гарантирует, что только эти модификаторы будут нажаты во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается как "Control" на Windows и Linux и как "Meta" на macOS.
- setNoWaitAfter boolean (опционально) Добавлено в: v1.28#
  
  Устарело
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- setPosition Position (опционально)#
  - setX double
  - setY double
  Точка, используемая относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().
- setTrial boolean (опционально) Добавлено в: v1.11#
  
  Если установлено, этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения.

Возвращает

void #

innerHTML

Добавлено до v1.9

elementHandle.innerHTML

Не рекомендуется

Используйте основанный на локаторах метод Locator.innerHTML() вместо этого. Подробнее о локаторах.

Возвращает element.innerHTML.

Использование

ElementHandle.innerHTML();

Возвращает

String #

innerText

Добавлено до v1.9

elementHandle.innerText

Не рекомендуется

Используйте основанный на локаторах метод Locator.innerText() вместо этого. Подробнее о локаторах.

Возвращает element.innerText.

Использование

ElementHandle.innerText();

Возвращает

String #

inputValue

Добавлено в: v1.13

elementHandle.inputValue

Не рекомендуется

Используйте основанный на локаторах метод Locator.inputValue() вместо этого. Подробнее о локаторах.

Возвращает input.value для выбранного элемента <input>, <textarea> или <select>.

Выбрасывает исключение для элементов, не являющихся вводом. Однако, если элемент находится внутри элемента <label>, который имеет ассоциированный контрол, возвращает значение контрола.

Использование

ElementHandle.inputValue();
ElementHandle.inputValue(options);

Аргументы

options ElementHandle.InputValueOptions (опционально)
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().

Возвращает

String #

isChecked

Добавлено до v1.9

elementHandle.isChecked

Не рекомендуется

Используйте основанный на локаторах метод Locator.isChecked() вместо этого. Подробнее о локаторах.

Возвращает, отмечен ли элемент. Выбрасывает исключение, если элемент не является флажком или радиокнопкой.

Использование

ElementHandle.isChecked();

Возвращает

boolean #

isDisabled

Добавлено до v1.9

elementHandle.isDisabled

Не рекомендуется

Используйте основанный на локаторах метод Locator.isDisabled() вместо этого. Подробнее о локаторах.

Возвращает, отключен ли элемент, противоположность включенному.

Использование

ElementHandle.isDisabled();

Возвращает

boolean #

isEditable

Добавлено до v1.9

elementHandle.isEditable

Не рекомендуется

Используйте основанный на локаторах метод Locator.isEditable() вместо этого. Подробнее о локаторах.

Возвращает, является ли элемент редактируемым.

Использование

ElementHandle.isEditable();

Возвращает

boolean #

isEnabled

Добавлено до v1.9

elementHandle.isEnabled

Не рекомендуется

Используйте основанный на локаторах метод Locator.isEnabled() вместо этого. Подробнее о локаторах.

Возвращает, является ли элемент включенным.

Использование

ElementHandle.isEnabled();

Возвращает

boolean #

isHidden

Добавлено до v1.9

elementHandle.isHidden

Не рекомендуется

Используйте основанный на локаторах метод Locator.isHidden() вместо этого. Подробнее о локаторах.

Возвращает, скрыт ли элемент, противоположность видимому.

Использование

ElementHandle.isHidden();

Возвращает

boolean #

isVisible

Добавлено до v1.9

elementHandle.isVisible

Не рекомендуется

Используйте основанный на локаторах метод Locator.isVisible() вместо этого. Подробнее о локаторах.

Возвращает, является ли элемент видимым.

Использование

ElementHandle.isVisible();

Возвращает

boolean #

press

Добавлено до v1.9

elementHandle.press

Не рекомендуется

Используйте основанный на локаторах метод Locator.press() вместо этого. Подробнее о локаторах.

Фокусируется на элементе, а затем использует 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". При указании с модификатором, модификатор нажимается и удерживается, пока не будет нажата последующая клавиша.

Использование

ElementHandle.press(key);
ElementHandle.press(key, options);

Аргументы

key String #

Имя клавиши для нажатия или символ для генерации, например, ArrowLeft или a.
options ElementHandle.PressOptions (опционально)
- setDelay double (опционально)#
  
  Время ожидания между keydown и keyup в миллисекундах. По умолчанию 0.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Эта опция по умолчанию будет true в будущем.
  
  Действия, инициирующие навигацию, ожидают, пока эти навигации не произойдут и страницы не начнут загружаться. Вы можете отказаться от ожидания, установив этот флаг. Вам понадобится эта опция только в исключительных случаях, таких как навигация на недоступные страницы. По умолчанию false.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().

Возвращает

void #

querySelector

Добавлено в: v1.9

elementHandle.querySelector

Не рекомендуется

Используйте основанный на локаторах метод Page.locator() вместо этого. Подробнее о локаторах.

Метод находит элемент, соответствующий указанному селектору в поддереве ElementHandle. Если ни один элемент не соответствует селектору, возвращает null.

Использование

ElementHandle.querySelector(selector);

Аргументы

selector String #

Селектор для поиска.

Возвращает

null | ElementHandle #

querySelectorAll

Добавлено в: v1.9

elementHandle.querySelectorAll

Не рекомендуется

Используйте основанный на локаторах метод Page.locator() вместо этого. Подробнее о локаторах.

Метод находит все элементы, соответствующие указанному селектору в поддереве ElementHandle. Если ни один элемент не соответствует селектору, возвращает пустой массив.

Использование

ElementHandle.querySelectorAll(selector);

Аргументы

selector String #

Селектор для поиска.

Возвращает

List<ElementHandle>#

screenshot

Добавлено до v1.9

elementHandle.screenshot

Не рекомендуется

Используйте основанный на локаторах метод Locator.screenshot() вместо этого. Подробнее о локаторах.

Этот метод делает скриншот страницы, обрезанный до размера и позиции этого конкретного элемента. Если элемент закрыт другими элементами, он не будет фактически виден на скриншоте. Если элемент является прокручиваемым контейнером, на скриншоте будет виден только текущий прокручиваемый контент.

Этот метод ожидает проверки действительности, затем прокручивает элемент в видимую область перед созданием скриншота. Если элемент отсоединен от DOM, метод выбрасывает ошибку.

Возвращает буфер с захваченным скриншотом.

Использование

ElementHandle.screenshot();
ElementHandle.screenshot(options);

Аргументы

options ElementHandle.ScreenshotOptions (опционально)
- setAnimations enum ScreenshotAnimations { DISABLED, ALLOW } (опционально)#
  
  Если установлено в "disabled", останавливает CSS-анимации, CSS-переходы и веб-анимации. Анимации получают разное обращение в зависимости от их продолжительности:
  - конечные анимации быстро перематываются до завершения, чтобы они вызвали событие transitionend.
  - бесконечные анимации отменяются до начального состояния, а затем воспроизводятся после скриншота.
  По умолчанию "allow", оставляет анимации нетронутыми.
- setCaret enum ScreenshotCaret { HIDE, INITIAL } (опционально)#
  
  Если установлено в "hide", скриншот скроет текстовый курсор. Если установлено в "initial", поведение текстового курсора не изменится. По умолчанию "hide".
- setMask List<Locator> (опционально)#
  
  Укажите локаторы, которые должны быть замаскированы при создании скриншота. Замаскированные элементы будут покрыты розовым прямоугольником #FF00FF (настраивается с помощью setMaskColor), который полностью покрывает их ограничивающий прямоугольник. Маска также применяется к невидимым элементам, см. Соответствие только видимым элементам, чтобы отключить это.
- setMaskColor String (опционально) Добавлено в: v1.35#
  
  Укажите цвет наложения для замаскированных элементов в формате цвета CSS. Цвет по умолчанию розовый #FF00FF.
- setOmitBackground boolean (опционально)#
  
  Скрывает белый фон по умолчанию и позволяет делать скриншоты с прозрачностью. Не применимо к изображениям jpeg. По умолчанию false.
- setPath Path (опционально)#
  
  Путь к файлу для сохранения изображения. Тип скриншота будет определен по расширению файла. Если setPath является относительным путем, то он разрешается относительно текущей рабочей директории. Если путь не указан, изображение не будет сохранено на диск.
- setQuality int (опционально)#
  
  Качество изображения, от 0 до 100. Не применимо к изображениям png.
- setScale enum ScreenshotScale { CSS, DEVICE } (опционально)#
  
  Если установлено в "css", скриншот будет иметь один пиксель на каждый css пиксель на странице. Для устройств с высоким разрешением это позволит сохранить скриншоты небольшими. Использование опции "device" создаст один пиксель на каждый пиксель устройства, так что скриншоты устройств с высоким разрешением будут в два раза больше или даже больше.
  
  По умолчанию "device".
- setStyle String (опционально) Добавлено в: v1.41#
  
  Текст таблицы стилей для применения при создании скриншота. Здесь вы можете скрыть динамические элементы, сделать элементы невидимыми или изменить их свойства, чтобы помочь вам создать повторяемые скриншоты. Эта таблица стилей проникает в Shadow DOM и применяется к внутренним фреймам.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Установите 0, чтобы отключить таймаут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().
- setType enum ScreenshotType { PNG, JPEG } (опционально)#
  
  Укажите тип скриншота, по умолчанию png.

Возвращает

byte[]#

scrollIntoViewIfNeeded

Добавлено до версии v1.9

elementHandle.scrollIntoViewIfNeeded

Не рекомендуется

Используйте основанный на локаторах метод Locator.scrollIntoViewIfNeeded() вместо этого. Подробнее о локаторах.

Этот метод ожидает проверки действительности, затем пытается прокрутить элемент в видимую область, если он не полностью виден, как это определено ratio IntersectionObserver.

Вызывает ошибку, если elementHandle не указывает на элемент, подключенный к Document или ShadowRoot.

Смотрите прокрутка для альтернативных способов прокрутки.

Использование

ElementHandle.scrollIntoViewIfNeeded();
ElementHandle.scrollIntoViewIfNeeded(options);

Аргументы

options ElementHandle.ScrollIntoViewIfNeededOptions (опционально)
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().

Возвращает

void #

selectOption

Добавлено до версии v1.9

elementHandle.selectOption

Не рекомендуется

Используйте основанный на локаторах метод Locator.selectOption() вместо этого. Подробнее о локаторах.

Этот метод ожидает проверки действительности, ждет, пока все указанные опции будут присутствовать в элементе <select>, и выбирает эти опции.

Если целевой элемент не является элементом <select>, этот метод вызывает ошибку. Однако, если элемент находится внутри элемента <label>, который имеет ассоциированный контрол, будет использован контрол.

Возвращает массив значений опций, которые были успешно выбраны.

Вызывает событие change и input, как только все предоставленные опции были выбраны.

Использование

// Одиночный выбор, соответствующий значению или метке
handle.selectOption("blue");
// одиночный выбор, соответствующий метке
handle.selectOption(new SelectOption().setLabel("Blue"));
// множественный выбор
handle.selectOption(new String[] {"red", "green", "blue"});

Аргументы

values null | String | ElementHandle | String[] | SelectOption | ElementHandle[] | SelectOption[]#
- setValue String (опционально)
  
  Соответствует option.value. Опционально.
- setLabel String (опционально)
  
  Соответствует option.label. Опционально.
- setIndex int (опционально)
  
  Соответствует индексу. Опционально.
Опции для выбора. Если у <select> есть атрибут multiple, все соответствующие опции выбираются, в противном случае выбирается только первая опция, соответствующая одной из переданных опций. Строковые значения соответствуют как значениям, так и меткам. Опция считается соответствующей, если все указанные свойства совпадают.
options ElementHandle.SelectOptionOptions (опционально)
- setForce boolean (опционально) Добавлено в: v1.13#
  
  Следует ли обходить проверки действительности. По умолчанию false.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout().

Возвращает

List<String>#

selectText

Добавлено до версии v1.9

elementHandle.selectText

Не рекомендуется

Используйте основанный на локаторах метод Locator.selectText() вместо этого. Подробнее о локаторах.

Этот метод ожидает проверки действительности, затем фокусируется на элементе и выделяет весь его текстовый контент.

Если элемент находится внутри элемента <label>, который имеет ассоциированный контрол, фокусируется и выделяет текст в контроле вместо этого.

Использование

ElementHandle.selectText();
ElementHandle.selectText(options);

Аргументы

options ElementHandle.SelectTextOptions (опционально)
- setForce boolean (опционально) Добавлено в: v1.13#
  
  Следует ли обходить проверки действительности. По умолчанию false.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() methods.

Возвращает

void #

setChecked

Добавлено в: v1.15

elementHandle.setChecked

Не рекомендуется

Используйте основанный на локаторах метод Locator.setChecked() вместо этого. Подробнее о локаторах.

Этот метод отмечает или снимает отметку с элемента, выполняя следующие шаги:

Убедитесь, что элемент является флажком или радиокнопкой. Если нет, этот метод вызывает ошибку.
Если элемент уже имеет правильное состояние, этот метод возвращается немедленно.
Ожидайте проверки действительности на совпадающем элементе, если не установлена опция setForce. Если элемент отсоединен во время проверок, все действие повторяется.
Прокрутите элемент в видимую область, если это необходимо.
Используйте Page.mouse() для нажатия в центре элемента.
Убедитесь, что элемент теперь отмечен или снят. Если нет, этот метод вызывает ошибку.

Если все шаги вместе не завершились в течение указанного времени setTimeout, этот метод вызывает TimeoutError. Передача нулевого тайм-аута отключает это.

Использование

ElementHandle.setChecked(checked);
ElementHandle.setChecked(checked, options);

Аргументы

checked boolean #

Следует ли отметить или снять отметку с флажка.
options ElementHandle.SetCheckedOptions (опционально)
- setForce boolean (опционально)#
  
  Следует ли обходить проверки действительности. По умолчанию false.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- setPosition Position (опционально)#
  - setX double
  - setY double
  Точка для использования относительно верхнего левого угла элемента. Если не указано, используется видимая точка элемента.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() methods.
- setTrial boolean (опционально)#
  
  Если установлено, этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения.

Возвращает

void #

setInputFiles

Добавлено до версии v1.9

elementHandle.setInputFiles

Не рекомендуется

Используйте основанный на локаторах метод Locator.setInputFiles() вместо этого. Подробнее о локаторах.

Устанавливает значение файлового ввода на эти пути к файлам или файлы. Если некоторые из filePaths являются относительными путями, они разрешаются относительно текущей рабочей директории. Для пустого массива очищает выбранные файлы. Для входов с атрибутом [webkitdirectory] поддерживается только один путь к директории.

Этот метод ожидает, что ElementHandle указывает на элемент ввода. Однако, если элемент находится внутри элемента <label>, который имеет ассоциированный контрол, нацелен на контрол вместо этого.

Использование

ElementHandle.setInputFiles(files);
ElementHandle.setInputFiles(files, options);

Аргументы

files Path | Path[] | FilePayload | FilePayload[]#
- setName String
  
  Имя файла
- setMimeType String
  
  Тип файла
- setBuffer byte[]
  
  Содержимое файла
options ElementHandle.SetInputFilesOptions (опционально)
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() methods.

Возвращает

void #

tap

Добавлено до версии v1.9

elementHandle.tap

Не рекомендуется

Используйте основанный на локаторах метод Locator.tap() вместо этого. Подробнее о локаторах.

Этот метод выполняет нажатие на элемент, выполняя следующие шаги:

Ожидайте проверки действительности на элементе, если не установлена опция setForce.
Прокрутите элемент в видимую область, если это необходимо.
Используйте Page.touchscreen() для нажатия в центре элемента или в указанной setPosition.

Если элемент отсоединен от DOM в любой момент во время действия, этот метод вызывает ошибку.

примечание

elementHandle.tap() требует, чтобы опция hasTouch контекста браузера была установлена в true.

Использование

ElementHandle.tap();
ElementHandle.tap(options);

Аргументы

options ElementHandle.TapOptions (опционально)
- setForce boolean (опционально)#
  
  Следует ли обходить проверки действительности. По умолчанию false.
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (опционально)#
  
  Модификаторы клавиш для нажатия. Обеспечивает, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы обратно. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается как "Control" на Windows и Linux и как "Meta" на macOS.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- setPosition Position (опционально)#
  - setX double
  - setY double
  Точка для использования относительно верхнего левого угла элемента. Если не указано, используется видимая точка элемента.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() methods.
- setTrial boolean (опционально) Добавлено в: v1.11#
  
  Если установлено, этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения.

Возвращает

void #

textContent

Добавлено до версии v1.9

elementHandle.textContent

Не рекомендуется

Используйте основанный на локаторах метод Locator.textContent() вместо этого. Подробнее о локаторах.

Возвращает node.textContent.

Использование

ElementHandle.textContent();

Возвращает

null | String #

type

Добавлено до версии v1.9

elementHandle.type

Устарело

В большинстве случаев следует использовать Locator.fill() вместо этого. Вам нужно нажимать клавиши по одной, только если на странице есть специальная обработка клавиатуры - в этом случае используйте Locator.pressSequentially().

Фокусируется на элементе, а затем отправляет событие keydown, keypress/input и keyup для каждого символа в тексте.

Чтобы нажать специальную клавишу, такую как Control или ArrowDown, используйте ElementHandle.press().

Использование

Аргументы

text String #

Текст для ввода в сфокусированный элемент.
options ElementHandle.TypeOptions (опционально)
- setDelay double (опционально)#
  
  Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() methods.

Возвращает

void #

uncheck

Добавлено до версии v1.9

elementHandle.uncheck

Не рекомендуется

Используйте основанный на локаторах метод Locator.uncheck() вместо этого. Подробнее о локаторах.

Этот метод снимает отметку с элемента, выполняя следующие шаги:

Убедитесь, что элемент является флажком или радиокнопкой. Если нет, этот метод вызывает ошибку. Если элемент уже снят, этот метод возвращается немедленно.
Ожидайте проверки действительности на элементе, если не установлена опция setForce.
Прокрутите элемент в видимую область, если это необходимо.
Используйте Page.mouse() для нажатия в центре элемента.
Убедитесь, что элемент теперь снят. Если нет, этот метод вызывает ошибку.

Если элемент отсоединен от DOM в любой момент во время действия, этот метод вызывает ошибку.

Использование

ElementHandle.uncheck();
ElementHandle.uncheck(options);

Аргументы

options ElementHandle.UncheckOptions (опционально)
- setForce boolean (опционально)#
  
  Следует ли обходить проверки действительности. По умолчанию false.
- setNoWaitAfter boolean (опционально)#
  
  Устарело
  Эта опция не имеет эффекта.
  
  Эта опция не имеет эффекта.
- setPosition Position (опционально) Добавлено в: v1.11#
  - setX double
  - setY double
  Точка для использования относительно верхнего левого угла элемента. Если не указано, используется видимая точка элемента.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() methods.
- setTrial boolean (опционально) Добавлено в: v1.11#
  
  Если установлено, этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно для ожидания, пока элемент будет готов к действию без его выполнения.

Возвращает

void #

waitForSelector

Добавлено до версии v1.9

elementHandle.waitForSelector

Не рекомендуется

Используйте веб-утверждения, которые утверждают видимость, или основанный на локаторах метод Locator.waitFor() вместо этого.

Возвращает элемент, указанный селектором, когда он удовлетворяет опции setState. Возвращает null, если ожидается hidden или detached.

Ожидает, пока селектор относительно элемента удовлетворит опции setState (либо появится/исчезнет из DOM, либо станет видимым/скрытым). Если на момент вызова метода селектор уже удовлетворяет условию, метод вернется немедленно. Если селектор не удовлетворяет условию в течение setTimeout миллисекунд, функция вызовет ошибку.

Использование

page.setContent("<div><span></span></div>");
ElementHandle div = page.querySelector("div");
// Ожидание селектора "span" относительно div.
ElementHandle span = div.waitForSelector("span", new ElementHandle.WaitForSelectorOptions()
  .setState(WaitForSelectorState.ATTACHED));

примечание

Этот метод не работает через навигации, используйте Page.waitForSelector() вместо этого.

Аргументы

selector String #

Селектор для запроса.
options ElementHandle.WaitForSelectorOptions (опционально)
- setState enum WaitForSelectorState { ATTACHED, DETACHED, VISIBLE, HIDDEN } (опционально)#
  
  По умолчанию 'visible'. Может быть:
  - 'attached' - ожидание, пока элемент будет присутствовать в DOM.
  - 'detached' - ожидание, пока элемент не будет присутствовать в DOM.
  - 'visible' - ожидание, пока элемент не будет иметь пустую ограничивающую рамку и не будет visibility:hidden. Обратите внимание, что элемент без какого-либо контента или с display:none имеет пустую ограничивающую рамку и не считается видимым.
  - 'hidden' - ожидание, пока элемент либо не будет отсоединен от DOM, либо не будет иметь пустую ограничивающую рамку или visibility:hidden. Это противоположно опции 'visible'.
- setStrict boolean (опционально) Добавлено в: v1.15#
  
  Если true, вызов требует, чтобы селектор разрешался в один элемент. Если данный селектор разрешается в более чем один элемент, вызов вызывает исключение.
- setTimeout double (опционально)#
  
  Максимальное время в миллисекундах. По умолчанию 30000 (30 секунд). Передайте 0, чтобы отключить тайм-аут. Значение по умолчанию можно изменить, используя методы BrowserContext.setDefaultTimeout() или Page.setDefaultTimeout() methods.

Возвращает

null | ElementHandle #

Методы​

boundingBox​

contentFrame​

ownerFrame​

waitForElementState​

Устаревшие​

check​

click​

dblclick​

dispatchEvent​

evalOnSelector​

evalOnSelectorAll​

fill​

focus​

getAttribute​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isEnabled​

isHidden​

isVisible​

press​

querySelector​

querySelectorAll​

screenshot​

scrollIntoViewIfNeeded​

selectOption​

selectText​

setChecked​

setInputFiles​

tap​

textContent​

type​

uncheck​

waitForSelector​

Методы

boundingBox

contentFrame

ownerFrame

waitForElementState

Устаревшие

check

click

dblclick

dispatchEvent

evalOnSelector

evalOnSelectorAll

fill

focus

getAttribute

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isEnabled

isHidden

isVisible

press

querySelector

querySelectorAll

screenshot

scrollIntoViewIfNeeded

selectOption

selectText

setChecked

setInputFiles

tap

textContent

type

uncheck

waitForSelector