Page

Page 提供了与 Browser 中的单个标签页或 Chromium 中的 extension background page 交互的方法。一个 Browser 实例可能包含多个 Page 实例。

这个示例创建了一个页面，将其导航到一个URL，然后保存截图：

const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.

(async () => {
  const browser = await webkit.launch();
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'screenshot.png' });
  await browser.close();
})();

Page类会发出各种事件（如下所述），可以使用Node的原生EventEmitter方法（如on、once或removeListener）来处理这些事件。

这个示例记录了单个页面load事件的消息：

page.once('load', () => console.log('Page loaded!'));

要取消订阅事件，请使用 removeListener 方法：

function logRequest(interceptedRequest) {
  console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.removeListener('request', logRequest);

方法​

addInitScript​

添加一个脚本，该脚本将在以下任一场景中被执行：

• 每当页面发生导航时。
• 每当子框架被附加或导航时。在这种情况下，脚本会在新附加框架的上下文中进行评估。

脚本会在文档创建后但在其任何脚本运行前被评估。这对于修改JavaScript环境非常有用，例如用于初始化Math.random。

用法

在页面加载前覆盖Math.random的示例：

// preload.js
Math.random = () => 42;

// In your playwright script, assuming the preload.js file is in same directory
await page.addInitScript({ path: './preload.js' });

await page.addInitScript(mock => {
  window.mock = mock;
}, mock);

参数

• script function | string | Object#

  • path string (可选)

    JavaScript文件的路径。如果path是相对路径，则相对于当前工作目录解析。可选。

  • content string (可选)

    原始脚本内容。可选参数。

  要在页面中评估的脚本。

• arg Serializable (可选)#

  传递给script的可选参数（仅在传递函数时支持）。

返回

• Promise<void>#

addLocatorHandler​

在测试网页时，有时会出现意外的覆盖层，例如"注册"对话框，它们会阻止你想要自动执行的操作，比如点击按钮。这些覆盖层并不总是以相同的方式或相同的时间出现，使得它们在自动化测试中难以处理。

该方法允许您设置一个特殊的函数，称为处理程序，当检测到覆盖层可见时激活。处理程序的任务是移除覆盖层，使您的测试能够继续运行，就像覆盖层不存在一样。

需要注意的事项：

• 当可以预见性地显示覆盖层时，我们建议在测试中显式等待它并将其关闭作为正常测试流程的一部分，而不是使用page.addLocatorHandler()。
• Playwright 在执行或重试需要可操作性检查的操作之前，或者在执行自动等待断言检查之前，每次都会检查覆盖层。当覆盖层可见时，Playwright 会先调用处理程序，然后继续执行操作/断言。请注意，处理程序仅在您执行操作/断言时被调用 - 如果覆盖层变得可见但您不执行任何操作，则不会触发处理程序。
• 执行完处理程序后，Playwright会确保触发该处理程序的覆盖层不再可见。您可以通过noWaitAfter选项禁用此行为。
• 处理程序的执行时间计入执行该处理程序的操作/断言超时。如果您的处理程序耗时过长，可能会导致超时。
• 您可以注册多个处理程序。但是，同一时间只会运行一个处理程序。请确保处理程序内的操作不依赖于另一个处理程序。

用法

一个示例，当"注册订阅新闻通讯"对话框出现时将其关闭：

// Setup the handler.
await page.addLocatorHandler(page.getByText('Sign up to the newsletter'), async () => {
  await page.getByRole('button', { name: 'No thanks' }).click();
});

// Write the test as usual.
await page.goto('https://example.com');
await page.getByRole('button', { name: 'Start here' }).click();

一个示例，当显示"确认您的安全详情"页面时跳过该页面：

// Setup the handler.
await page.addLocatorHandler(page.getByText('Confirm your security details'), async () => {
  await page.getByRole('button', { name: 'Remind me later' }).click();
});

// Write the test as usual.
await page.goto('https://example.com');
await page.getByRole('button', { name: 'Start here' }).click();

一个在每次可操作性检查时使用自定义回调的示例。它使用了始终可见的定位器，因此该处理程序会在每次可操作性检查前被调用。指定noWaitAfter很重要，因为该处理程序不会隐藏元素。

// Setup the handler.
await page.addLocatorHandler(page.locator('body'), async () => {
  await page.evaluate(() => window.removeObstructionsForTestIfNeeded());
}, { noWaitAfter: true });

// Write the test as usual.
await page.goto('https://example.com');
await page.getByRole('button', { name: 'Start here' }).click();

Handler 将原始定位器作为参数。您还可以通过设置 times 来指定调用次数后自动移除该 handler：

await page.addLocatorHandler(page.getByLabel('Close'), async locator => {
  await locator.click();
}, { times: 1 });

参数

• locator Locator#

  触发处理程序的定位器。

• handler function(Locator):Promise<Object>#

  当locator出现时应运行的函数。该函数应移除阻碍点击等操作的遮挡元素。

• options Object (可选)

  • noWaitAfter boolean (可选) 添加于: v1.44#

    默认情况下，调用处理程序后，Playwright会等待覆盖层变为隐藏状态，然后才会继续执行触发处理程序的操作/断言。此选项允许退出此行为，以便处理程序运行后覆盖层可以保持可见。

  • times number (可选) 添加于: v1.44#

    指定此处理程序应被调用的最大次数。默认情况下无限制。

返回

• Promise<void>#

addScriptTag​

向页面添加一个带有指定URL或内容的<script>标签。当脚本的onload事件触发或脚本内容被注入到框架时，返回添加的标签。

用法

await page.addScriptTag();
await page.addScriptTag(options);

参数

• options Object (optional)

  • content string (可选)#

    要注入到框架中的原始JavaScript内容。

  • path string (可选)#

    要注入到框架中的JavaScript文件路径。如果path是相对路径，则相对于当前工作目录解析。

  • type string (可选)#

    脚本类型。使用'module'来加载JavaScript ES6模块。更多详情请参阅script。

  • url string (可选)#

    要添加的脚本的URL。

返回

• Promise<ElementHandle>#

addStyleTag​

向页面中添加一个带有指定URL的<link rel="stylesheet">标签，或者一个带有CSS内容的<style type="text/css">标签。当样式表的onload事件触发或CSS内容被注入到框架时，返回添加的标签。

用法

await page.addStyleTag();
await page.addStyleTag(options);

参数

• options Object (optional)

  • content string (可选)#

    要注入到框架中的原始CSS内容。

  • path string (可选)#

    要注入框架的CSS文件路径。如果path是相对路径，则相对于当前工作目录解析。

  • url string (可选)#

    <link> 标签的URL地址。

返回

• Promise<ElementHandle>#

bringToFront​

将页面置于前台（激活标签页）。

用法

await page.bringToFront();

返回

• Promise<void>#

关闭​

如果runBeforeUnload是false，则不会运行任何卸载处理程序并等待页面关闭。如果runBeforeUnload是true，该方法将运行卸载处理程序，但不会等待页面关闭。

默认情况下，page.close() 不会运行beforeunload处理程序。

用法

await page.close();
await page.close(options);

参数

• options Object (optional)

  • reason string (可选) 添加于: v1.40#

    要报告给因页面关闭而中断的操作的原因。

  • runBeforeUnload boolean (可选)#

    默认为false。是否运行before unload页面处理程序。

返回

• Promise<void>#

内容​

Gets the full HTML contents of the page, including the doctype.

用法

await page.content();

返回

• Promise<string>#

上下文​

获取页面所属的浏览器上下文。

用法

page.context();

返回

• BrowserContext#

dragAndDrop​

该方法将源元素拖动到目标元素。首先会移动到源元素，执行mousedown操作，然后移动到目标元素并执行mouseup操作。

用法

await page.dragAndDrop('#source', '#target');
// or specify exact positions relative to the top-left corners of the elements:
await page.dragAndDrop('#source', '#target', {
  sourcePosition: { x: 34, y: 7 },
  targetPosition: { x: 10, y: 20 },
});

参数

• source string#

  用于搜索要拖拽元素的选择器。如果有多个元素满足该选择器，将使用第一个元素。

• target string#

  用于搜索要拖放到的元素的选择器。如果有多个元素满足该选择器，将使用第一个元素。

• options Object (可选)

  • force boolean (可选)#

    是否绕过可操作性检查。默认为false。

  • noWaitAfter boolean (可选)#

    已弃用

    此选项无效。

    此选项无效。

  • sourcePosition Object (可选) 添加于: v1.14#

    • x number

    • y number

    点击源元素上相对于该元素内边距框左上角的这个点。如果未指定，则使用该元素的某个可见点。

  • strict boolean (可选) 添加于: v1.14#

    当为true时，要求选择器必须解析为单个元素。如果给定的选择器解析出多个元素，调用将抛出异常。

  • targetPosition Object (可选) 添加于: v1.14#

    • x number

    • y number

    在目标元素的这一点上相对于元素内边距框的左上角进行拖放。如果未指定，则使用元素的某个可见点。

  • timeout number (可选)#

    最大时间，单位为毫秒。默认为 0 - 表示无超时限制。默认值可以通过配置文件中的 actionTimeout 选项进行修改，或者使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法进行设置。

  • trial boolean (可选)#

    当设置此参数时，该方法仅执行可操作性检查并跳过实际操作。默认为false。适用于等待元素准备好执行操作但暂不执行的情况。

返回

• Promise<void>#

模拟媒体​

此方法通过media参数更改CSS媒体类型，和/或使用colorScheme参数更改'prefers-colors-scheme'媒体特性。

用法

await page.evaluate(() => matchMedia('screen').matches);
// → true
await page.evaluate(() => matchMedia('print').matches);
// → false

await page.emulateMedia({ media: 'print' });
await page.evaluate(() => matchMedia('screen').matches);
// → false
await page.evaluate(() => matchMedia('print').matches);
// → true

await page.emulateMedia({});
await page.evaluate(() => matchMedia('screen').matches);
// → true
await page.evaluate(() => matchMedia('print').matches);
// → false

await page.emulateMedia({ colorScheme: 'dark' });
await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches);
// → true
await page.evaluate(() => matchMedia('(prefers-color-scheme: light)').matches);
// → false

