ElementHandle

extends: JSHandle

ElementHandle представляет элемент DOM на странице. ElementHandles можно создать с помощью метода page.$().

Отговаривается от использования

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

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

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

Экземпляры 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();

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

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

Методы

boundingBox

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

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

Прокрутка влияет на возвращаемый прямоугольник, аналогично 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);

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

Promise<null | Объект>
- x число
  
  координата x элемента в пикселях.
- y число
  
  координата y элемента в пикселях.
- width число
  
  ширина элемента в пикселях.
- height число
  
  высота элемента в пикселях.

contentFrame

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

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

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

await elementHandle.contentFrame();

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

Promise<null | Рамка>

ownerFrame

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

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

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

await elementHandle.ownerFrame();

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

Promise<null | Рамка>

waitForElementState

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

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

В зависимости от параметра state этот метод ожидает выполнения одного из проверок actionability. Этот метод выбрасывает исключение, если элемент отсоединяется во время ожидания, за исключением ожидания состояния "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 Объект (необязательно)
- timeout число (необязательно)
  
  Максимальное время ожидания в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию может быть изменено через опцию actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

Promise<void>

Устаревшие

$

Отговаривается от использования

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

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

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

await elementHandle.$(selector);

Аргументы

selector строка

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

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

Promise<null | ElementHandle>

$$

Отговаривается от использования

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

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

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

await elementHandle.$$(selector);

Аргументы

selector строка

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

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

Promise<Массив<ElementHandle>>

$eval

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

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

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

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

Если pageFunction возвращает Promise, то elementHandle.$eval() ожидает завершения промиса и возвращает его значение.

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

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

Аргументы

selector строка

Селектор для поиска.
pageFunction функция(Элемент) | строка

Функция, которая будет вычисляться в контексте страницы.
arg EvaluationArgument (необязательно)

Необязательный аргумент для передачи в pageFunction.

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

Promise<Сериализуемое значение>

$$eval

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

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

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

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

Если pageFunction возвращает Promise, то elementHandle.$$eval() ожидает завершения промиса и возвращает его значение.

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

<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!'],
);

Аргументы

selector строка

Селектор для поиска.
pageFunction функция(Массив<Элемент>) | строка

Функция, которая будет вычисляться в контексте страницы.
arg EvaluationArgument (необязательно)

Необязательный аргумент для передачи в pageFunction.

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

Promise<Сериализуемое значение>

check

Добавлена до версии 1.9

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

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

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

Убедитесь, что элемент является чекбоксом или радиокнопкой. В противном случае метод генерирует ошибку. Если элемент уже проверен, метод возвращается сразу.
Дождитесь проверок на выполнимость действия элемента, если опция force не установлена.
Прокрутите элемент в видимую область, если необходимо.
Используйте page.mouse для клика в центре элемента.
Убедитесь, что элемент теперь проверен. В противном случае метод генерирует ошибку.

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

Если все шаги не завершатся в течение указанного timeout, метод генерирует ошибку TimeoutError. Передача нулевого значения таймаута отключает его.

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

await elementHandle.check();
await elementHandle.check(options);

Аргументы

options Объект (необязательно)
- force логическое значение (необязательно)
  
  Определяет, нужно ли игнорировать проверки на выполнимость действия. По умолчанию false.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  Эта опция не влияет на результат.
  
  Эта опция не влияет на результат.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указана, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или методами browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial логическое значение (необязательно)
  
  При установке этот метод выполняет только проверки на выполнимость действия и пропускает само действие. По умолчанию false. Полезно для ожидания готовности элемента к действию без его выполнения.

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

Promise<void>

click

Добавлена до версии 1.9

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

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

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

Подождите проверки действительности элемента, если опция force не задана.
Прокрутите элемент в видимую область, если необходимо.
Используйте page.mouse для нажатия в центре элемента или в указанной позиции.
Подождите завершения инициированных навигаций, если опция noWaitAfter не задана.

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

