Перейти к основному содержимому

ElementHandle

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

Discouraged

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

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

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

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

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

В примере ниже дескриптор указывает на конкретный DOM-элемент на странице. Если этот элемент изменяет текст или используется React для рендеринга совершенно другого компонента, дескриптор все равно указывает на этот самый 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();

Methods​

boundingBox​

Added before v1.9 elementHandle.boundingBox

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

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

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

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

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

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

Возвращает

  • Promise<null | Object>#

    • x number

      x-координата элемента в пикселях.

    • y number

      y-координата элемента в пикселях.

    • width number

      ширина элемента в пикселях.

    • height number

      высота элемента в пикселях.

contentFrame​

Added before v1.9 elementHandle.contentFrame

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

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

await elementHandle.contentFrame();

Возвращает

ownerFrame​

Added before v1.9 elementHandle.ownerFrame

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

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

await elementHandle.ownerFrame();

Возвращает

waitForElementState​

Added before v1.9 elementHandle.waitForElementState

Возвращает, когда элемент удовлетворяет 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 Object (optional)

    • timeout number (optional)#

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

Возвращает

Deprecated​

$​

Added in: v1.9 elementHandle.$
Discouraged

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

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

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

await elementHandle.$(selector);

Аргументы

  • selector string#

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

Возвращает

$$​

Added in: v1.9 elementHandle.$$
Discouraged

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

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

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

await elementHandle.$$(selector);

Аргументы

  • selector string#

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

Возвращает

$eval​

Added in: v1.9 elementHandle.$eval
Discouraged

Этот метод не ожидает, пока элемент пройдет проверки на возможность действия, и поэтому может привести к нестабильным тестам. Вместо этого используйте 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 string#

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

  • pageFunction function(Element) | string#

    Функция для выполнения в контексте страницы.

  • arg EvaluationArgument (optional)#

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

Возвращает

$$eval​

Added in: v1.9 elementHandle.$$eval
Discouraged

В большинстве случаев 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!'],
);

Аргументы

Возвращает

check​

Added before v1.9 elementHandle.check
Discouraged

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

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

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

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

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

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

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

Аргументы

  • options Object (optional)

    • force boolean (optional)#

      Следует ли обходить проверки actionability. По умолчанию false.

    • noWaitAfter boolean (optional)#

      Deprecated

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • position Object (optional) Added in: v1.11#

      Точка для использования относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.

    • timeout number (optional)#

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

    • trial boolean (optional) Added in: v1.11#

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

Возвращает

click​

Added before v1.9 elementHandle.click
Discouraged

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

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

  1. Ожидайте проверки actionability на элементе, если не установлена опция force.
  2. Прокрутите элемент в вид, если это необходимо.
  3. Используйте page.mouse для нажатия в центре элемента или указанной position.
  4. Ожидайте, пока инициированные навигации либо завершатся успешно, либо неудачно, если не установлена опция noWaitAfter.

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

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

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

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

Аргументы

  • options Object (optional)

    • button "left" | "right" | "middle" (optional)#

      По умолчанию left.

    • clickCount number (optional)#

      По умолчанию 1. См. UIEvent.detail.

    • delay number (optional)#

      Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.

    • force boolean (optional)#

      Следует ли обходить проверки actionability. По умолчанию false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (optional)#

      Модификаторные клавиши для нажатия. Обеспечивает, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается в "Control" на Windows и Linux и в "Meta" на macOS.

    • noWaitAfter boolean (optional)#

      Deprecated

      Этот параметр по умолчанию будет true в будущем.

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

    • position Object (optional)#

      Точка для использования относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.

    • timeout number (optional)#

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

    • trial boolean (optional) Added in: v1.11#

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

Возвращает

dblclick​

Added before v1.9 elementHandle.dblclick
Discouraged

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

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

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

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

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

примечание

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

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

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

Аргументы

  • options Object (опционально)

    • button "left" | "right" | "middle" (опционально)#

      По умолчанию left.

    • delay number (опционально)#

      Время ожидания между mousedown и mouseup в миллисекундах. По умолчанию 0.

    • force boolean (опционально)#

      Следует ли обходить проверки actionability. По умолчанию false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (опционально)#

      Модификаторные клавиши для нажатия. Гарантирует, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается как "Control" на Windows и Linux и как "Meta" на macOS.

    • noWaitAfter boolean (опционально)#

      Deprecated

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • position Object (опционально)#

      Точка, используемая относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.

    • timeout number (опционально)#

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

    • trial boolean (опционально) Добавлено в: v1.11#

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

Возвращает

dispatchEvent​

Added before v1.9 elementHandle.dispatchEvent
Discouraged

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

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

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

await elementHandle.dispatchEvent('click');

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

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

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