参数

• options Object (optional)

  • colorScheme null | "light" | "dark" | "no-preference" (可选) 添加于: v1.9#

    模拟 prefers-colors-scheme 媒体特性，支持的值为 'light' 和 'dark'。传递 null 会禁用颜色方案模拟。'no-preference' 已弃用。

  • contrast null | "no-preference" | "more" (可选) 添加于: v1.51#

    模拟'prefers-contrast'媒体特性，支持的值为'no-preference'、'more'。传入null将禁用对比度模拟。

  • forcedColors null | "active" | "none" (可选) 添加于: v1.15#

    模拟'forced-colors'媒体特性，支持的值为'active'和'none'。传入null将禁用强制颜色模拟。

  • media null | "screen" | "print" (可选) 添加于: v1.9#

    更改页面的CSS媒体类型。唯一允许的值为'screen'、'print'和null。传递null将禁用CSS媒体模拟。

  • reducedMotion null | "reduce" | "no-preference" (可选) 添加于: v1.12#

    模拟'prefers-reduced-motion'媒体特性，支持的值为'reduce', 'no-preference'。传入null将禁用减少运动模拟。

返回

• Promise<void>#

评估​

返回pageFunction调用的值。

如果传递给page.evaluate()的函数返回一个Promise，那么page.evaluate()将等待该promise解析并返回其值。

如果传递给page.evaluate()的函数返回一个非Serializable值，那么page.evaluate()会解析为undefined。Playwright还支持传输一些无法通过JSON序列化的额外值：-0、NaN、Infinity、-Infinity。

用法

向pageFunction传递参数：

const result = await page.evaluate(([x, y]) => {
  return Promise.resolve(x * y);
}, [7, 8]);
console.log(result); // prints "56"

也可以传入字符串代替函数：

console.log(await page.evaluate('1 + 2')); // prints "3"
const x = 10;
console.log(await page.evaluate(`1 + ${x}`)); // prints "11"

ElementHandle 实例可以作为参数传递给 page.evaluate()：