Если все шаги вместе не завершатся в течение указанного времени ожидания, этот метод вызывает исключение TimeoutError. Передача нулевого значения времени ожидания отключает эту проверку.

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

await elementHandle.click();
await elementHandle.click(options);

Аргументы

options Объект (необязательно)
- button "слева" | "справа" | "посередине" (необязательно)
  
  По умолчанию left.
- clickCount число (необязательно)
  
  по умолчанию 1. См. UIEvent.detail.
- delay число (необязательно)
  
  Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
- force логическое значение (необязательно)
  
  Пропустить проверки действительности. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Модификаторы клавиш для нажатия. Обеспечивает нажатие только этих модификаторов во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" преобразуется в "Control" в Windows и Linux и в "Meta" в macOS.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  В будущем эта опция будет по умолчанию true.
  
  Действия, инициирующие навигацию, ожидают выполнения этих навигаций и загрузки страниц. Вы можете отказаться от ожидания, установив этот флаг. Вам потребуется только эта опция в исключительных случаях, таких как навигация на недоступные страницы. По умолчанию false.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно левого верхнего угла области отступа элемента. Если не указано, используется некоторая видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial логическое значение (необязательно)
  
  Если задано, этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно подождать, пока элемент будет готов к действию, не выполняя его.

Возвращает

Обещание<void>

dblclick

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

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

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

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

Подождите проверки действительности элемента, если опция force не задана.
Прокрутите элемент в видимую область, если необходимо.
Используйте page.mouse для двойного щелчка в центре элемента или в указанной позиции.

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

примечание

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

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

await elementHandle.dblclick();
await elementHandle.dblclick(options);

Аргументы

options Объект (необязательно)
- button "слева" | "справа" | "посередине" (необязательно)
  
  По умолчанию left.
- delay число (необязательно)
  
  Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.
- force логическое значение (необязательно)
  
  Пропустить проверки действительности. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Модификаторы клавиш для нажатия. Обеспечивает нажатие только этих модификаторов во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" преобразуется в "Control" в Windows и Linux и в "Meta" в macOS.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  Эта опция не оказывает влияния.
  
  Эта опция не оказывает влияния.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно левого верхнего угла области отступа элемента. Если не указано, используется некоторая видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью опции actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial логическое значение (необязательно)
  
  Если задано, этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно подождать, пока элемент будет готов к действию, не выполняя его.

Возвращает

Обещание<void>

dispatchEvent

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

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

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

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

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

await elementHandle.dispatchEvent('click');

Внутри, он создаёт экземпляр события на основе заданного типа, инициализирует его свойствами 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 });

Аргументы

type строка

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

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

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

Promise<void>

fill

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

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

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

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

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

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

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

await elementHandle.fill(value);
await elementHandle.fill(value, options);

Аргументы

value строка

Значение для <input>, <textarea> или [contenteditable] элемента.
options Объект (необязательно)
- force булево (необязательно)
  
  Пропускать ли проверки активности. По умолчанию false.
- noWaitAfter булево (необязательно)
  
  Устарело
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - без таймаута. Значение по умолчанию можно изменить через параметр actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

Promise<void>

focus

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

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

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

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

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

await elementHandle.focus();

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

Promise<void>

getAttribute

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

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

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

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

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

await elementHandle.getAttribute(name);

Аргументы

name строка

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

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

Promise<null | строка>

hover

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

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

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

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

Ожидает проверок активности элемента, если параметр force не задан.
Если необходимо, прокручивает элемент в область видимости.
Использует page.mouse, чтобы навести указатель мыши на центр элемента или указанную позицию.

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

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

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

await elementHandle.hover();
await elementHandle.hover(options);

Аргументы

options Объект (необязательно)
- force булево (необязательно)
  
  Указывает, нужно ли пропускать проверки действительности элемента. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Модификаторы клавиш для нажатия. Гарантирует, что во время операции нажаты только эти модификаторы, а затем восстанавливаются текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" преобразуется в "Control" в Windows и Linux и в "Meta" в macOS.
