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

ElementHandle

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 захватывает логику того, как получить элемент.

В примере ниже дескриптор указывает на конкретный 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();

Методы​

boundingBox​

Добавлено до 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​

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

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

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

await elementHandle.contentFrame();

Возвращает

ownerFrame​

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

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

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

await elementHandle.ownerFrame();

Возвращает

waitForElementState​

Добавлено до 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 (необязательно)

    • timeout number (необязательно)#

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

Возвращает

Deprecated​

$​

Добавлено в: v1.9 elementHandle.$
Не рекомендуется

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

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

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

await elementHandle.$(selector);

Аргументы

  • selector string#

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

Возвращает

$$​

Добавлено в: v1.9 elementHandle.$$
Не рекомендуется

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

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

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

await elementHandle.$$(selector);

Аргументы

  • selector string#

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

Возвращает

$eval​

Добавлено в: v1.9 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 string#

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

  • pageFunction function(Element) | string#

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

  • arg EvaluationArgument (необязательно)#

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

Возвращает

$$eval​

Добавлено в: v1.9 elementHandle.$$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 string#

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

  • pageFunction function(Array<Element>) | string#

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

  • arg EvaluationArgument (необязательно)#

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

Возвращает

check​

Добавлено до v1.9 elementHandle.check
Не рекомендуется

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

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

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • force boolean (необязательно)#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • position Object (необязательно) Добавлено в: v1.11#

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

    • timeout number (необязательно)#

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

    • trial boolean (необязательно) Добавлено в: v1.11#

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

Возвращает

click​

Добавлено до v1.9 elementHandle.click
Не рекомендуется

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

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

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • button "left" | "right" | "middle" (необязательно)#

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

    • clickCount number (необязательно)#

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

    • delay number (необязательно)#

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

    • force boolean (необязательно)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • position Object (необязательно)#

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

    • steps number (необязательно) Добавлено в: v1.57#

      По умолчанию 1. Отправляет n интерполированных событий mousemove, чтобы смоделировать перемещение между текущей позицией курсора Playwright и указанной точкой назначения. Если установить 1, будет сгенерировано одно событие mousemove в точке назначения.

    • timeout number (необязательно)#

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

    • trial boolean (необязательно) Добавлено в: v1.11#

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

Возвращает

dblclick​

Добавлено до v1.9 elementHandle.dblclick
Не рекомендуется

Используйте основанный на локаторах 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 (необязательно)#

      Устарело

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

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

    • position Object (необязательно)#

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

    • steps number (необязательно) Добавлено в: v1.57#

      По умолчанию 1. Отправляет n интерполированных событий mousemove, чтобы смоделировать перемещение между текущей позицией курсора Playwright и указанной точкой назначения. Если установить 1, будет сгенерировано одно событие mousemove в точке назначения.

    • timeout number (необязательно)#

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

    • trial boolean (необязательно) Добавлено в: v1.11#

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

Возвращает

dispatchEvent​

Добавлено до v1.9 elementHandle.dispatchEvent
Не рекомендуется

Используйте основанный на локаторах 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​

Добавлено до v1.9 elementHandle.fill
Не рекомендуется

Используйте основанный на локаторах 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 (необязательно)#

      Устарело

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

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

    • timeout number (необязательно)#

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

Возвращает

focus​

Добавлено до v1.9 elementHandle.focus
Не рекомендуется

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

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

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

await elementHandle.focus();

Возвращает

getAttribute​

Добавлено до v1.9 elementHandle.getAttribute
Не рекомендуется

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

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

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

await elementHandle.getAttribute(name);

Аргументы

  • name string#

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

Возвращает

hover​

Добавлено до v1.9 elementHandle.hover
Не рекомендуется

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

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

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • force boolean (необязательно)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)#

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

    • noWaitAfter boolean (необязательно) Добавлено в: v1.28#

      Устарело

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

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

    • position Object (необязательно)#

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

    • timeout number (необязательно)#

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

    • trial boolean (необязательно) Добавлено в: v1.11#

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

Возвращает

innerHTML​

Добавлено до v1.9 elementHandle.innerHTML
Не рекомендуется

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

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

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

await elementHandle.innerHTML();

Возвращает

innerText​

Добавлено до v1.9 elementHandle.innerText
Не рекомендуется

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

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

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

await elementHandle.innerText();

Возвращает

inputValue​

Добавлено в: v1.13 elementHandle.inputValue
Не рекомендуется

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • timeout number (необязательно)#

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

Возвращает

isChecked​

Добавлено до v1.9 elementHandle.isChecked
Не рекомендуется

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

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

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