// Обратите внимание, что вы можете создать DataTransfer только в Chromium и Firefox
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await elementHandle.dispatchEvent('dragstart', { dataTransfer });

Аргументы

  • type string#

    Тип DOM события: "click", "dragstart", и т.д.

  • eventInit EvaluationArgument (опционально)#

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

Возвращает

fill​

Added before v1.9 elementHandle.fill
Discouraged

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

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

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

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

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

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

Аргументы

  • value string#

    Значение для установки в элемент <input>, <textarea> или [contenteditable].

  • options Object (опционально)

    • force boolean (опционально) Добавлено в: v1.13#

      Следует ли обходить проверки actionability. По умолчанию false.

    • noWaitAfter boolean (опционально)#

      Deprecated

      Этот параметр не имеет эффекта.

      Этот параметр не имеет эффекта.

    • timeout number (опционально)#

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

Возвращает

focus​

Added before v1.9 elementHandle.focus
Discouraged

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

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

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

await elementHandle.focus();

Возвращает

getAttribute​

Added before v1.9 elementHandle.getAttribute
Discouraged

Use locator-based locator.getAttribute() instead. Read more about locators.

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

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

await elementHandle.getAttribute(name);

Аргументы

  • name string#

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

Возвращает

hover​

Added before v1.9 elementHandle.hover
Discouraged

Use locator-based locator.hover() instead. Read more about locators.

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

  1. Ожидание проверки actionability на элементе, если не установлена опция force.
  2. Прокрутка элемента в видимую область, если это необходимо.
  3. Использование page.mouse для наведения на центр элемента или указанную position.

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

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

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

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

Аргументы

  • options Object (optional)

    • force boolean (optional)#

      Нужно ли обходить проверки actionability. По умолчанию false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (optional)#

      Модификаторы клавиш для нажатия. Гарантирует, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается как "Control" на Windows и Linux и как "Meta" на macOS.

    • noWaitAfter boolean (optional) Added in: v1.28#

      Deprecated

      Эта опция не имеет эффекта.

      Эта опция не имеет эффекта.

    • position Object (optional)#

      Точка, используемая относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.

    • timeout number (optional)#

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

    • trial boolean (optional) Added in: v1.11#

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

Возвращает

innerHTML​

Added before v1.9 elementHandle.innerHTML
Discouraged

Use locator-based locator.innerHTML() instead. Read more about locators.

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

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

await elementHandle.innerHTML();

Возвращает

innerText​

Added before v1.9 elementHandle.innerText
Discouraged

Use locator-based locator.innerText() instead. Read more about locators.

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

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

await elementHandle.innerText();

Возвращает

inputValue​

Added in: v1.13 elementHandle.inputValue
Discouraged

Use locator-based locator.inputValue() instead. Read more about locators.

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

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

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

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

Аргументы

  • options Object (optional)

    • timeout number (optional)#

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

Возвращает

isChecked​

Added before v1.9 elementHandle.isChecked
Discouraged

Use locator-based locator.isChecked() instead. Read more about locators.

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

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

await elementHandle.isChecked();

Возвращает

isDisabled​

Added before v1.9 elementHandle.isDisabled
Discouraged

Use locator-based locator.isDisabled() instead. Read more about locators.

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

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

await elementHandle.isDisabled();

Возвращает

isEditable​

Added before v1.9 elementHandle.isEditable
Discouraged

Use locator-based locator.isEditable() instead. Read more about locators.

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

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

await elementHandle.isEditable();

Возвращает

isEnabled​

Added before v1.9 elementHandle.isEnabled
Discouraged

Use locator-based locator.isEnabled() instead. Read more about locators.

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

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

await elementHandle.isEnabled();

Возвращает

isHidden​

Added before v1.9 elementHandle.isHidden
Discouraged

Use locator-based locator.isHidden() instead. Read more about locators.

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

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

await elementHandle.isHidden();

Возвращает

isVisible​

Added before v1.9 elementHandle.isVisible
Discouraged

Use locator-based locator.isVisible() instead. Read more about locators.

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

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

await elementHandle.isVisible();

Возвращает

press​

Added before v1.9 elementHandle.press
Discouraged

Use locator-based locator.press() instead. Read more about locators.

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

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

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

Аргументы

  • key string#

    Название клавиши для нажатия или символ для генерации, например, ArrowLeft или a.

  • options Object (optional)

    • delay number (optional)#

      Время ожидания между keydown и keyup в миллисекундах. По умолчанию 0.

    • noWaitAfter boolean (optional)#

      Deprecated

      Этот параметр по умолчанию будет true в будущем.

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

    • timeout number (optional)#

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

Возвращает

screenshot​

Added before v1.9 elementHandle.screenshot
Discouraged

Use locator-based locator.screenshot() instead. Read more about locators.

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

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

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

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

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