- noWaitAfter булево (необязательно)
  
  Устарело
  
  Этот параметр не оказывает никакого влияния.
  
  Этот параметр не оказывает никакого влияния.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указано, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial булево (необязательно)
  
  При установке этот метод выполняет только проверки действительности элемента и пропускает действие. По умолчанию false. Полезно для ожидания готовности элемента к действию без его выполнения.

Возвращает

Обещание<пустое значение>

innerHTML

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

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

Используйте основанный на локаторе метод locator.innerHTML() вместо этого. Дополнительную информацию см. в разделе локаторы.

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

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

await elementHandle.innerHTML();

Возвращает

Обещание<строка>

innerText

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

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

Используйте основанный на локаторе метод locator.innerText() вместо этого. Дополнительную информацию см. в разделе локаторы.

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

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

await elementHandle.innerText();

Возвращает

Обещание<строка>

inputValue

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

Используйте основанный на локаторе метод locator.inputValue() вместо этого. Дополнительную информацию см. в разделе локаторы.

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

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

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

await elementHandle.inputValue();
await elementHandle.inputValue(options);

Аргументы

options Объект (необязательно)
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Обещание<строка>

isChecked

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

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

Используйте основанный на локаторе метод locator.isChecked() вместо этого. Дополнительную информацию см. в разделе локаторы.

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

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

await elementHandle.isChecked();

Возвращает

Обещание<булево>

isDisabled

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

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

Используйте основанный на локаторе метод locator.isDisabled() вместо этого. Дополнительную информацию см. в разделе локаторы.

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

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

await elementHandle.isDisabled();

Возвращает

Обещание<булево>

isEditable

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

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

Используйте основанный на локаторе метод locator.isEditable() вместо этого. Дополнительную информацию см. в разделе локаторы.

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

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

await elementHandle.isEditable();

Возвращает

Обещание<булево>

isEnabled

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

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

Используйте основанный на локаторе метод locator.isEnabled() вместо этого. Дополнительную информацию см. в разделе локаторы.

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

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

await elementHandle.isEnabled();

Возвращает

Обещание<булево>

isHidden

Добавлен до версии 1.9

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

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

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

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

await elementHandle.isHidden();

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

Promise<boolean>

isVisible

Добавлен до версии 1.9

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

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

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

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

await elementHandle.isVisible();

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

Promise<boolean>

press

Добавлен до версии 1.9

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

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

Фокусирует элемент, а затем использует keyboard.down() и keyboard.up().

Ключ может указать целевое значение 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 приведет к вводу текста, соответствующего ключу, заглавными буквами.

Если ключ — это один символ, он регистрозависим, поэтому значения a и A будут генерировать разные тексты.

Также поддерживаются сокращения, такие как key: "Control+o", key: "Control++ или key: "Control+Shift+T". При указании с модификатором модификатор нажат и удерживается, а затем нажимается последующая клавиша.

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

await elementHandle.press(key);
await elementHandle.press(key, options);

Аргументы

key строка

Имя нажимаемой клавиши или символ для генерации, например, ArrowLeft или a.
options Объект (необязательно)
- delay число (необязательно)
  
  Время ожидания между keydown и keyup в миллисекундах. По умолчанию 0.
- noWaitAfter логическое значение (необязательно)
  
  Устарело
  
  Этот параметр по умолчанию будет true в будущем.
  
  Действия, инициирующие навигацию, ожидают завершения этих навигаций и загрузки страниц. Вы можете отказаться от ожидания, установив этот флаг. Вам понадобится этот параметр только в исключительных случаях, например, при навигации на недоступные страницы. По умолчанию false.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

Promise<void>

screenshot

Добавлен до версии 1.9

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

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

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

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

Возвращает буфер со сделанным снимком.

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

await elementHandle.screenshot();
await elementHandle.screenshot(options);