const bodyHandle = await page.evaluate('document.body');
const html = await page.evaluate<string, HTMLElement>(([body, suffix]) =>
  body.innerHTML + suffix, [bodyHandle, 'hello']
);
await bodyHandle.dispose();

参数

• pageFunction function | string#

  要在页面上下文中评估的函数。

• arg EvaluationArgument (可选)#

  传递给pageFunction的可选参数。

返回

• Promise<Serializable>#

evaluateHandle​

将pageFunction调用的值作为JSHandle返回。

page.evaluate() 和 page.evaluateHandle() 的唯一区别在于 page.evaluateHandle() 会返回 JSHandle。

如果传递给page.evaluateHandle()的函数返回一个Promise，那么page.evaluateHandle()将等待该promise解析并返回其值。

用法

// Handle for the window object.
const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window));

也可以传入字符串代替函数：

const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'

JSHandle 实例可以作为参数传递给 page.evaluateHandle()：

const aHandle = await page.evaluateHandle(() => document.body);
const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();

参数

• pageFunction function | string#

  要在页面上下文中评估的函数。

• arg EvaluationArgument (可选)#

  传递给pageFunction的可选参数。

返回

• Promise<JSHandle>#

exposeBinding​

该方法在页面每个框架的window对象上添加一个名为name的函数。当调用时，该函数执行callback并返回一个Promise，该Promise会解析为callback的返回值。如果callback返回一个Promise，它将被等待。

callback函数的第一个参数包含调用者的信息：{ browserContext: BrowserContext, page: Page, frame: Frame }。

查看browserContext.exposeBinding()获取上下文范围的版本。

用法

一个将页面URL暴露给页面中所有框架的示例：

const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.

(async () => {
  const browser = await webkit.launch({ headless: false });
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.exposeBinding('pageURL', ({ page }) => page.url());
  await page.setContent(`
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.pageURL();
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
  `);
  await page.click('button');
})();

参数

• name string#

  窗口对象上的函数名称。

• callback function#

  将在Playwright上下文中调用的回调函数。

• options Object (可选)

  • handle boolean (可选)#

    已弃用

    此选项将在未来版本中移除。

    是否将参数作为句柄传递，而不是按值传递。当传递句柄时，仅支持一个参数。当按值传递时，支持多个参数。

返回

• Promise<void>#

exposeFunction​

该方法在页面每个框架的window对象上添加一个名为name的函数。当调用时，该函数执行callback并返回一个Promise，该Promise会解析为callback的返回值。

如果callback返回一个Promise，它将被等待。

有关上下文范围内暴露的函数，请参见browserContext.exposeFunction()。

用法

一个向页面添加sha256函数的示例：

const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.
const crypto = require('crypto');

(async () => {
  const browser = await webkit.launch({ headless: false });
  const page = await browser.newPage();
  await page.exposeFunction('sha256', text =>
    crypto.createHash('sha256').update(text).digest('hex'),
  );
  await page.setContent(`
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
  `);
  await page.click('button');
})();

参数

• name string#

  窗口对象上的函数名称

• callback function#

  回调函数，将在Playwright的上下文中被调用。

返回

• Promise<void>#

框架​

返回符合指定条件的框架。必须指定name或url参数。

用法

const frame = page.frame('frame-name');

const frame = page.frame({ url: /.*domain.*/ });

参数

• frameSelector 字符串 | Object#

  • name string (可选)

    在iframe的name属性中指定的框架名称。可选。

  • url string | RegExp | function(URL):boolean (可选)

    一个通配符模式、正则表达式模式或接收框架url作为URL对象的谓词函数。可选参数。

  Frame name or other frame lookup options.

返回

• null | Frame#

frameLocator​

在使用iframe时，您可以创建一个框架定位器，该定位器将进入iframe并允许选择该iframe中的元素。

用法

以下代码片段定位了id为my-frame的iframe中文本为"Submit"的元素，例如<iframe id="my-frame">：

const locator = page.frameLocator('#my-iframe').getByText('Submit');
await locator.click();

参数

• selector string#

  解析DOM元素时使用的选择器。

返回

• FrameLocator#

框架​

附加到页面的所有框架的数组。

用法

page.frames();

返回

• Array<Frame>#

getByAltText​

允许通过元素的alt文本来定位元素。

用法

例如，这个方法将通过alt文本"Playwright logo"找到图片：

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

getByLabel​

允许通过关联<label>或aria-labelledby元素的文本内容，或者通过aria-label属性来定位输入元素。

用法

例如，这个方法将在以下DOM中通过标签"Username"和"Password"找到输入框：

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

getByPlaceholder​

允许通过占位文本来定位输入元素。

用法

例如，考虑以下DOM结构。

<input type="email" placeholder="name@example.com" />

您可以通过占位符文本定位后填写输入框：

await page
    .getByPlaceholder('name@example.com')
    .fill('playwright@microsoft.com');

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

getByRole​

允许通过元素的ARIA角色、ARIA属性和可访问名称来定位元素。

用法

考虑以下DOM结构。

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

您可以通过元素的隐式角色来定位每个元素：

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).click();

参数

• role "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"#

  必需的aria角色。

• options Object (可选)

  • checked boolean (可选)#

    通常由aria-checked或原生<input type=checkbox>控件设置的属性。

    了解更多关于aria-checked的信息。

  • disabled boolean (可选)#

    通常由aria-disabled或disabled设置的属性。

    注意

    与大多数其他属性不同，disabled会通过DOM层次结构继承。了解更多关于aria-disabled的信息。

  • exact boolean (可选) 添加于: v1.28#

    是否精确匹配name: 区分大小写且需完全匹配整个字符串。默认为 false。当name是正则表达式时此参数会被忽略。请注意精确匹配仍会去除首尾空格。

  • expanded boolean (可选)#

    通常由aria-expanded设置的属性。

    了解更多关于aria-expanded的信息。

  • includeHidden boolean (可选)#

    控制是否匹配隐藏元素的选项。默认情况下，角色选择器仅匹配非隐藏元素，如ARIA定义的那样。

    了解更多关于aria-hidden的信息。

  • level number (可选)#

    一个数字属性，通常出现在heading、listitem、row、treeitem等角色中，对于<h1>-<h6>元素有默认值。

    了解更多关于aria-level的信息。

  • name string | RegExp (可选)#

    用于匹配accessible name的选项。默认情况下匹配不区分大小写并搜索子字符串，使用exact来控制此行为。

    了解更多关于accessible name的信息。

  • pressed boolean (可选)#

    通常由aria-pressed设置的属性。

    了解更多关于aria-pressed的信息。

  • selected boolean (可选)#

    通常由aria-selected设置的属性。

    了解更多关于aria-selected的信息。