Аргументы

  • options Object (optional)

    • animations "disabled" | "allow" (optional)#

      При установке в "disabled", останавливает CSS-анимации, CSS-переходы и веб-анимации. Анимации получают разное обращение в зависимости от их продолжительности:

      • конечные анимации быстро перематываются до завершения, так что они вызовут событие transitionend.
      • бесконечные анимации отменяются до начального состояния, а затем воспроизводятся после скриншота.

      По умолчанию "allow", что оставляет анимации нетронутыми.

    • caret "hide" | "initial" (optional)#

      При установке в "hide", скриншот скроет текстовый курсор. При установке в "initial", поведение текстового курсора не будет изменено. По умолчанию "hide".

    • mask Array<Locator> (optional)#

      Укажите локаторы, которые должны быть замаскированы при создании скриншота. Замаскированные элементы будут покрыты розовым прямоугольником #FF00FF (настраивается с помощью maskColor), который полностью покрывает их ограничивающий прямоугольник. Маска также применяется к невидимым элементам, см. Matching only visible elements для отключения этого.

    • maskColor string (optional) Added in: v1.35#

      Укажите цвет наложения для замаскированных элементов в CSS-формате цвета. Цвет по умолчанию - розовый #FF00FF.

    • omitBackground boolean (optional)#

      Скрывает белый фон по умолчанию и позволяет делать скриншоты с прозрачностью. Не применимо к изображениям jpeg. По умолчанию false.

    • path string (optional)#

      Путь к файлу для сохранения изображения. Тип скриншота будет определен по расширению файла. Если path является относительным путем, то он разрешается относительно текущей рабочей директории. Если путь не указан, изображение не будет сохранено на диск.

    • quality number (optional)#

      Качество изображения, от 0 до 100. Не применимо к изображениям png.

    • scale "css" | "device" (optional)#

      При установке в "css", скриншот будет иметь один пиксель на каждый css-пиксель на странице. Для устройств с высоким разрешением это позволит уменьшить размер скриншотов. Использование опции "device" создаст один пиксель на каждый пиксель устройства, так что скриншоты устройств с высоким разрешением будут в два раза больше или даже больше.

      По умолчанию "device".

    • style string (optional) Added in: v1.41#

      Текст стиля, который будет применен при создании скриншота. Здесь вы можете скрыть динамические элементы, сделать элементы невидимыми или изменить их свойства, чтобы помочь вам создавать повторяемые скриншоты. Этот стиль проникает в Shadow DOM и применяется к внутренним фреймам.

    • timeout number (optional)#

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

    • type "png" | "jpeg" (optional)#

      Укажите тип скриншота, по умолчанию png.

Возвращает

scrollIntoViewIfNeeded​

Added before v1.9 elementHandle.scrollIntoViewIfNeeded
Discouraged

Use locator-based locator.scrollIntoViewIfNeeded() instead. Read more about locators.

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

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

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

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

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

Аргументы

  • options Object (optional)

    • timeout number (optional)#

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

Возвращает

selectOption​

Added before v1.9 elementHandle.selectOption
Discouraged

Use locator-based locator.selectOption() instead. Read more about locators.

Этот метод ожидает проверки actionability, ждет, пока все указанные опции будут присутствовать в элементе <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 | string | ElementHandle | Array<string> | Object | Array<ElementHandle> | Array<Object>#

    • value string (optional)

      Совпадение по option.value. Необязательно.

    • label string (optional)

      Совпадение по option.label. Необязательно.

    • index number (optional)

      Совпадение по индексу. Необязательно.

    Опции для выбора. Если у <select> есть атрибут multiple, выбираются все совпадающие опции, в противном случае выбирается только первая опция, совпадающая с одной из переданных. Строковые значения совпадают как с значениями, так и с метками. Опция считается совпадающей, если все указанные свойства совпадают.
  • options Object (optional)

    • force boolean (optional) Added in: v1.13#

      Нужно ли обходить проверки actionability. По умолчанию false.

    • noWaitAfter boolean (optional)#

      Deprecated

      Эта опция не имеет эффекта.

      Эта опция не имеет эффекта.

    • timeout number (optional)#

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

Возвращает

selectText​

Added before v1.9 elementHandle.selectText
Discouraged

Use locator-based locator.selectText() instead. Read more about locators.

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

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

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

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

Аргументы

  • options Object (optional)

    • force boolean (optional) Added in: v1.13#

      Нужно ли обходить проверки actionability. По умолчанию false.

    • timeout number (optional)#

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

Возвращает

setChecked​

Added in: v1.15 elementHandle.setChecked
Discouraged

Use locator-based locator.setChecked() instead. Read more about locators.

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

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

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

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

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