Аргументы

options Объект (необязательно)
- animations "выключен" | "разрешить" (необязательно)
  
  При установке в "disabled", останавливаются анимации CSS, переходы CSS и веб-анимации. Анимации обрабатываются по-разному в зависимости от их продолжительности:
  - конечные анимации доводятся до завершения, поэтому они сработают transitionend событием.
  - бесконечные анимации отменяются до начального состояния, а затем воспроизводятся повторно после снимка экрана.
  По умолчанию "allow", что оставляет анимации без изменений.
- caret "скрыть" | "начальное" (необязательно)
  
  При установке в "hide", курсор ввода на снимке экрана будет скрыт. При установке в "initial", поведение курсора ввода не будет изменено. По умолчанию "hide".
- mask Массив<Locator> (необязательно)
  
  Укажите локейторы, которые должны быть замаскированы при создании снимка экрана. Замаскированные элементы будут перекрыты розовым прямоугольником #FF00FF (настраиваемым параметром maskColor), который полностью закрывает его область.
- maskColor строка (необязательно)
  
  Укажите цвет прямоугольника наложения для замаскированных элементов в формате CSS. Цвет по умолчанию — розовый #FF00FF.
- omitBackground булево (необязательно)
  
  Скрывает стандартный белый фон и позволяет делать снимки экрана с прозрачностью. Не применимо к jpeg изображениям. По умолчанию false.
- path строка (необязательно)
  
  Путь к файлу, в который необходимо сохранить изображение. Тип снимка экрана будет определён из расширения файла. Если path является относительным путём, то он разрешается относительно текущей рабочей директории. Если путь не указан, изображение не будет сохранено на диск.
- quality число (необязательно)
  
  Качество изображения, от 0 до 100. Не применимо к png изображениям.
- scale "css" | "device" (необязательно)
  
  При установке в "css", снимок экрана будет содержать один пиксель на каждый пиксель CSS на странице. Для устройств с высоким разрешением это позволит сохранить снимки экрана компактными. Использование "device" приведет к одному пикселю на каждый пиксель устройства, поэтому снимки экрана устройств с высоким разрешением будут вдвое больше или даже больше.
  
  По умолчанию "device".
- style строка (необязательно)
  
  Текст таблицы стилей, который нужно применить при создании снимка экрана. Здесь вы можете скрыть динамические элементы, сделать элементы невидимыми или изменить их свойства, чтобы помочь в создании повторяющихся снимков экрана. Эта таблица стилей проникает в Shadow DOM и применяется к внутренним кадрам.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью actionTimeout параметра в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- type "png" | "jpeg" (необязательно)
  
  Укажите тип снимка экрана, по умолчанию png.

Возвращает

Promise<Буфер>

scrollIntoViewIfNeeded

Добавлено до версии 1.9

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

Используйте локейтор-ориентированную функцию locator.scrollIntoViewIfNeeded() вместо неё. Дополнительная информация о локейторах.

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

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

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

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

await elementHandle.scrollIntoViewIfNeeded();
await elementHandle.scrollIntoViewIfNeeded(options);

Аргументы

options Объект (необязательно)
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию можно изменить с помощью actionTimeout параметра в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<пустое значение>

selectOption

Добавлено до версии 1.9

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

Используйте локейтор-ориентированную функцию locator.selectOption() вместо неё. Дополнительная информация о локейторах.

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

Если целевой элемент не является элементом <select> , этот метод выбросит ошибку. Однако, если элемент находится внутри элемента <label> , у которого есть связанный control, будет использован 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> | Массив<Объект>
- value строка (необязательно)
  
  Совпадение по option.value. Необязательно.
- label строка (необязательно)
  
  Совпадение по option.label. Необязательно.
- index число (необязательно)
  
  Совпадение по индексу. Необязательно.