返回

• 定位器#

详情

角色选择器不能替代无障碍审计和合规性测试，而是提供关于ARIA指南的早期反馈。

Many html elements have an implicitly defined role that is recognized by the role selector. You can find all the supported roles here. ARIA guidelines do not recommend duplicating implicit roles and attributes by setting role and/or aria-* attributes to default values.

getByTestId​

通过测试ID定位元素。

用法

考虑以下DOM结构。

<button data-testid="directions">Itinéraire</button>

您可以通过元素的测试ID来定位它：

await page.getByTestId('directions').click();

参数

• testId string | RegExp#

  用于定位元素的ID。

返回

• 定位器#

详情

默认情况下，data-testid属性被用作测试ID。如有需要，可使用selectors.setTestIdAttribute()来配置不同的测试ID属性。

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

getByText​

允许定位包含给定文本的元素。

另请参阅locator.filter()，它允许通过其他条件（如可访问角色）进行匹配，然后按文本内容进行筛选。

用法

考虑以下DOM结构：

<div>Hello <span>world</span></div>
<div>Hello</div>

您可以通过文本子字符串、精确字符串或正则表达式进行定位：

// Matches <span>
page.getByText('world');

// Matches first <div>
page.getByText('Hello world');

// Matches second <div>
page.getByText('Hello', { exact: true });

// Matches both <div>s
page.getByText(/Hello/);

// Matches second <div>
page.getByText(/^hello$/i);

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

详情

按文本匹配时总是会规范化空白字符，即使是精确匹配。例如，它会将多个空格转换为一个，将换行符转换为空格，并忽略开头和结尾的空白字符。

类型为button和submit的输入元素是通过它们的value值而非文本内容来匹配的。例如，通过文本"Log in"定位会匹配到<input type=button value="Log in">。

getByTitle​

允许通过元素的title属性来定位元素。

用法

考虑以下DOM结构。

<span title='Issues count'>25 issues</span>

您可以通过标题文本定位后检查问题数量：

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

返回​

返回主资源响应。在多次重定向的情况下，导航将解析为最后一次重定向的响应。如果无法返回，则返回null。

在历史记录中导航到上一页。

用法

await page.goBack();
await page.goBack(options);

参数

• options Object (optional)

  • timeout number (可选)#

    操作的最长时间，单位为毫秒。默认为0表示无超时限制。默认值可以通过配置文件中的navigationTimeout选项进行修改，或者使用browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()或page.setDefaultTimeout()方法来设置。

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

    何时认为操作成功，默认为 load。事件可以是以下之一：

    • 'domcontentloaded' - 当触发DOMContentLoaded事件时认为操作已完成。
    • 'load' - 当触发load事件时认为操作已完成。
    • 'networkidle' - 不建议使用 当至少500毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，应依赖网页断言来评估准备状态。
    • 'commit' - 当收到网络响应且文档开始加载时，认为操作已完成。

返回

• Promise<null | Response>#

前进​

返回主资源响应。在多次重定向的情况下，导航将以最后一次重定向的响应结果解析。如果无法前进，则返回null。

在历史记录中导航到下一页。

用法

await page.goForward();
await page.goForward(options);

参数

• options Object (optional)

  • timeout number (可选)#

    操作的最长时间，单位为毫秒。默认为0表示无超时限制。默认值可以通过配置文件中的navigationTimeout选项进行修改，或者使用browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()或page.setDefaultTimeout()方法来设置。

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

    何时认为操作成功，默认为 load。事件可以是以下之一：

    • 'domcontentloaded' - 当触发DOMContentLoaded事件时认为操作已完成。
    • 'load' - 当触发load事件时认为操作已完成。
    • 'networkidle' - 不建议使用 当至少500毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，应依赖网页断言来评估准备状态。
    • 'commit' - 当收到网络响应且文档开始加载时，认为操作已完成。

返回

• Promise<null | Response>#

前往​

返回主资源响应。在多次重定向的情况下，导航将解析为第一个非重定向响应。

该方法将在以下情况下抛出错误：

• 存在SSL错误（例如自签名证书的情况）。
• 目标URL无效。
• 在导航过程中超过了timeout。
• 远程服务器未响应或无法访问。
• 主资源加载失败。

当远程服务器返回任何有效的HTTP状态码时，该方法不会抛出错误，包括404"未找到"和500"内部服务器错误"。可以通过调用response.status()来获取此类响应的状态码。

用法

await page.goto(url);
await page.goto(url, options);

参数

• url string#

  页面要导航到的URL。该URL应包含协议，例如https://。当通过上下文选项提供了baseURL且传入的URL是路径时，将通过new URL()构造函数进行合并。

• options Object (可选)

  • referer string (可选)#

    Referer头信息值。如果提供此参数，它将优先于通过page.setExtraHTTPHeaders()设置的referer头信息值。

  • timeout number (可选)#

    操作的最长时间，单位为毫秒。默认为0表示无超时限制。默认值可以通过配置文件中的navigationTimeout选项进行修改，或者使用browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()或page.setDefaultTimeout()方法来设置。

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

    何时认为操作成功，默认为 load。事件可以是以下之一：

    • 'domcontentloaded' - 当触发DOMContentLoaded事件时认为操作已完成。
    • 'load' - 当触发load事件时认为操作已完成。
    • 'networkidle' - 不建议使用 当至少500毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，应依赖网页断言来评估准备状态。
    • 'commit' - 当收到网络响应且文档开始加载时，认为操作已完成。

返回