await elementHandle.isChecked();

Возвращает

isDisabled​

Добавлено до v1.9 elementHandle.isDisabled
Не рекомендуется

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

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

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

await elementHandle.isDisabled();

Возвращает

isEditable​

Добавлено до v1.9 elementHandle.isEditable
Не рекомендуется

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

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

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

await elementHandle.isEditable();

Возвращает

isEnabled​

Добавлено до v1.9 elementHandle.isEnabled
Не рекомендуется

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

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

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

await elementHandle.isEnabled();

Возвращает

isHidden​

Добавлено до v1.9 elementHandle.isHidden
Не рекомендуется

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

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

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

await elementHandle.isHidden();

Возвращает

isVisible​

Добавлено до v1.9 elementHandle.isVisible
Не рекомендуется

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

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

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

await elementHandle.isVisible();

Возвращает

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

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

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

Аргументы

  • key string#

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

  • options Object (необязательно)

    • delay number (необязательно)#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • timeout number (необязательно)#

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

Возвращает

screenshot​

Добавлено до v1.9 elementHandle.screenshot
Не рекомендуется

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

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • animations "disabled" | "allow" (необязательно)#

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

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

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

    • caret "hide" | "initial" (необязательно)#

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

    • mask Array<Locator> (необязательно)#

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

    • maskColor string (необязательно) Добавлено в: v1.35#

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

    • omitBackground boolean (необязательно)#

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

    • path string (необязательно)#

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

    • quality number (необязательно)#

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

    • scale "css" | "device" (необязательно)#

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

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

    • style string (необязательно) Добавлено в: v1.41#

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

    • timeout number (необязательно)#

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

    • type "png" | "jpeg" (необязательно)#

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

Возвращает

scrollIntoViewIfNeeded​

Добавлено до v1.9 elementHandle.scrollIntoViewIfNeeded
Не рекомендуется

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

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • timeout number (необязательно)#

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

Возвращает

selectOption​

Добавлено до v1.9 elementHandle.selectOption
Не рекомендуется

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

Этот метод ожидает проверки 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 (необязательно)

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

    • label string (необязательно)

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

    • index number (необязательно)

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

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

  • options Object (необязательно)

    • force boolean (необязательно) Добавлено в: v1.13#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • timeout number (необязательно)#

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

Возвращает

selectText​

Добавлено до v1.9 elementHandle.selectText
Не рекомендуется

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • force boolean (необязательно) Добавлено в: v1.13#

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

    • timeout number (необязательно)#

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

Возвращает

setChecked​

Добавлено в: v1.15 elementHandle.setChecked
Не рекомендуется

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

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

  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 (необязательно)

    • force boolean (необязательно)#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • position Object (необязательно)#

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

    • timeout number (необязательно)#

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

    • trial boolean (необязательно)#

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

Возвращает

setInputFiles​

Добавлено до v1.9 elementHandle.setInputFiles
Не рекомендуется

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

Устанавливает значение файлового ввода в указанные пути к файлам или файлы. Если некоторые из 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 (необязательно)

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • timeout number (необязательно)#

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

Возвращает

tap​

Добавлено до v1.9 elementHandle.tap
Не рекомендуется

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

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

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

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

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

примечание

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

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

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

Аргументы

  • options Object (необязательно)

    • force boolean (необязательно)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (необязательно)#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • position Object (необязательно)#

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

    • timeout number (необязательно)#

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

    • trial boolean (необязательно) Добавлено в: v1.11#

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

Возвращает

textContent​

Добавлено до v1.9 elementHandle.textContent
Не рекомендуется

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

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

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

await elementHandle.textContent();

Возвращает

type​

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

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

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

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

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

Аргументы

  • text string#

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

  • options Object (необязательно)

    • delay number (необязательно)#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

      Этот параметр ни на что не влияет.

      Этот параметр ни на что не влияет.

    • timeout number (необязательно)#

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

Возвращает

uncheck​

Добавлено до v1.9 elementHandle.uncheck
Не рекомендуется

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

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

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

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

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

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

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

Аргументы

  • options Object (необязательно)

    • force boolean (необязательно)#

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

    • noWaitAfter boolean (необязательно)#

      Устарело

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

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

    • position Object (необязательно) Добавлено в: v1.11#

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

    • timeout number (необязательно)#

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

    • trial boolean (необязательно) Добавлено в: v1.11#

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

Возвращает

waitForSelector​

Добавлено до v1.9 elementHandle.waitForSelector
Не рекомендуется

Используйте веб-утверждения, которые проверяют видимость, или основанные на локаторах 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().

Возвращает