Варианты для выбора. Если у <select> есть атрибут multiple, все совпадающие варианты выбираются, иначе выбирается только первый вариант, соответствующий одному из переданных вариантов. Строковые значения сопоставляются как со значениями, так и с метками. Вариант считается соответствующим, если все указанные свойства совпадают.
options Объект (необязательно)
- force логическое (необязательно)
  
  Пропускать ли проверки активности. По умолчанию false.
- noWaitAfter логическое (необязательно)
  
  Устарело
  
  Этот параметр не оказывает никакого влияния.
  
  Этот параметр не оказывает никакого влияния.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — нет таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Обещание<Массив<строка>>

selectText

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

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

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

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

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

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

await elementHandle.selectText();
await elementHandle.selectText(options);

Аргументы

options Объект (необязательно)
- force логическое (необязательно)
  
  Пропускать ли проверки активности. По умолчанию false.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — нет таймаута. Значение по умолчанию можно изменить с помощью параметра actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Обещание<ничего>

setChecked

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

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

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

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

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

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

await elementHandle.setChecked(checked);
await elementHandle.setChecked(checked, options);

Аргументы

checked boolean

Включить или выключить флажок.
options Объект (необязательно)
- force boolean (необязательно)
  
  Пропустить проверки действительности действия. По умолчанию false.
- noWaitAfter boolean (необязательно)
  
  Устарело
  
  Этот параметр не оказывает влияния.
  
  Этот параметр не оказывает влияния.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно левого верхнего угла области отступа элемента. Если не указано, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — нет таймаута. Значение по умолчанию может быть изменено через параметр actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial boolean (необязательно)
  
  При установке этот метод выполняет только проверки действительности действия и пропускает само действие. По умолчанию false. Полезно для ожидания готовности элемента к действию без его выполнения.

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

Promise<void>

setInputFiles

Добавлен до версии 1.9

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

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

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

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

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

await elementHandle.setInputFiles(files);
await elementHandle.setInputFiles(files, options);

Аргументы

files строка | Массив<строка> | Объект | Массив<Объект>
- name строка
  
  Имя файла
- mimeType строка
  
  Тип файла
- buffer Буфер
  
  Содержимое файла
options Объект (необязательно)
- noWaitAfter boolean (необязательно)
  
  Устарело
  
  Этот параметр не оказывает влияния.
  
  Этот параметр не оказывает влияния.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — нет таймаута. Значение по умолчанию может быть изменено через параметр actionTimeout в конфигурации или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

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

Promise<void>

tap

Добавлен до версии 1.9

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

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

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

Ожидает проверок действительности действия для элемента, если параметр force не задан.
Прокручивает элемент в область видимости, если необходимо.
Использует page.touchscreen для тапа в центр элемента или указанной позиции.

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

Если все шаги не завершаются в течение указанного таймаута timeout, метод генерирует исключение TimeoutError. Передача нулевого значения таймаута отключает его.

примечание

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

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

await elementHandle.tap();
await elementHandle.tap(options);

Аргументы

options Объект (необязательно)
- force boolean (необязательно)
  
  Обойти ли проверки действительности. По умолчанию false.
- modifiers Массив<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)
  
  Ключи модификаторов для нажатия. Гарантирует, что во время операции нажаты только эти модификаторы, а затем восстанавливаются текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" преобразуется в "Control" в Windows и Linux и в "Meta" в macOS.
- noWaitAfter boolean (необязательно)
  
  Устарело
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указано, используется некоторая видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - нет таймаута. Значение по умолчанию можно изменить через параметр actionTimeout в конфигурации или используя методы browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial boolean (необязательно)
  
  При установке этот метод выполняет только проверки действительности и пропускает действие. По умолчанию false. Полезно ожидать готовности элемента к действию без его выполнения.

Возвращает

Promise<void>

textContent

Добавлено до версии 1.9

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

Используйте базирующийся на локаторах метод locator.textContent() вместо этого. Подробнее о локатоpax.

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

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

await elementHandle.textContent();

Возвращает