• Promise<null | Response>#

isClosed​

表示页面已关闭。

用法

page.isClosed();

返回

• boolean#

定位器​

该方法返回一个元素定位器，可用于在此页面/框架上执行操作。定位器在执行操作前会立即解析为对应元素，因此同一定位器上的一系列操作实际上可能作用于不同的DOM元素。如果这些操作之间的DOM结构发生了变化，就会出现这种情况。

了解更多关于定位器的信息。

用法

page.locator(selector);
page.locator(selector, options);

参数

• selector string#

  解析DOM元素时使用的选择器。

• options Object (可选)

  • has Locator (可选)#

    将方法的结果范围缩小到包含匹配此相对定位器的元素。例如，article 包含 text=Playwright 会匹配 <article><div>Playwright</div></article>。

    内部定位器必须相对于外部定位器，并且从外部定位器匹配开始查询，而不是文档根目录。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到包含 div 的 content。但是，查找包含 article div 的 content 会失败，因为内部定位器必须是相对的，不应使用 content 之外的任何元素。

    请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。

  • hasNot Locator (可选) 新增于: v1.33#

    匹配不包含符合内部定位器元素的元素。内部定位器会针对外部元素进行查询。例如，article元素不包含div时，会匹配<article><span>Playwright</span></article>。

    请注意外部和内部定位器必须属于同一个框架。内部定位器不能包含FrameLocator。

  • hasNotText string | RegExp (可选) 添加于: v1.33#

    匹配内部某处不包含指定文本的元素，可能在子元素或后代元素中。当传入string时，匹配不区分大小写并搜索子字符串。

  • hasText string | RegExp (可选)#

    匹配内部某处包含指定文本的元素，可能在子元素或后代元素中。当传入string时，匹配不区分大小写并搜索子字符串。例如，"Playwright"会匹配<article><div>Playwright</div></article>。

返回

• 定位器#

主框架​

页面的主框架。Page保证有一个主框架，在导航过程中持续存在。

用法

page.mainFrame();

返回

• Frame#

开启器​

返回弹出页面的开启者，其他情况返回null。如果开启者已被关闭，则返回null。

用法

await page.opener();

返回

• Promise<null | Page>#

暂停​

暂停脚本执行。Playwright将停止执行脚本，等待用户点击页面覆盖层中的'Resume'按钮或在开发者工具控制台中调用playwright.resume()。

用户可以在暂停时检查选择器或执行手动步骤。恢复将继续从暂停的地方运行原始脚本。

用法

await page.pause();

返回

• Promise<void>#

pdf​

返回PDF缓冲区。

page.pdf() 使用 print CSS媒体类型生成页面的PDF。要使用screen媒体类型生成PDF，请在调用page.pdf()之前先调用page.emulateMedia()：

用法

// Generates a PDF with 'screen' media type.
await page.emulateMedia({ media: 'screen' });
await page.pdf({ path: 'page.pdf' });

width、height和margin选项接受带有单位的数值。未标注单位的数值将被视为像素。

一些示例：

• page.pdf({width: 100}) - 打印时宽度设置为100像素
• page.pdf({width: '100px'}) - 打印时设置宽度为100像素
• page.pdf({width: '10cm'}) - 打印时设置宽度为10厘米。

所有可能的单位包括：

• px - 像素
• in - 英寸
• cm - 厘米
• mm - 毫米

format 的选项有：

• Letter: 8.5英寸 x 11英寸
• Legal: 8.5英寸 x 14英寸
• Tabloid: 11英寸 x 17英寸
• Ledger: 17英寸 x 11英寸
• A0: 33.1英寸 x 46.8英寸
• A1: 23.4英寸 x 33.1英寸
• A2: 16.54英寸 x 23.4英寸
• A3: 11.7英寸 x 16.54英寸
• A4: 8.27英寸 x 11.7英寸
• A5: 5.83英寸 x 8.27英寸
• A6: 4.13英寸 x 5.83英寸

参数

• options Object (optional)

  • displayHeaderFooter boolean (可选)#

    显示页眉和页脚。默认为 false。

  • footerTemplate string (optional)#

    HTML template for the print footer. Should use the same format as the headerTemplate.

  • format string (可选)#

    纸张格式。如果设置此项，优先级将高于width或height选项。默认为'Letter'。

  • headerTemplate string (可选)#

    HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:

    • 'date' 格式化打印日期
    • 'title' 文档标题
    • 'url' 文档位置
    • 'pageNumber' 当前页码
    • 'totalPages' 文档中的总页数

  • height string | number (可选)#

    纸张高度，接受带单位的数值。

  • landscape boolean (可选)#

    纸张方向。默认为 false。

  • margin Object (可选)#

    • top string | number (可选)

      上边距，接受带单位的数值。默认为 0。

    • right string | number (可选)

      右边距，接受带单位的数值。默认为 0。

    • bottom string | number (可选)

      底部边距，接受带单位的数值。默认为 0。

    • left string | number (可选)

      左边距，接受带单位的数值。默认为 0。

    纸张边距，默认为无。

  • outline boolean (可选) 添加于: v1.42#

    是否将文档大纲嵌入PDF中。默认为false。

  • pageRanges string (可选)#

    要打印的页码范围，例如'1-5, 8, 11-13'。默认为空字符串，表示打印所有页面。

  • path string (可选)#

    保存PDF的文件路径。如果path是相对路径，则相对于当前工作目录解析。如果没有提供路径，PDF将不会保存到磁盘。

  • preferCSSPageSize boolean (可选)#

    优先使用页面中声明的任何CSS @page尺寸，而不是width和height或format选项中声明的尺寸。默认为false，此时会将内容缩放以适应纸张大小。

  • printBackground boolean (可选)#

    打印背景图形。默认为 false。

  • scale number (可选)#

    网页渲染的缩放比例。默认为1。缩放值必须在0.1到2之间。

  • tagged boolean (可选) 添加于: v1.42#

    是否生成带标签(可访问)的PDF。默认为false。

  • width string | number (可选)#

    纸张宽度，接受带单位的数值。

返回

• Promise<Buffer>#

重新加载​