Аргументы

  • checked boolean#

    Нужно ли отметить или снять отметку с флажка.

  • options Object (optional)

    • force boolean (optional)#

      Нужно ли обходить проверки actionability. По умолчанию false.

    • noWaitAfter boolean (optional)#

      Deprecated

      Эта опция не имеет эффекта.

      Эта опция не имеет эффекта.

    • position Object (optional)#

      Точка для использования относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.

    • timeout number (optional)#

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

    • trial boolean (optional)#

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

Возвращает

setInputFiles​

Added before v1.9 elementHandle.setInputFiles
Discouraged

Use locator-based locator.setInputFiles() instead. Read more about locators.

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

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

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

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

Аргументы

  • files string | Array<string> | Object | Array<Object>#

    • name string

      Имя файла

    • mimeType string

      Тип файла

    • buffer Buffer

      Содержимое файла

  • options Object (optional)

    • noWaitAfter boolean (optional)#

      Deprecated

      This option has no effect.

      This option has no effect.

    • timeout number (optional)#

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

Возвращает

tap​

Added before v1.9 elementHandle.tap
Discouraged

Use locator-based locator.tap() instead. Read more about locators.

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

  1. Ожидание actionability проверок на элементе, если только не установлена опция force.
  2. Прокрутка элемента в видимую область, если это необходимо.
  3. Использование page.touchscreen для нажатия в центр элемента или указанную position.

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

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

примечание

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

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

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

Аргументы

  • options Object (optional)

    • force boolean (optional)#

      Нужно ли обходить actionability проверки. По умолчанию false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (optional)#

      Модификаторные клавиши для нажатия. Обеспечивает, что только эти модификаторы нажаты во время операции, а затем восстанавливает текущие модификаторы обратно. Если не указано, используются текущие нажатые модификаторы. "ControlOrMeta" разрешается в "Control" на Windows и Linux и в "Meta" на macOS.

    • noWaitAfter boolean (optional)#

      Deprecated

      This option has no effect.

      This option has no effect.

    • position Object (optional)#

      Точка для использования относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.

    • timeout number (optional)#

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

    • trial boolean (optional) Added in: v1.11#

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

Возвращает

textContent​

Added before v1.9 elementHandle.textContent
Discouraged

Use locator-based locator.textContent() instead. Read more about locators.

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

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

await elementHandle.textContent();

Возвращает

type​

Added before v1.9 elementHandle.type
Deprecated

In most cases, you should use locator.fill() instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use locator.pressSequentially().

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

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

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

Аргументы

  • text string#

    Текст для ввода в фокусированный элемент.

  • options Object (optional)

    • delay number (optional)#

      Время ожидания между нажатиями клавиш в миллисекундах. По умолчанию 0.

    • noWaitAfter boolean (optional)#

      Deprecated

      This option has no effect.

      This option has no effect.

    • timeout number (optional)#

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

Возвращает

uncheck​

Added before v1.9 elementHandle.uncheck
Discouraged

Use locator-based locator.uncheck() instead. Read more about locators.

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

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

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

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

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

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

Аргументы

  • options Object (optional)

    • force boolean (optional)#

      Нужно ли обходить actionability проверки. По умолчанию false.

    • noWaitAfter boolean (optional)#

      Deprecated

      This option has no effect.

      This option has no effect.

    • position Object (optional) Added in: v1.11#

      Точка для использования относительно верхнего левого угла рамки элемента. Если не указано, используется видимая точка элемента.

    • timeout number (optional)#

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

    • trial boolean (optional) Added in: v1.11#

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

Возвращает

waitForSelector​

Added before v1.9 elementHandle.waitForSelector
Discouraged

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

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

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

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

await page.setContent(`<div><span></span></div>`);
const div = await page.$('div');
// Ожидание селектора 'span' относительно div.
const span = await div.waitForSelector('span', { state: 'attached' });
примечание

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

Аргументы

  • selector string#

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

  • options Object (опционально)

    • state "attached" | "detached" | "visible" | "hidden" (опционально)#

      По умолчанию 'visible'. Может быть:

      • 'attached' - ожидание, пока элемент будет присутствовать в DOM.
      • 'detached' - ожидание, пока элемент не будет присутствовать в DOM.
      • 'visible' - ожидание, пока элемент не будет иметь пустую ограничивающую рамку и не будет visibility:hidden. Обратите внимание, что элемент без какого-либо содержимого или с display:none имеет пустую ограничивающую рамку и не считается видимым.
      • 'hidden' - ожидание, пока элемент либо не будет отсоединен от DOM, либо не будет иметь пустую ограничивающую рамку или visibility:hidden. Это противоположно опции 'visible'.

    • strict boolean (опционально) Добавлено в: v1.15#

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

    • timeout number (опционально)#

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

Возвращает