Promise<null | строка>

type

Добавлено до версии 1.9

Устарело

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

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

Для нажатия специальных клавиш, таких как Control или ArrowDown, используйте elementHandle.press().

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

Аргументы

text строка

Текст, который нужно ввести в сфокусированный элемент.
options Объект (необязательно)
- delay число (необязательно)
  
  Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.
- noWaitAfter boolean (необязательно)
  
  Устарело
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 - нет таймаута. Значение по умолчанию можно изменить через параметр actionTimeout в конфигурации или используя методы browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<void>

uncheck

Добавлено до версии 1.9

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

Используйте базирующийся на локаторах метод locator.uncheck() вместо этого. Подробнее о локатоpax.

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

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

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

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

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

await elementHandle.uncheck();
await elementHandle.uncheck(options);

Аргументы

options Объект (необязательно)
- force boolean (необязательно)
  
  Определяет, нужно ли пропускать проверки активности. По умолчанию false.
- noWaitAfter boolean (необязательно)
  
  Устарело
  
  Этот параметр не имеет эффекта.
  
  Этот параметр не имеет эффекта.
- position Объект (необязательно)
  - x число
  - y число
  Точка, используемая относительно верхнего левого угла области отступа элемента. Если не указано, используется какая-либо видимая точка элемента.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию может быть изменено с помощью параметра actionTimeout в конфигурации, или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().
- trial boolean (необязательно)
  
  Если установлено, этот метод выполняет только проверки активности и пропускает действие. По умолчанию false. Полезно для ожидания готовности элемента к действию без его выполнения.

Возвращает

Promise<void>

waitForSelector

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

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

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

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

Ожидает, что селектор, относящийся к элементу, удовлетворит параметру состояние (либо появится/исчезнет из 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() вместо этого.

Аргументы

selector строка

Селектор для запроса.
options Объект (необязательно)
- state "прикреплён" | "откреплён" | "видимый" | "скрытый" (необязательно)
  
  По умолчанию 'visible'. Может быть:
  - 'attached' - ожидание наличия элемента в DOM.
  - 'detached' - ожидание отсутствия элемента в DOM.
  - 'visible' - ожидание наличия у элемента ненулевого прямоугольника и отсутствия visibility:hidden. Обратите внимание, что элемент без содержимого или с display:none имеет пустой прямоугольник и не считается видимым.
  - 'hidden' - ожидание открепления элемента от DOM или наличия у него пустого прямоугольника или visibility:hidden. Это противоположно параметру 'visible'.
- strict boolean (необязательно)
  
  При значении true, вызов требует, чтобы селектор возвращал единственный элемент. Если селектор возвращает более одного элемента, вызов выбросит исключение.
- timeout число (необязательно)
  
  Максимальное время в миллисекундах. По умолчанию 0 — без таймаута. Значение по умолчанию может быть изменено с помощью параметра actionTimeout в конфигурации, или с помощью методов browserContext.setDefaultTimeout() или page.setDefaultTimeout().

Возвращает

Promise<null | ElementHandle>

Методы​

boundingBox​

contentFrame​

ownerFrame​

waitForElementState​

Устаревшие​

$​

$$​

$eval​

$$eval​

check​

click​

dblclick​

dispatchEvent​

fill​

focus​

getAttribute​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isEnabled​

isHidden​

isVisible​

press​

screenshot​

scrollIntoViewIfNeeded​

selectOption​

selectText​

setChecked​

setInputFiles​

tap​

textContent​

type​

uncheck​

waitForSelector​

Методы

boundingBox

contentFrame

ownerFrame

waitForElementState

Устаревшие

$

$$

$eval

$$eval

check

click

dblclick

dispatchEvent

fill

focus

getAttribute

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isEnabled

isHidden

isVisible

press

screenshot

scrollIntoViewIfNeeded

selectOption

selectText

setChecked

setInputFiles

tap

textContent

type

uncheck

waitForSelector