此方法会重新加载当前页面，就像用户触发了浏览器刷新一样。返回主资源响应。如果存在多次重定向，导航将以最后一次重定向的响应结果为准。

用法

await page.reload();
await page.reload(options);

参数

• options Object (optional)

  • timeout number (可选)#

    操作的最长时间，单位为毫秒。默认为0表示无超时限制。默认值可以通过配置文件中的navigationTimeout选项进行修改，或者使用browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()或page.setDefaultTimeout()方法来设置。

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

    何时认为操作成功，默认为 load。事件可以是以下之一：

    • 'domcontentloaded' - 当触发DOMContentLoaded事件时认为操作已完成。
    • 'load' - 当触发load事件时认为操作已完成。
    • 'networkidle' - 不建议使用 当至少500毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，应依赖网页断言来评估准备状态。
    • 'commit' - 当收到网络响应且文档开始加载时，认为操作已完成。

返回

• Promise<null | Response>#

removeAllListeners​

移除给定类型的所有监听器（如果未指定类型，则移除所有已注册的监听器）。允许等待异步监听器完成，或忽略这些监听器后续产生的错误。

用法

page.on('request', async request => {
  const response = await request.response();
  const body = await response.body();
  console.log(body.byteLength);
});
await page.goto('https://playwright.dev', { waitUntil: 'domcontentloaded' });
// Waits for all the reported 'request' events to resolve.
await page.removeAllListeners('request', { behavior: 'wait' });

参数

• type string (可选)#
• options Object (optional)

  • behavior "wait" | "ignoreErrors" | "default" (可选)#

    指定是否等待已运行的监听器以及当它们抛出错误时的处理方式：

    • 'default' - 不等待当前监听器调用(如果有)完成，如果监听器抛出异常，可能导致未处理的错误
    • 'wait' - 等待当前监听器调用（如果有）完成
    • 'ignoreErrors' - 不等待当前监听器调用(如果有)完成，移除后监听器抛出的所有错误将被静默捕获

返回

• Promise<void>#

removeLocatorHandler​

移除通过page.addLocatorHandler()为特定定位器添加的所有定位器处理程序。

用法

await page.removeLocatorHandler(locator);

参数

• locator Locator#

  传递给page.addLocatorHandler()的定位器。

返回

• Promise<void>#

requestGC​

请求页面执行垃圾回收。请注意，不能保证所有不可达对象都会被回收。

这有助于检测内存泄漏。例如，如果您的页面有一个可能泄漏的大型对象'suspect'，您可以通过使用WeakRef来检查它是否泄漏。

// 1. In your page, save a WeakRef for the "suspect".
await page.evaluate(() => globalThis.suspectWeakRef = new WeakRef(suspect));
// 2. Request garbage collection.
await page.requestGC();
// 3. Check that weak ref does not deref to the original object.
expect(await page.evaluate(() => !globalThis.suspectWeakRef.deref())).toBe(true);

用法

await page.requestGC();

返回

• Promise<void>#

路由​

路由功能提供了修改页面发出的网络请求的能力。

一旦启用路由功能，每个匹配URL模式的请求都将被挂起，除非它被继续、完成或中止。

用法

一个简单的处理程序示例，它会中止所有图片请求：

const page = await browser.newPage();
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
await page.goto('https://example.com');
await browser.close();

或者使用正则表达式模式替代的相同代码片段：

const page = await browser.newPage();
await page.route(/(\.png$)|(\.jpg$)/, route => route.abort());
await page.goto('https://example.com');
await browser.close();

可以检查请求来决定路由操作。例如，模拟所有包含某些post数据的请求，而保持其他所有请求不变：

await page.route('/api/**', async route => {
  if (route.request().postData().includes('my-string'))
    await route.fulfill({ body: 'mocked-data' });
  else
    await route.continue();
});

当请求同时匹配多个处理器时，页面路由（通过browserContext.route()设置）优先于浏览器上下文路由。

要移除带有处理程序的路由，可以使用page.unroute()。

参数

• url string | RegExp | function(URL):boolean#

  一个用于路由匹配的全局模式、正则表达式模式或接收URL的谓词函数。当通过上下文选项提供了baseURL且传入的URL是路径时，会通过new URL()构造函数进行合并。

• handler function(Route, Request):Promise<Object> | Object#

  用于路由请求的处理函数。

• options Object (可选)

  • times number (可选) 添加于: v1.15#

    路由应被使用的频率。默认情况下每次都会被使用。

返回

• Promise<void>#

从HAR文件创建路由​

如果指定了该选项，页面中发出的网络请求将从HAR文件中获取。了解更多关于从HAR回放的信息。

Playwright 不会处理由Service Worker从HAR文件中拦截的请求。请参阅此问题。我们建议在使用请求拦截时通过将serviceWorkers设置为'block'来禁用Service Workers。

用法

await page.routeFromHAR(har);
await page.routeFromHAR(har, options);

参数

• har string#

  指向包含预录制网络数据的HAR文件的路径。如果path是相对路径，则会相对于当前工作目录进行解析。

• options Object (可选)

  • notFound "abort" | "fallback" (可选)#

    • 如果设置为'abort'，任何在HAR文件中找不到的请求都将被中止。
    • 如果设置为'fallback'，缺失的请求将被发送到网络。

    默认为中止。

  • update boolean (可选)#

    如果指定，将使用实际的网络信息更新给定的HAR文件，而不是从文件提供。文件会在调用browserContext.close()时写入磁盘。

  • updateContent "embed" | "attach" (可选) 添加于: v1.32#

    控制资源内容管理的可选设置。如果指定了attach，资源将作为单独的文件或ZIP存档中的条目持久化。如果指定了embed，内容将内联存储在HAR文件中。

  • updateMode "full" | "minimal" (可选) 添加于: v1.32#

    当设置为minimal时，仅记录从HAR路由所必需的信息。这将省略大小、时间、页面、cookies、安全和其他类型的HAR信息，这些信息在从HAR回放时不会被使用。默认为minimal。

  • url string | RegExp (可选)#

    用于匹配请求URL的通配符模式、正则表达式或谓词函数。只有URL匹配该模式的请求才会从HAR文件中获取响应。如果未指定，则所有请求都将从HAR文件中获取响应。

返回

• Promise<void>#

routeWebSocket​

该方法允许修改由页面建立的websocket连接。

请注意，只有在此方法调用后创建的WebSocket才会被路由。建议在导航页面之前调用此方法。

用法

下面是一个简单模拟响应单条消息的示例。更多详情和示例请参见WebSocketRoute。

await page.routeWebSocket('/ws', ws => {
  ws.onMessage(message => {
    if (message === 'request')
      ws.send('response');
  });
});

参数

• url string | RegExp | function(URL):boolean#

  只有URL匹配此模式的WebSocket连接才会被路由。字符串模式可以相对于baseURL上下文选项。

• handler function(WebSocketRoute):Promise<Object> | Object#

  用于路由WebSocket的处理函数。

返回

• Promise<void>#

截图​

返回包含捕获屏幕截图的缓冲区。

用法

await page.screenshot();
await page.screenshot(options);

参数

• options Object (optional)

  • animations "disabled" | "allow" (可选)#

    当设置为"disabled"时，会停止CSS动画、CSS过渡和Web动画。动画会根据其持续时间受到不同的处理：

    • 有限动画会被快进到完成状态，因此会触发transitionend事件。
    • 无限循环动画会被取消回到初始状态，截图完成后会重新播放。

    默认为"allow"，表示保持动画原样不做处理。

  • caret "hide" | "initial" (可选)#

    当设置为"hide"时，截图将隐藏文本光标。当设置为"initial"时，文本光标行为将保持不变。默认为"hide"。

  • clip Object (可选)#

    • x number

      裁剪区域左上角的x坐标

    • y number

      裁剪区域左上角的y坐标

    • width number

      裁剪区域的宽度

    • height number

      裁剪区域的高度

    一个指定结果图像裁剪范围的对象。

  • fullPage boolean (可选)#

    当设置为true时，会截取整个可滚动页面的截图，而不是当前可见的视口区域。默认为false。

  • 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像素生成一个像素。对于高DPI设备，这将保持截图较小。使用"device"选项将为每个设备像素生成一个像素，因此高DPI设备的截图会是两倍甚至更大。

    默认为"device"。

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

    在截图时应用的样式表文本。在这里您可以隐藏动态元素、使元素不可见或更改其属性，以帮助创建可重复的截图。此样式表穿透Shadow DOM并应用于内部框架。

  • timeout number (可选)#

    最大时间，单位为毫秒。默认为 0 - 表示无超时限制。默认值可以通过配置文件中的 actionTimeout 选项进行修改，或者使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法进行设置。

  • type "png" | "jpeg" (可选)#

    指定截图类型，默认为png。

返回

• Promise<Buffer>#

setContent​

此方法内部调用document.write()，继承了其所有特定特性和行为。

用法

await page.setContent(html);
await page.setContent(html, options);

参数

• html string#

  HTML markup to assign to the page.

• options Object (可选)

  • timeout number (可选)#

    操作的最长时间，单位为毫秒。默认为0表示无超时限制。默认值可以通过配置文件中的navigationTimeout选项进行修改，或者使用browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()或page.setDefaultTimeout()方法来设置。

  • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

    何时认为操作成功，默认为 load。事件可以是以下之一：

    • 'domcontentloaded' - 当触发DOMContentLoaded事件时认为操作已完成。
    • 'load' - 当触发load事件时认为操作已完成。
    • 'networkidle' - 不建议使用 当至少500毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，应依赖网页断言来评估准备状态。
    • 'commit' - 当收到网络响应且文档开始加载时，认为操作已完成。

返回

• Promise<void>#

setDefaultNavigationTimeout​

此设置将更改以下方法及相关快捷方式的默认最大导航时间：

• page.goBack()
• page.goForward()
• page.goto()
• page.reload()
• page.setContent()
• page.waitForNavigation()
• page.waitForURL()

用法

page.setDefaultNavigationTimeout(timeout);

参数

• timeout number#

  最大导航时间（毫秒）

setDefaultTimeout​

此设置将更改所有接受timeout选项的方法的默认最大时间。

用法

page.setDefaultTimeout(timeout);

参数

• timeout number#

  最大时间，单位为毫秒。传入0表示禁用超时。

setExtraHTTPHeaders​

额外的HTTP头信息将与页面发起的每个请求一起发送。

用法

await page.setExtraHTTPHeaders(headers);

参数

• headers Object<string, string>#

  一个包含要随每个请求发送的额外HTTP头信息的对象。所有头信息的值都必须是字符串。

返回

• Promise<void>#

setViewportSize​

在单个浏览器中存在多个页面的情况下，每个页面都可以有自己的视口尺寸。不过，browser.newContext()允许一次性为上下文中的所有页面设置视口尺寸（以及其他参数）。

page.setViewportSize() 会调整页面尺寸。许多网站并未考虑手机会改变尺寸的情况，因此您应在导航到页面之前设置视口大小。page.setViewportSize() 同时会重置 screen 尺寸，若您需要更好地控制这些属性，请使用带有 screen 和 viewport 参数的 browser.newContext()。

用法

const page = await browser.newPage();
await page.setViewportSize({
  width: 640,
  height: 480,
});
await page.goto('https://example.com');

参数

• viewportSize Object#

  • width number

    页面宽度，单位为像素。

  • height number

    页面高度，单位为像素。

返回

• Promise<void>#

标题​

返回页面的标题。

用法

await page.title();

返回

• Promise<string>#

取消路由​

移除通过page.route()创建的路由。当未指定handler时，会移除该url的所有路由。

用法

await page.unroute(url);
await page.unroute(url, handler);

参数

• url string | RegExp | function(URL):boolean#

  在路由时用于匹配URL的全局模式、正则表达式模式或接收URL的谓词函数。

• handler function(Route, Request):Promise<Object> | Object (可选)#

  用于路由请求的可选处理函数。

返回

• Promise<void>#

unrouteAll​

移除所有通过page.route()和page.routeFromHAR()创建的路由。

用法

await page.unrouteAll();
await page.unrouteAll(options);

参数

• options Object (optional)

  • behavior "wait" | "ignoreErrors" | "default" (可选)#

    指定是否等待已运行的处理器以及当它们抛出错误时的处理方式：

    • 'default' - 不等待当前处理程序调用(如果有)完成，如果未路由的处理程序抛出异常，可能导致未处理的错误
    • 'wait' - 等待当前处理程序调用（如果有）完成
    • 'ignoreErrors' - 不等待当前处理程序调用（如果有）完成，取消路由后由处理程序抛出的所有错误将被静默捕获

返回

• Promise<void>#

网址​

用法

page.url();

返回

• string#

视频​

与此页面关联的视频对象。

用法

page.video();

返回

• null | 视频#

视口尺寸​

用法

page.viewportSize();

返回

• null | Object#

  • width number

    页面宽度，单位为像素。

  • height number

    页面高度，单位为像素。

waitForEvent​

等待事件触发并将其值传递给谓词函数。当谓词返回真值时返回。如果在事件触发前页面已关闭，将抛出错误。返回事件数据值。

用法

// Start waiting for download before clicking. Note no await.
const downloadPromise = page.waitForEvent('download');
await page.getByText('Download file').click();
const download = await downloadPromise;

参数

• event string#

  事件名称，通常与传入*.on(event)中的名称相同。

• optionsOrPredicate function | Object (可选)#

  • predicate function

    接收事件数据，当等待应解决时解析为真值。

  • timeout number (可选)

    等待的最长时间，以毫秒为单位。默认为0 - 无超时。默认值可以通过配置文件中的actionTimeout选项进行更改，或者使用browserContext.setDefaultTimeout()或page.setDefaultTimeout()方法进行设置。

  可以是一个接收事件的谓词函数，也可以是一个选项对象。可选参数。

• options Object (可选)

  • predicate function (可选)#

    接收事件数据，当等待应解决时解析为真值。

返回

• Promise<Object>#

waitForFunction​

当pageFunction返回真值时触发。它会解析为该真值的JSHandle对象。

用法

page.waitForFunction() 可用于观察视口大小的变化：

const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.

(async () => {
  const browser = await webkit.launch();
  const page = await browser.newPage();
  const watchDog = page.waitForFunction(() => window.innerWidth < 100);
  await page.setViewportSize({ width: 50, height: 50 });
  await watchDog;
  await browser.close();
})();

要向page.waitForFunction()函数的谓词传递参数：

const selector = '.foo';
await page.waitForFunction(selector => !!document.querySelector(selector), selector);

参数

• pageFunction function | string#

  要在页面上下文中评估的函数。

• arg EvaluationArgument (可选)#

  传递给pageFunction的可选参数。

• options Object (可选)

  • polling number | "raf" (可选)#

    如果polling设置为'raf'，则pageFunction会在requestAnimationFrame回调中持续执行。如果polling是一个数字，则被视为函数执行的间隔时间（毫秒）。默认为raf。

  • timeout number (可选)#

    最大等待时间，单位为毫秒。默认为0 - 表示无超时限制。默认值可以通过配置文件中的actionTimeout选项进行修改，或者使用browserContext.setDefaultTimeout()或page.setDefaultTimeout()方法来更改。

返回

• Promise<JSHandle>#

waitForLoadState​

当所需的加载状态达到时返回。

当页面达到所需的加载状态（默认为load）时，此问题将得到解决。调用此方法时，导航必须已提交。如果当前文档已达到所需状态，则立即解决。

用法

await page.getByRole('button').click(); // Click triggers navigation.
await page.waitForLoadState(); // The promise resolves after 'load' event.

const popupPromise = page.waitForEvent('popup');
await page.getByRole('button').click(); // Click triggers a popup.
const popup = await popupPromise;
await popup.waitForLoadState('domcontentloaded'); // Wait for the 'DOMContentLoaded' event.
console.log(await popup.title()); // Popup is ready to use.

参数

• state "load" | "domcontentloaded" | "networkidle" (可选)#

  可选的加载状态等待参数，默认为load。如果在加载当前文档时已经达到该状态，则该方法会立即解析。可以是以下之一：

  • 'load' - 等待触发load事件。
  • 'domcontentloaded' - 等待触发DOMContentLoaded事件。
  • 'networkidle' - 不推荐使用 等待直到至少500毫秒内没有网络连接。不要将此方法用于测试，应依赖web断言来评估准备状态。

• options Object (可选)

  • timeout number (可选)#

    操作的最长时间，单位为毫秒。默认为0表示无超时限制。默认值可以通过配置文件中的navigationTimeout选项进行修改，或者使用browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout()或page.setDefaultTimeout()方法来设置。

返回

• Promise<void>#

waitForRequest​

等待匹配的请求并返回它。有关事件的更多详情，请参阅waiting for event。

用法

// Start waiting for request before clicking. Note no await.
const requestPromise = page.waitForRequest('https://example.com/resource');
await page.getByText('trigger request').click();
const request = await requestPromise;

// Alternative way with a predicate. Note no await.
const requestPromise = page.waitForRequest(request =>
  request.url() === 'https://example.com' && request.method() === 'GET',
);
await page.getByText('trigger request').click();
const request = await requestPromise;

参数

• urlOrPredicate string | RegExp | function(Request):boolean | Promise<boolean>#

  请求URL字符串、正则表达式或接收Request对象的谓词函数。

• options Object (可选)

  • timeout number (可选)#

    最大等待时间（毫秒），默认为30秒，传入0表示禁用超时。默认值可以通过page.setDefaultTimeout()方法修改。

返回

• Promise<Request>#

waitForResponse​

返回匹配的响应。有关事件的更多详情，请参阅waiting for event。

用法

// Start waiting for response before clicking. Note no await.
const responsePromise = page.waitForResponse('https://example.com/resource');
await page.getByText('trigger response').click();
const response = await responsePromise;

// Alternative way with a predicate. Note no await.
const responsePromise = page.waitForResponse(response =>
  response.url() === 'https://example.com' && response.status() === 200
      && response.request().method() === 'GET'
);
await page.getByText('trigger response').click();
const response = await responsePromise;