跳到主要內容

Page

Page 提供了與 Browser 中的單個分頁互動，或 Chromium 中擴充功能背景頁面的方法。一個 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.js 原生 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​

在 v1.9 版本之前新增 page.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);
注意

透過 browserContext.addInitScript() 和 page.addInitScript() 安裝的多個腳本的評估順序未定義。

引數

  • script function | string | Object#

    • path string (選用)

      JavaScript 檔案的路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。選用。

    • content string (選用)

      原始腳本內容。選用。

    要在頁面中評估的腳本。

  • arg Serializable (選用)#

    要傳遞給 script 的選用引數（僅在傳遞函數時支援）。

傳回

addLocatorHandler​

新增於：v1.42 page.addLocatorHandler

在測試網頁時，有時會出現意外的覆蓋層，例如「註冊」對話方塊，並阻止您想要自動化的操作，例如點擊按鈕。這些覆蓋層不一定以相同的方式或在同一時間顯示，因此在自動化測試中很難處理。

此方法可讓您設定一個特殊的函數（稱為處理常式），當偵測到覆蓋層可見時，該函數會啟動。處理常式的工作是移除覆蓋層，讓您的測試繼續進行，就像覆蓋層不存在一樣。

注意事項

  • 當覆蓋層可預測地顯示時，我們建議在您的測試中明確等待它，並將其作為正常測試流程的一部分解除，而不是使用 page.addLocatorHandler()。
  • Playwright 在每次執行或重試需要 可操作性檢查 的操作之前，或在執行自動等待斷言檢查之前，都會檢查覆蓋層。當覆蓋層可見時，Playwright 會先呼叫處理常式，然後繼續執行操作/斷言。請注意，只有在您執行操作/斷言時才會呼叫處理常式 - 如果覆蓋層變得可見，但您未執行任何操作，則不會觸發處理常式。
  • 執行處理常式後，Playwright 將確保觸發處理常式的覆蓋層不再可見。您可以使用 noWaitAfter 選擇退出此行為。
  • 處理常式的執行時間計入執行處理常式的操作/斷言的逾時時間。如果您的處理常式花費太長時間，可能會導致逾時。
  • 您可以註冊多個處理常式。但是，一次只會執行一個處理常式。請確保處理常式內的操作不依賴另一個處理常式。
警告

執行處理常式將在測試過程中變更您的頁面狀態。例如，它會變更目前焦點元素並移動滑鼠。請確保在處理常式之後執行的操作是獨立的，並且不依賴焦點和滑鼠狀態保持不變。

例如，考慮一個測試，該測試呼叫 locator.focus()，然後呼叫 keyboard.press()。如果您的處理常式在這兩個操作之間點擊一個按鈕，則焦點元素很可能不正確，並且按鍵會發生在意外的元素上。請改用 locator.press() 以避免此問題。

另一個範例是一系列滑鼠操作，其中 mouse.move() 後面接著 mouse.down()。同樣，當處理常式在這兩個操作之間執行時，滑鼠位置在滑鼠按下期間會不正確。請偏好獨立的操作，例如 locator.click()，這些操作不依賴處理常式變更狀態。

用法

關閉「註冊電子報」對話方塊（當它出現時）的範例

// 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();

具有每個可操作性檢查的自訂回呼的範例。它使用始終可見的 <body> 定位器，因此在每次可操作性檢查之前都會呼叫處理常式。指定 noWaitAfter 很重要，因為處理常式不會隱藏 <body> 元素。

// 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();

處理常式將原始定位器作為引數。您也可以透過設定 times 在多次調用後自動移除處理常式

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 將等待直到覆蓋層變成隱藏，然後 Playwright 才會繼續執行觸發處理常式的操作/斷言。此選項允許選擇退出此行為，以便覆蓋層可以在處理常式執行後保持可見。

    • times number (選用)新增於：v1.44#

      指定應呼叫此處理常式的最大次數。預設為無限次數。

傳回

addScriptTag​

在 v1.9 版本之前新增 page.addScriptTag

將 <script> 標籤新增到具有所需 URL 或內容的頁面中。當腳本的 onload 事件觸發或腳本內容注入到框架中時，傳回新增的標籤。

用法

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

引數

  • options Object (選用)

    • content string (選用)#

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

    • path string (選用)#

      要注入到框架中的 JavaScript 檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。

    • type string (選用)#

      腳本類型。使用 'module' 以載入 JavaScript ES6 模組。請參閱 script 以取得更多詳細資訊。

    • url string (選用)#

      要新增的腳本的 URL。

傳回

addStyleTag​

在 v1.9 版本之前新增 page.addStyleTag

將具有所需 URL 的 <link rel="stylesheet"> 標籤或具有內容的 <style type="text/css"> 標籤新增到頁面中。當樣式表的 onload 事件觸發或 CSS 內容注入到框架中時，傳回新增的標籤。

用法

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

引數

  • options Object (選用)

    • content string (選用)#

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

    • path string (選用)#

      要注入到框架中的 CSS 檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。

    • url string (選用)#

      <link> 標籤的 URL。

傳回

bringToFront​

在 v1.9 版本之前新增 page.bringToFront

將頁面帶到最前面（啟動分頁）。

用法

await page.bringToFront();

傳回

close​

在 v1.9 版本之前新增 page.close

如果 runBeforeUnload 為 false，則不執行任何卸載處理常式，並等待頁面關閉。如果 runBeforeUnload 為 true，則此方法將執行卸載處理常式，但不會等待頁面關閉。

預設情況下，page.close() 不會執行 beforeunload 處理常式。

注意

如果 runBeforeUnload 作為 true 傳遞，則可能會召喚 beforeunload 對話方塊，應透過 page.on('dialog') 事件手動處理。

用法

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

引數

  • options Object (選用)

    • reason string (選用)新增於：v1.40#

      要報告給頁面關閉中斷的操作的原因。

    • runBeforeUnload boolean (選用)#

      預設為 false。是否執行 before unload 頁面處理常式。

傳回

content​

在 v1.9 版本之前新增 page.content

取得頁面的完整 HTML 內容，包括 doctype。

用法

await page.content();

傳回

context​

在 v1.9 版本之前新增 page.context

取得頁面所屬的瀏覽器內容。

用法

page.context();

傳回

dragAndDrop​

新增於：v1.13 page.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#

      在來源元素上，相對於元素內邊距框的左上角，點擊此點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • targetPosition Object (選用)新增於：v1.14#

      在目標元素上，相對於元素內邊距框的左上角，放置在此點。如果未指定，則使用元素的某些可見點。

    • timeout number (選用)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

    • trial boolean (選用)#

      設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好執行動作時很有用。

傳回

emulateMedia​

在 v1.9 版本之前新增 page.emulateMedia

此方法透過 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 (選用)

    • colorScheme null | "light" | "dark" | "no-preference" (選用)新增於：v1.9#

      模擬 prefers-colors-scheme 媒體功能，支援的值為 'light' 和 'dark'。傳遞 null 會停用色彩配置模擬。'no-preference' 已棄用。

    • 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 會停用減少動態效果模擬。

傳回

evaluate​

在 v1.9 版本之前新增 page.evaluate

傳回 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();

引數

傳回

evaluateHandle​

在 v1.9 版本之前新增 page.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();

引數

傳回

exposeBinding​

在 v1.9 版本之前新增 page.exposeBinding

此方法在頁面中每個框架的 window 物件上新增一個名為 name 的函數。呼叫時，該函數會執行 callback 並傳回一個 Promise，該 Promise 解析為 callback 的傳回值。如果 callback 傳回 Promise，則將會等待它。

callback 函數的第一個引數包含關於呼叫者的資訊：{ browserContext: BrowserContext, page: Page, frame: Frame }。

請參閱 browserContext.exposeBinding() 以取得內容範圍版本。

注意

透過 page.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)#

    window 物件上的函式名稱。

  • callback 函式 (function)#

    將在 Playwright 環境中呼叫的回呼函式。

  • options Object (選用)

    • handle 布林值 (boolean) (選填)#

      已棄用

      此選項將在未來移除。

      是否將引數作為 handle 傳遞，而不是傳值。當傳遞 handle 時，僅支援一個引數。當傳值時，支援多個引數。

傳回

exposeFunction​

在 v1.9 版本之前新增 page.exposeFunction

此方法在頁面中每個 frame 的 window 物件上新增一個名為 name 的函式。當被呼叫時，此函式會執行 callback 並回傳一個 Promise，此 Promise 會解析為 callback 的回傳值。

如果 callback 回傳一個 Promise，則會等待其完成。

請參閱 browserContext.exposeFunction() 以了解 context-wide 暴露函式。

注意

透過 page.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');
})();

引數

傳回

frame​

在 v1.9 版本之前新增 page.frame

回傳符合指定條件的 frame。必須指定 name 或 url 其中一個。

用法

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

引數

傳回

frameLocator​

新增於：v1.17 page.frameLocator

當使用 iframe 時，您可以建立一個 frame locator，它將進入 iframe 並允許在該 iframe 中選取元素。

用法

以下程式碼片段在 id 為 my-frame 的 iframe 中，找到文字為 "Submit" 的元素，例如 <iframe id="my-frame">

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

引數

傳回

frames​

在 v1.9 版本之前新增 page.frames

附加到頁面的所有 frame 的陣列。

用法

page.frames();

傳回

getByAltText​

新增於：v1.27 page.getByAltText

允許透過元素的 alt 文字定位元素。

用法

例如，此方法將透過 alt 文字 "Playwright logo" 找到圖片

<img alt='Playwright logo'>
await page.getByAltText('Playwright logo').click();

引數

傳回

getByLabel​

新增於：v1.27 page.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');

引數

傳回

getByPlaceholder​

新增於：v1.27 page.getByPlaceholder

允許透過 placeholder 文字定位輸入元素。

用法

例如，考慮以下 DOM 結構。

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

您可以在透過 placeholder 文字定位輸入框後，填寫內容

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

引數

傳回

getByRole​

新增於：v1.27 page.getByRole

允許透過元素的 ARIA role、ARIA 屬性和 accessible name 定位元素。

用法

考慮以下 DOM 結構。

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

您可以透過每個元素的隱含 role 定位它們

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 role。

  • options Object (選用)

傳回

詳細資訊

Role selector 並不能取代 accessibility 稽核和一致性測試，而是提供關於 ARIA 指南的早期回饋。

許多 html 元素具有 role selector 識別的隱含定義 role。您可以在此處找到所有支援的 role。ARIA 指南不建議透過將 role 和/或 aria-* 屬性設定為預設值來複製隱含 role 和屬性。

getByTestId​

新增於：v1.27 page.getByTestId

透過 test id 定位元素。

用法

考慮以下 DOM 結構。

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

您可以透過元素的 test id 定位它

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

引數

傳回

詳細資訊

預設情況下，data-testid 屬性用作 test id。如有必要，請使用 selectors.setTestIdAttribute() 來設定不同的 test id 屬性。

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

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

getByText​

新增於：v1.27 page.getByText

允許定位包含給定文字的元素。

另請參閱 locator.filter()，它允許透過其他條件（例如 accessible role）進行比對，然後透過文字內容進行篩選。

用法

考慮以下 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);

引數

傳回

詳細資訊

即使是完全符合，透過文字比對也總是會正規化空白字元。例如，它將多個空格變成一個，將換行符號變成空格，並忽略開頭和結尾的空白字元。

類型為 button 和 submit 的輸入元素會透過它們的 value 而不是文字內容進行比對。例如，透過文字 "Log in" 定位會比對 <input type=button value="Log in">。

getByTitle​

新增於：v1.27 page.getByTitle

允許透過元素的 title 屬性定位元素。

用法

考慮以下 DOM 結構。

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

您可以在透過 title 文字定位後，檢查 issues 數量

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

引數

傳回

goBack​

在 v1.9 版本之前新增 page.goBack

回傳主要資源回應。在多個重定向的情況下，導航將解析為最後一個重定向的回應。如果無法返回，則回傳 null。

導航到歷史記錄中的上一頁。

用法

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

引數

  • options Object (選用)

    • timeout 數字 (number) (選填)#

      最大操作時間，以毫秒為單位。預設為 0 - 無 timeout。預設值可以透過 config 中的 navigationTimeout 選項更改，或使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法。

    • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (選填)#

      何時視為操作成功，預設為 load。事件可以是：

      • 'domcontentloaded' - 當 DOMContentLoaded 事件被觸發時，視為操作完成。
      • 'load' - 當 load 事件被觸發時，視為操作完成。
      • 'networkidle' - 不建議使用 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，請改為依賴 web assertions 來評估就緒狀態。
      • 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

goForward​

在 v1.9 版本之前新增 page.goForward

回傳主要資源回應。在多個重定向的情況下，導航將解析為最後一個重定向的回應。如果無法前進，則回傳 null。

導航到歷史記錄中的下一頁。

用法

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

引數

  • options Object (選用)

    • timeout 數字 (number) (選填)#

      最大操作時間，以毫秒為單位。預設為 0 - 無 timeout。預設值可以透過 config 中的 navigationTimeout 選項更改，或使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法。

    • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (選填)#

      何時視為操作成功，預設為 load。事件可以是：

      • 'domcontentloaded' - 當 DOMContentLoaded 事件被觸發時，視為操作完成。
      • 'load' - 當 load 事件被觸發時，視為操作完成。
      • 'networkidle' - 不建議使用 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，請改為依賴 web assertions 來評估就緒狀態。
      • 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

goto​

在 v1.9 版本之前新增 page.goto

回傳主要資源回應。在多個重定向的情況下，導航將解析為第一個非重定向的回應。

如果發生以下情況，此方法將拋出錯誤：

  • 發生 SSL 錯誤 (例如，在自簽憑證的情況下)。
  • 目標 URL 無效。
  • 在導航期間超過 timeout 時間。
  • 遠端伺服器沒有回應或無法連線。
  • 主要資源載入失敗。

當遠端伺服器回傳任何有效的 HTTP 狀態碼時，此方法不會拋出錯誤，包括 404 "Not Found" 和 500 "Internal Server Error"。此類回應的狀態碼可以透過呼叫 response.status() 取得。

注意

此方法要么拋出錯誤，要么回傳主要資源回應。唯一的例外是導航到 about:blank 或導航到具有不同雜湊的相同 URL，這將成功並回傳 null。

注意

無頭模式不支援導航到 PDF 文件。請參閱 upstream issue。

用法

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

引數

  • url 字串 (string)#

    要導航頁面到的 URL。url 應包含 scheme，例如 https://。當透過 context 選項提供了 baseURL，且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。

  • options Object (選用)

    • referer 字串 (string) (選填)#

      Referer 標頭值。如果提供，它將優先於 page.setExtraHTTPHeaders() 設定的 referer 標頭值。

    • timeout 數字 (number) (選填)#

      最大操作時間，以毫秒為單位。預設為 0 - 無 timeout。預設值可以透過 config 中的 navigationTimeout 選項更改，或使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法。

    • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (選填)#

      何時視為操作成功，預設為 load。事件可以是：

      • 'domcontentloaded' - 當 DOMContentLoaded 事件被觸發時，視為操作完成。
      • 'load' - 當 load 事件被觸發時，視為操作完成。
      • 'networkidle' - 不建議使用 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，請改為依賴 web assertions 來評估就緒狀態。
      • 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

isClosed​

在 v1.9 版本之前新增 page.isClosed

指示頁面已關閉。

用法

page.isClosed();

傳回

locator​

新增於：v1.14 page.locator

此方法回傳一個元素 locator，可用於在此頁面/frame 上執行動作。Locator 會在執行動作之前立即解析為元素，因此在同一個 locator 上執行的一系列動作實際上可以在不同的 DOM 元素上執行。如果這些動作之間的 DOM 結構發生變化，就會發生這種情況。

深入了解 locators.

用法

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

引數

  • selector 字串 (string)#

    用於解析 DOM 元素的 selector。

  • options Object (選用)

    • has Locator (選填)#

      將此方法的结果缩小到那些包含与此相对定位器匹配的元素的元素。例如，具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。

      內部 locator 必須相對於外部 locator，並且查詢從外部 locator 比對開始，而不是從文件根目錄開始。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到具有 div 的 content。但是，尋找具有 article div 的 content 將會失敗，因為內部 locator 必須是相對的，並且不應使用 content 之外的任何元素。

      請注意，外部和內部 locator 必須屬於同一個 frame。內部 locator 不得包含 FrameLocator。

    • hasNot Locator (選填)新增於：v1.33#

      比對不包含與內部 locator 比對的元素的元素。內部 locator 是針對外部 locator 查詢的。例如，不具有 div 的 article 匹配 <article><span>Playwright</span></article>。

      請注意，外部和內部 locator 必須屬於同一個 frame。內部 locator 不得包含 FrameLocator。

    • hasNotText 字串 (string) | 正規表示式 (RegExp) (選填)新增於：v1.33#

      比對不包含指定文字在內部的某處的元素，可能在子元素或後代元素中。當傳遞字串時，比對不區分大小寫並搜尋子字串。

    • hasText 字串 (string) | 正規表示式 (RegExp) (選填)#

      比對包含指定文字在內部的某處的元素，可能在子元素或後代元素中。當傳遞字串時，比對不區分大小寫並搜尋子字串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

傳回

mainFrame​

在 v1.9 版本之前新增 page.mainFrame

頁面的主要框架。保證 Page 會有一個在導航期間持續存在的主要框架。

用法

page.mainFrame();

傳回

opener​

在 v1.9 版本之前新增 page.opener

為彈出式頁面返回 opener，為其他頁面返回 null。如果 opener 已經關閉，則返回 null。

用法

await page.opener();

傳回

pause​

新增於：v1.9 page.pause

暫停腳本執行。Playwright 將停止執行腳本，並等待使用者按下頁面覆蓋中的「繼續」按鈕，或在 DevTools 控制台中呼叫 playwright.resume()。

使用者可以在暫停時檢查選擇器或執行手動步驟。「繼續」將從暫停的位置繼續執行原始腳本。

注意

此方法需要 Playwright 在有 head 模式下啟動，且 headless 選項為 falsy。

用法

await page.pause();

傳回

pdf​

在 v1.9 版本之前新增 page.pdf

返回 PDF buffer。

page.pdf() 使用 print css media 生成頁面的 pdf。若要使用 screen media 生成 pdf，請在呼叫 page.pdf() 之前呼叫 page.emulateMedia()。

注意

預設情況下，page.pdf() 生成的 pdf 會修改列印顏色。使用 -webkit-print-color-adjust 屬性強制渲染精確的顏色。

用法

// 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 英吋
注意

headerTemplate 和 footerTemplate 標記有以下限制： > 1. 範本內的 Script 標籤不會被評估。 > 2. 頁面樣式在範本內不可見。

引數

  • options Object (選用)

    • displayHeaderFooter boolean (可選)#

      顯示頁首和頁尾。預設為 false。

    • footerTemplate string (可選)#

      用於列印頁尾的 HTML 範本。應使用與 headerTemplate 相同的格式。

    • format string (可選)#

      紙張格式。如果設定，則優先於 width 或 height 選項。預設為 'Letter'。

    • headerTemplate string (可選)#

      用於列印頁首的 HTML 範本。應為有效的 HTML 標記，並使用以下類別將列印值注入其中

      • '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 (可選)#

      紙張寬度，接受帶有單位的數值。

傳回

reload​

在 v1.9 版本之前新增 page.reload

此方法重新載入目前頁面，方式與使用者觸發瀏覽器重新整理相同。返回主要資源回應。在多次重新導向的情況下，導航將以最後一次重新導向的回應解析。

用法

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

引數

  • options Object (選用)

    • timeout number (可選)#

      最大操作時間，以毫秒為單位。預設為 0 - 無 timeout。預設值可以透過 config 中的 navigationTimeout 選項更改，或使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法。

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

      何時視為操作成功，預設為 load。事件可以是：

      • 'domcontentloaded' - 當 DOMContentLoaded 事件被觸發時，視為操作完成。
      • 'load' - 當 load 事件被觸發時，視為操作完成。
      • 'networkidle' - 不建議使用 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，請改為依賴 web assertions 來評估就緒狀態。
      • 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

removeAllListeners​

新增於：v1.47 page.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.org.tw', { waitUntil: 'domcontentloaded' });
// Waits for all the reported 'request' events to resolve.
await page.removeAllListeners('request', { behavior: 'wait' });

引數

  • type string (可選)#
  • options Object (選用)

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

      指定是否等待已在執行的監聽器，以及如果它們拋出錯誤時該怎麼做

      • 'default' - 不等待當前監聽器呼叫 (如果有的話) 完成，如果監聽器拋出錯誤，可能會導致未處理的錯誤
      • 'wait' - 等待當前監聽器呼叫 (如果有的話) 完成
      • 'ignoreErrors' - 不等待當前監聽器呼叫 (如果有的話) 完成，移除後監聽器拋出的所有錯誤都會被靜默捕獲

傳回

removeLocatorHandler​

新增於：v1.44 page.removeLocatorHandler

移除由 page.addLocatorHandler() 為特定 locator 新增的所有 locator 處理程序。

用法

await page.removeLocatorHandler(locator);

引數

傳回

requestGC​

新增於：v1.48 page.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();

傳回

route​

在 v1.9 版本之前新增 page.route

路由提供了修改頁面發出的網路請求的功能。

一旦啟用路由，每個符合 url 模式的請求都會暫停，除非它被繼續、滿足或中止。

注意

如果回應是重新導向，則只會為第一個 url 呼叫處理程序。

注意

page.route() 不會攔截 Service Worker 攔截的請求。請參閱 此 問題。我們建議在使用請求攔截時停用 Service Worker，方法是將 serviceWorkers 設定為 'block'。

注意

page.route() 不會攔截彈出式頁面的第一個請求。請改用 browserContext.route()。

用法

一個中止所有圖片請求的簡單處理程序範例

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

或使用 regex 模式的相同程式碼片段

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()。

注意

啟用路由會停用 http 快取。

引數

傳回

routeFromHAR​

新增於：v1.23 page.routeFromHAR

如果指定，則頁面中發出的網路請求將從 HAR 檔案提供。閱讀更多關於 從 HAR 重新播放。

Playwright 不會從 HAR 檔案提供 Service Worker 攔截的請求。請參閱 此 問題。我們建議在使用請求攔截時停用 Service Worker，方法是將 serviceWorkers 設定為 'block'。

用法

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 路由所需的資訊。這省略了大小、時間、頁面、cookie、安全性以及其他在從 HAR 重新播放時未使用的 HAR 資訊。預設為 minimal。

    • url string | RegExp (可選)#

      用於匹配請求 URL 的 glob 模式、正則表達式或謂詞。只有 URL 符合模式的請求才會從 HAR 檔案提供。如果未指定，則所有請求都從 HAR 檔案提供。

傳回

routeWebSocket​

新增於：v1.48 page.routeWebSocket

此方法允許修改頁面建立的 websocket 連線。

請注意，只有在此方法被呼叫後建立的 WebSockets 才会被路由。建議在導航頁面之前呼叫此方法。

用法

以下是一個簡單 mock 的範例，它回應單一訊息。請參閱 WebSocketRoute 以取得更多詳細資訊和範例。

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

引數

傳回

screenshot​

在 v1.9 版本之前新增 page.screenshot

返回包含已捕獲螢幕截圖的 buffer。

用法

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

引數

  • options Object (選用)

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

      當設定為 "disabled" 時，停止 CSS 動畫、CSS 過渡和 Web Animations。動畫會根據其持續時間獲得不同的處理

      • 有限動畫會快速轉發到完成，因此它們會觸發 transitionend 事件。
      • 無限動畫會取消到初始狀態，然後在螢幕截圖後重新播放。

      預設為 "allow"，保持動畫不受影響。

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

      當設定為 "hide" 時，螢幕截圖將隱藏文字游標。當設定為 "initial" 時，文字游標行為將不會更改。預設為 "hide"。

    • clip Object (可選)#

      • x number

        剪裁區域左上角的 x 座標

      • y number

        剪裁區域左上角的 y 座標

      • width number

        剪裁區域的寬度

      • height number

        剪裁區域的高度

      指定結果影像剪裁的物件。

    • fullPage boolean (可選)#

      如果為 true，則拍攝整個可滾動頁面的螢幕截圖，而不是目前可見的 viewport。預設為 false。

    • mask Array<Locator> (可選)#

      指定在拍攝螢幕截圖時應遮罩的 locator。遮罩的元素將以粉紅色框 #FF00FF (由 maskColor 自訂) 覆蓋，該框完全覆蓋其邊界框。

    • 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 (可選)新增於：v1.41#

      製作螢幕截圖時要套用的樣式表文字。您可以在此處隱藏動態元素、使元素不可見或變更其屬性，以協助您建立可重複的螢幕截圖。此樣式表會穿透 Shadow DOM 並套用於內部框架。

    • timeout number (可選)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

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

      指定螢幕截圖類型，預設為 png。

傳回

setContent​

在 v1.9 版本之前新增 page.setContent

此方法在內部呼叫 document.write()，繼承其所有特定特性和行為。

用法

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

引數

  • html string#

    要指派給頁面的 HTML 標記。

  • options Object (選用)

    • timeout number (可選)#

      最大操作時間，以毫秒為單位。預設為 0 - 無 timeout。預設值可以透過 config 中的 navigationTimeout 選項更改，或使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法。

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

      何時視為操作成功，預設為 load。事件可以是：

      • 'domcontentloaded' - 當 DOMContentLoaded 事件被觸發時，視為操作完成。
      • 'load' - 當 load 事件被觸發時，視為操作完成。
      • 'networkidle' - 不建議使用 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，請改為依賴 web assertions 來評估就緒狀態。
      • 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

setDefaultNavigationTimeout​

在 v1.9 版本之前新增 page.setDefaultNavigationTimeout

此設定將變更以下方法和相關捷徑的預設最大導航時間

注意

page.setDefaultNavigationTimeout() 優先於 page.setDefaultTimeout()、browserContext.setDefaultTimeout() 和 browserContext.setDefaultNavigationTimeout()。

用法

page.setDefaultNavigationTimeout(timeout);

引數

  • timeout number#

    導航逾時時間上限，單位為毫秒

setDefaultTimeout​

在 v1.9 版本之前新增 page.setDefaultTimeout

此設定將變更所有接受 timeout 選項的方法的預設逾時時間上限。

注意

page.setDefaultNavigationTimeout() 的優先順序高於 page.setDefaultTimeout()。

用法

page.setDefaultTimeout(timeout);

引數

  • timeout number#

    時間上限，單位為毫秒。傳遞 0 以停用逾時。

setExtraHTTPHeaders​

在 v1.9 版本之前新增 page.setExtraHTTPHeaders

額外的 HTTP 標頭將會隨著頁面發起的每個請求一起傳送。

注意

page.setExtraHTTPHeaders() 不保證傳出請求中標頭的順序。

用法

await page.setExtraHTTPHeaders(headers);

引數

  • headers Object<string, string>#

    包含要與每個請求一起傳送的額外 HTTP 標頭的物件。所有標頭值都必須是字串。

傳回

setViewportSize​

在 v1.9 版本之前新增 page.setViewportSize

在單一瀏覽器中有多個頁面的情況下，每個頁面都可以有自己的 viewport 大小。然而，browser.newContext() 允許一次為 context 中的所有頁面設定 viewport 大小（以及更多設定）。

page.setViewportSize() 將調整頁面大小。許多網站不預期手機會變更大小，因此您應該在導航到頁面之前設定 viewport 大小。page.setViewportSize() 也會重設 screen 大小，如果您需要更好地控制這些屬性，請將 browser.newContext() 與 screen 和 viewport 參數一起使用。

用法

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

引數

  • viewportSize Object#

    • width number

      頁面寬度，單位為像素。

    • height number

      頁面高度，單位為像素。

傳回

title​

在 v1.9 版本之前新增 page.title

傳回頁面的標題。

用法

await page.title();

傳回

unroute​

在 v1.9 版本之前新增 page.unroute

移除使用 page.route() 建立的路由。當未指定 handler 時，會移除 url 的所有路由。

用法

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

引數

傳回

unrouteAll​

新增於：v1.41 page.unrouteAll

移除所有使用 page.route() 和 page.routeFromHAR() 建立的路由。

用法

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

引數

  • options Object (選用)

    • behavior "wait" | "ignoreErrors" | "default" (optional)#

      指定是否等待已在執行的處理常式，以及如果它們拋出錯誤時該怎麼做

      • 'default' - 不等待目前的處理常式呼叫（如果有的話）完成，如果未路由的處理常式拋出錯誤，可能會導致未處理的錯誤
      • 'wait' - 等待目前的處理常式呼叫（如果有的話）完成
      • 'ignoreErrors' - 不等待目前的處理常式呼叫（如果有的話）完成，所有在取消路由後由處理常式拋出的錯誤都會被靜默捕獲

傳回

url​

在 v1.9 版本之前新增 page.url

用法

page.url();

傳回

video​

在 v1.9 版本之前新增 page.video

與此頁面相關聯的 Video 物件。

用法

page.video();

傳回

viewportSize​

在 v1.9 版本之前新增 page.viewportSize

用法

page.viewportSize();

傳回

waitForEvent​

在 v1.9 版本之前新增 page.waitForEvent

等待事件觸發，並將其值傳遞到 predicate 函式中。當 predicate 傳回 truthy 值時傳回。如果在事件觸發之前頁面關閉，將拋出錯誤。傳回事件資料值。

用法

// 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 (optional)#

    接收事件的 predicate 或選項物件。可選。

  • options Object (選用)

    • predicate function (optional)#

      接收事件資料，並在等待應解析時解析為 truthy 值。

傳回

waitForFunction​

在 v1.9 版本之前新增 page.waitForFunction

當 pageFunction 傳回 truthy 值時傳回。它會解析為 truthy 值的 JSHandle。

用法

page.waitForFunction() 可用於觀察 viewport 大小變更

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() 函式的 predicate

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

引數

傳回

waitForLoadState​

在 v1.9 版本之前新增 page.waitForLoadState

當達到所需的載入狀態時傳回。

當頁面達到所需的載入狀態時，預設為 load 時，此方法會解析。導航必須在此方法被呼叫時已提交。如果目前的文檔已達到所需的狀態，則會立即解析。

注意

大多數情況下，不需要此方法，因為 Playwright 在 每次操作前都會自動等待。

用法

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" (optional)#

    要等待的可選載入狀態，預設為 load。如果在載入目前文檔時已達到該狀態，則此方法會立即解析。可以是以下其中之一

    • 'load' - 等待 load 事件觸發。
    • 'domcontentloaded' - 等待 DOMContentLoaded 事件觸發。
    • 'networkidle' - **不建議** 等待直到至少 500 毫秒沒有網路連線。請勿將此方法用於測試，而是依靠網頁斷言來評估就緒狀態。

  • options Object (選用)

傳回

waitForRequest​

在 v1.9 版本之前新增 page.waitForRequest

等待符合的請求並傳回它。有關事件的更多詳細資訊，請參閱 等待事件。

用法

// 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;

引數

傳回

waitForResponse​

在 v1.9 版本之前新增 page.waitForResponse

傳回符合的回應。有關事件的更多詳細資訊，請參閱 等待事件。

用法

// 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;

引數

傳回

waitForURL​

Added in: v1.11 page.waitForURL

等待主框架導航到給定的 URL。

用法

await page.click('a.delayed-navigation'); // Clicking the link will indirectly cause a navigation
await page.waitForURL('**/target.html');

引數

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

    在等待導航時要比對的 glob 模式、regex 模式或接收 URL 的 predicate。請注意，如果參數是不帶萬用字元的字串，則此方法將等待導航到與該字串完全相等的 URL。

  • options Object (選用)

    • timeout number (optional)#

      最大操作時間，以毫秒為單位。預設為 0 - 無 timeout。預設值可以透過 config 中的 navigationTimeout 選項更改，或使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法。

    • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (optional)#

      何時視為操作成功，預設為 load。事件可以是：

      • 'domcontentloaded' - 當 DOMContentLoaded 事件被觸發時，視為操作完成。
      • 'load' - 當 load 事件被觸發時，視為操作完成。
      • 'networkidle' - 不建議使用 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，請改為依賴 web assertions 來評估就緒狀態。
      • 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

workers​

在 v1.9 版本之前新增 page.workers

此方法傳回與頁面相關聯的所有專用 WebWorkers。

注意

這不包含 ServiceWorker

用法

page.workers();

傳回

Properties​

clock​

Added in: v1.45 page.clock

Playwright 具有模擬時鐘和時間流逝的能力。

用法

page.clock

Type

coverage​

在 v1.9 版本之前新增 page.coverage
注意

目前僅適用於 Chromium。

瀏覽器特定的 Coverage 實作。有關更多詳細資訊，請參閱 Coverage。

用法

page.coverage

Type

keyboard​

在 v1.9 版本之前新增 page.keyboard

用法

page.keyboard

Type

mouse​

在 v1.9 版本之前新增 page.mouse

用法

page.mouse

Type

request​

Added in: v1.16 page.request

與此頁面相關聯的 API 測試輔助工具。此方法傳回與頁面 context 上的 browserContext.request 相同的實例。有關更多詳細資訊，請參閱 browserContext.request。

用法

page.request

Type

touchscreen​

在 v1.9 版本之前新增 page.touchscreen

用法

page.touchscreen

Type

Events​

on('close')​

在 v1.9 版本之前新增 page.on('close')

當頁面關閉時發出。

用法

page.on('close', data => {});

事件資料

on('console')​

在 v1.9 版本之前新增 page.on('console')

當頁面內的 JavaScript 呼叫其中一個 console API 方法時發出，例如 console.log 或 console.dir。

傳遞到 console.log 中的引數可在 ConsoleMessage 事件處理常式引數中使用。

用法

page.on('console', async msg => {
  const values = [];
  for (const arg of msg.args())
    values.push(await arg.jsonValue());
  console.log(...values);
});
await page.evaluate(() => console.log('hello', 5, { foo: 'bar' }));

事件資料

on('crash')​

在 v1.9 版本之前新增 page.on('crash')

當頁面崩潰時發出。如果瀏覽器頁面嘗試分配過多記憶體，則可能會崩潰。當頁面崩潰時，正在進行和後續的操作將會拋出錯誤。

處理崩潰最常見的方法是捕獲例外

try {
  // Crash might happen during a click.
  await page.click('button');
  // Or while waiting for an event.
  await page.waitForEvent('popup');
} catch (e) {
  // When the page crashes, exception message contains 'crash'.
}

用法

page.on('crash', data => {});

事件資料

on('dialog')​

在 v1.9 版本之前新增 page.on('dialog')

當出現 JavaScript 對話框時發出，例如 alert、prompt、confirm 或 beforeunload。監聽器**必須** dialog.accept() 或 dialog.dismiss() 對話框 - 否則頁面將會 凍結 等待對話框，而點擊等操作將永遠無法完成。

用法

page.on('dialog', dialog => dialog.accept());
注意

當沒有 page.on('dialog') 或 browserContext.on('dialog') 監聽器存在時，所有對話框都會自動關閉。

事件資料

on('domcontentloaded')​

新增於：v1.9 page.on('domcontentloaded')

當 JavaScript DOMContentLoaded 事件被分派時發出。

用法

page.on('domcontentloaded', data => {});

事件資料

on('download')​

在 v1.9 版本之前新增 page.on('download')

當附件下載開始時發出。使用者可以透過傳遞的 Download 實例存取已下載內容的基本檔案操作。

用法

page.on('download', data => {});

事件資料

on('filechooser')​

新增於：v1.9 page.on('filechooser')

當應該出現檔案選擇器時發出，例如在點擊 <input type=file> 之後。Playwright 可以透過使用 fileChooser.setFiles() 設定輸入檔案來回應，之後可以上傳這些檔案。

page.on('filechooser', async fileChooser => {
  await fileChooser.setFiles(path.join(__dirname, '/tmp/myfile.pdf'));
});

用法

page.on('filechooser', data => {});

事件資料

on('frameattached')​

新增於：v1.9 page.on('frameattached')

當 frame 被附加時發出。

用法

page.on('frameattached', data => {});

事件資料

on('framedetached')​

新增於：v1.9 page.on('framedetached')

當 frame 被分離時發出。

用法

page.on('framedetached', data => {});

事件資料

on('framenavigated')​

新增於：v1.9 page.on('framenavigated')

當 frame 導航到新的 url 時發出。

用法

page.on('framenavigated', data => {});

事件資料

on('load')​

在 v1.9 版本之前新增 page.on('load')

當 JavaScript load 事件被分派時發出。

用法

page.on('load', data => {});

事件資料

on('pageerror')​

新增於：v1.9 page.on('pageerror')

當頁面內發生未捕獲的例外時發出。

// Log all uncaught errors to the terminal
page.on('pageerror', exception => {
  console.log(`Uncaught exception: "${exception}"`);
});

// Navigate to a page with an exception.
await page.goto('data:text/html,<script>throw new Error("Test")</script>');

用法

page.on('pageerror', data => {});

事件資料

on('popup')​

在 v1.9 版本之前新增 page.on('popup')

當頁面開啟新的分頁或視窗時發出。此事件除了 browserContext.on('page') 之外也會發出，但僅適用於與此頁面相關的彈出視窗。

頁面可用的最早時刻是它導航到初始 url 時。例如，當使用 window.open('http://example.com') 開啟彈出視窗時，當對 "http://example.com" 的網路請求完成且其回應已開始在彈出視窗中載入時，將會觸發此事件。如果您想路由/監聽此網路請求，請分別使用 browserContext.route() 和 browserContext.on('request')，而不是 Page 上的類似方法。

// Start waiting for popup before clicking. Note no await.
const popupPromise = page.waitForEvent('popup');
await page.getByText('open the popup').click();
const popup = await popupPromise;
console.log(await popup.evaluate('location.href'));
注意

使用 page.waitForLoadState() 等待頁面達到特定狀態（在大多數情況下您不需要它）。

用法

page.on('popup', data => {});

事件資料

on('request')​

在 v1.9 版本之前新增 page.on('request')

當頁面發出請求時發出。request 物件是唯讀的。為了攔截和變更請求，請參閱 page.route() 或 browserContext.route()。

用法

page.on('request', data => {});

事件資料

on('requestfailed')​

新增於：v1.9 page.on('requestfailed')

當請求失敗時發出，例如逾時。

page.on('requestfailed', request => {
  console.log(request.url() + ' ' + request.failure().errorText);
});
注意

HTTP 錯誤回應，例如 404 或 503，從 HTTP 的角度來看仍然是成功的回應，因此請求將以 page.on('requestfinished') 事件完成，而不是 page.on('requestfailed')。只有當客戶端無法從伺服器取得 HTTP 回應時，請求才被視為失敗，例如由於網路錯誤 net::ERR_FAILED。

用法

page.on('requestfailed', data => {});

事件資料

on('requestfinished')​

新增於：v1.9 page.on('requestfinished')

當請求在下載回應主體後成功完成時發出。對於成功的回應，事件順序為 request、response 和 requestfinished。

用法

page.on('requestfinished', data => {});

事件資料

on('response')​

在 v1.9 版本之前新增 page.on('response')

當收到請求的 response 狀態和標頭時發出。對於成功的回應，事件順序為 request、response 和 requestfinished。

用法

page.on('response', data => {});

事件資料

on('websocket')​

新增於：v1.9 page.on('websocket')

當傳送 WebSocket 請求時發出。

用法

page.on('websocket', data => {});

事件資料

on('worker')​

在 v1.9 版本之前新增 page.on('worker')

當頁面產生專用的 WebWorker 時發出。

用法

page.on('worker', data => {});

事件資料

Deprecated​

$​

新增於：v1.9 page.$
不建議使用

請改用基於 locator 的 page.locator()。請閱讀更多關於 locators 的資訊。

此方法會在頁面中尋找符合指定選擇器的元素。如果沒有元素符合選擇器，回傳值會解析為 null。若要等待頁面上的元素，請使用 locator.waitFor()。

用法

await page.$(selector);
await page.$(selector, options);

引數

  • selector string#

    要查詢的選擇器。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

傳回

$$​

新增於：v1.9 page.$$
不建議使用

請改用基於 locator 的 page.locator()。請閱讀更多關於 locators 的資訊。

此方法會在頁面中尋找所有符合指定選擇器的元素。如果沒有元素符合選擇器，回傳值會解析為 []。

用法

await page.$$(selector);

引數

  • selector string#

    要查詢的選擇器。

傳回

$eval​

新增於：v1.9 page.$eval
不建議使用

此方法不會等待元素通過可操作性檢查，因此可能導致測試不穩定。請改用 locator.evaluate()、其他 Locator 輔助方法或網頁優先的斷言。

此方法會在頁面中尋找符合指定選擇器的元素，並將其作為第一個參數傳遞給 pageFunction。如果沒有元素符合選擇器，此方法會拋出錯誤。回傳 pageFunction 的值。

如果 pageFunction 回傳 Promise，則 page.$eval() 會等待 Promise 解析並回傳其值。

用法

const searchValue = await page.$eval('#search', el => el.value);
const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');
// In TypeScript, this example requires an explicit type annotation (HTMLLinkElement) on el:
const preloadHrefTS = await page.$eval('link[rel=preload]', (el: HTMLLinkElement) => el.href);

引數

  • selector string#

    要查詢的選擇器。

  • pageFunction function(Element) | string#

    要在頁面上下文中評估的函數。

  • arg EvaluationArgument (選填)#

    傳遞給 pageFunction 的選填參數。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

傳回

$$eval​

新增於：v1.9 page.$$eval
不建議使用

在大多數情況下，locator.evaluateAll()、其他 Locator 輔助方法和網頁優先的斷言會做得更好。

此方法會在頁面中尋找所有符合指定選擇器的元素，並將相符元素的陣列作為第一個參數傳遞給 pageFunction。回傳 pageFunction 呼叫的結果。

如果 pageFunction 回傳 Promise，則 page.$$eval() 會等待 Promise 解析並回傳其值。

用法

const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);

引數

傳回

accessibility​

在 v1.9 版本之前新增 page.accessibility
已棄用

不建議使用此屬性。如果您需要測試頁面可訪問性，請使用其他程式庫，例如 Axe。請參閱我們的 Node.js 指南，以了解與 Axe 的整合。

用法

page.accessibility

Type

check​

在 v1.9 版本之前新增 page.check
不建議使用

請改用基於 locator 的 locator.check()。請閱讀更多關於 locators 的資訊。

此方法會透過執行以下步驟，勾選符合 selector 的元素

  1. 尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
  2. 確保符合的元素是核取方塊或 radio 輸入框。如果不是，此方法會拋出錯誤。如果元素已經被勾選，此方法會立即回傳。
  3. 等待符合元素上的可操作性檢查，除非設定了 force 選項。如果在檢查期間元素被分離，則會重試整個操作。
  4. 如果需要，將元素滾動到視野中。
  5. 使用 page.mouse 在元素的中心點擊。
  6. 確保元素現在已被勾選。如果沒有，此方法會拋出錯誤。

當所有步驟在指定的 timeout 期間內未完成時，此方法會拋出 TimeoutError。傳遞零 timeout 會停用此功能。

用法

await page.check(selector);
await page.check(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • force boolean (選填)#

      是否略過可操作性檢查。預設為 false。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

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

      相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

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

      設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好執行動作時很有用。

傳回

click​

在 v1.9 版本之前新增 page.click
不建議使用

請改用基於 locator 的 locator.click()。請閱讀更多關於 locators 的資訊。

此方法會透過執行以下步驟，點擊符合 selector 的元素

  1. 尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
  2. 等待符合元素上的可操作性檢查，除非設定了 force 選項。如果在檢查期間元素被分離，則會重試整個操作。
  3. 如果需要，將元素滾動到視野中。
  4. 使用 page.mouse 在元素的中心點擊，或指定的 position。
  5. 等待啟動的導航成功或失敗，除非設定了 noWaitAfter 選項。

當所有步驟在指定的 timeout 期間內未完成時，此方法會拋出 TimeoutError。傳遞零 timeout 會停用此功能。

用法

await page.click(selector);
await page.click(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • button "left" | "right" | "middle" (選填)#

      預設為 left。

    • clickCount number (選填)#

      預設為 1。請參閱 UIEvent.detail。

    • delay number (選填)#

      mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設為 0。

    • force boolean (選填)#

      是否略過可操作性檢查。預設為 false。

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

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項在未來將預設為 true。

      啟動導航的操作正在等待這些導航發生以及頁面開始載入。您可以選擇不等待，透過設定此旗標。您只需要在特殊情況下使用此選項，例如導航到無法訪問的頁面。預設為 false。

    • position Object (選填)#

      相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

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

      設定後，此方法僅執行可操作性檢查，並跳過操作。預設為 false。可用於等待元素準備好進行操作，而無需執行操作。請注意，鍵盤 modifiers 將始終被按下，無論 trial 設定為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

dblclick​

在 v1.9 版本之前新增 page.dblclick
不建議使用

請改用基於 locator 的 locator.dblclick()。請閱讀更多關於 locators 的資訊。

此方法會透過執行以下步驟，雙擊符合 selector 的元素

  1. 尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
  2. 等待符合元素上的可操作性檢查，除非設定了 force 選項。如果在檢查期間元素被分離，則會重試整個操作。
  3. 如果需要，將元素滾動到視野中。
  4. 使用 page.mouse 在元素的中心雙擊，或指定的 position。

當所有步驟在指定的 timeout 期間內未完成時，此方法會拋出 TimeoutError。傳遞零 timeout 會停用此功能。

注意

page.dblclick() 會發送兩個 click 事件和一個 dblclick 事件。

用法

await page.dblclick(selector);
await page.dblclick(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • button "left" | "right" | "middle" (選填)#

      預設為 left。

    • delay number (選填)#

      mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設為 0。

    • force boolean (選填)#

      是否略過可操作性檢查。預設為 false。

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

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

      相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

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

      設定後，此方法僅執行可操作性檢查，並跳過操作。預設為 false。可用於等待元素準備好進行操作，而無需執行操作。請注意，鍵盤 modifiers 將始終被按下，無論 trial 設定為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

dispatchEvent​

在 v1.9 版本之前新增 page.dispatchEvent
不建議使用

請改用基於 locator 的 locator.dispatchEvent()。請閱讀更多關於 locators 的資訊。

以下程式碼片段在元素上發送 click 事件。無論元素的可见性狀態如何，都會發送 click。這相當於呼叫 element.click()。

用法

await page.dispatchEvent('button#submit', 'click');

在底層，它會根據給定的 type 建立事件實例，使用 eventInit 屬性初始化它，並在元素上發送它。事件預設為 composed、cancelable 和 bubble。

由於 eventInit 是事件特定的，請參閱事件文件以獲取初始屬性列表

如果您想要將即時物件傳遞到事件中，您還可以將 JSHandle 指定為屬性值

// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await page.dispatchEvent('#source', 'dragstart', { dataTransfer });

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • type string#

    DOM 事件類型："click"、"dragstart" 等。

  • eventInit EvaluationArgument (選填)#

    選填的事件特定初始化屬性。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

fill​

在 v1.9 版本之前新增 page.fill
不建議使用

請改用基於 locator 的 locator.fill()。請閱讀更多關於 locators 的資訊。

此方法會等待符合 selector 的元素，等待可操作性檢查，聚焦元素，填寫它，並在填寫後觸發 input 事件。請注意，您可以傳遞空字串來清除輸入欄位。

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會拋出錯誤。但是，如果元素在具有關聯 control 的 <label> 元素內，則將會填寫該 control。

若要發送細緻的鍵盤事件，請使用 locator.pressSequentially()。

用法

await page.fill(selector, value);
await page.fill(selector, value, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • value string#

    要為 <input>、<textarea> 或 [contenteditable] 元素填寫的值。

  • options Object (選用)

    • force boolean (選填)新增於：v1.13#

      是否略過可操作性檢查。預設為 false。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

focus​

在 v1.9 版本之前新增 page.focus
不建議使用

請改用基於 locator 的 locator.focus()。請閱讀更多關於 locators 的資訊。

此方法會獲取具有 selector 的元素並使其聚焦。如果沒有符合 selector 的元素，則此方法會等待直到符合的元素出現在 DOM 中。

用法

await page.focus(selector);
await page.focus(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

getAttribute​

在 v1.9 版本之前新增 page.getAttribute
不建議使用

請改用基於 locator 的 locator.getAttribute()。請閱讀更多關於 locators 的資訊。

回傳元素屬性值。

用法

await page.getAttribute(selector, name);
await page.getAttribute(selector, name, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • name string#

    要取得其值的屬性名稱。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

hover​

在 v1.9 版本之前新增 page.hover
不建議使用

請改用基於 locator 的 locator.hover()。請閱讀更多關於 locators 的資訊。

此方法會透過執行以下步驟，懸停在符合 selector 的元素上方

  1. 尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
  2. 等待符合元素上的可操作性檢查，除非設定了 force 選項。如果在檢查期間元素被分離，則會重試整個操作。
  3. 如果需要，將元素滾動到視野中。
  4. 使用 page.mouse 懸停在元素的中心上方，或指定的 position。

當所有步驟在指定的 timeout 期間內未完成時，此方法會拋出 TimeoutError。傳遞零 timeout 會停用此功能。

用法

await page.hover(selector);
await page.hover(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • force boolean (選填)#

      是否略過可操作性檢查。預設為 false。

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

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

    • noWaitAfter boolean (選用)新增於：v1.28#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

      相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

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

      設定後，此方法僅執行可操作性檢查，並跳過操作。預設為 false。可用於等待元素準備好進行操作，而無需執行操作。請注意，鍵盤 modifiers 將始終被按下，無論 trial 設定為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

innerHTML​

在 v1.9 版本之前新增 page.innerHTML
不建議使用

請改用基於 locator 的 locator.innerHTML()。請閱讀更多關於 locators 的資訊。

回傳 element.innerHTML。

用法

await page.innerHTML(selector);
await page.innerHTML(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

innerText​

在 v1.9 版本之前新增 page.innerText
不建議使用

請改用基於 locator 的 locator.innerText()。請閱讀更多關於 locators 的資訊。

回傳 element.innerText。

用法

await page.innerText(selector);
await page.innerText(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

inputValue​

新增於：v1.13 page.inputValue
不建議使用

請改用基於定位器的 locator.inputValue()。閱讀更多關於定位器的資訊。

針對選取的 <input>、<textarea> 或 <select> 元素，傳回 input.value。

若元素並非輸入元素則會拋出錯誤。但是，如果元素位於具有關聯控制項的 <label> 元素內，則會傳回控制項的值。

用法

await page.inputValue(selector);
await page.inputValue(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

isChecked​

在 v1.9 版本之前新增 page.isChecked
不建議使用

請改用基於定位器的 locator.isChecked()。閱讀更多關於定位器的資訊。

傳回元素是否被勾選。如果元素不是核取方塊或單選按鈕輸入，則會拋出錯誤。

用法

await page.isChecked(selector);
await page.isChecked(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

isDisabled​

在 v1.9 版本之前新增 page.isDisabled
不建議使用

請改用基於定位器的 locator.isDisabled()。閱讀更多關於定位器的資訊。

傳回元素是否為停用狀態，與啟用狀態相反。

用法

await page.isDisabled(selector);
await page.isDisabled(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

isEditable​

在 v1.9 版本之前新增 page.isEditable
不建議使用

請改用基於定位器的 locator.isEditable()。閱讀更多關於定位器的資訊。

傳回元素是否為可編輯狀態。

用法

await page.isEditable(selector);
await page.isEditable(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

isEnabled​

在 v1.9 版本之前新增 page.isEnabled
不建議使用

請改用基於定位器的 locator.isEnabled()。閱讀更多關於定位器的資訊。

傳回元素是否為啟用狀態。

用法

await page.isEnabled(selector);
await page.isEnabled(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

isHidden​

在 v1.9 版本之前新增 page.isHidden
不建議使用

請改用基於定位器的 locator.isHidden()。閱讀更多關於定位器的資訊。

傳回元素是否為隱藏狀態，與可見狀態相反。不符合任何元素的 selector 會被視為隱藏。

用法

await page.isHidden(selector);
await page.isHidden(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      已棄用

      此選項會被忽略。page.isHidden() 不會等待元素變成隱藏，並立即傳回。

傳回

isVisible​

在 v1.9 版本之前新增 page.isVisible
不建議使用

請改用基於定位器的 locator.isVisible()。閱讀更多關於定位器的資訊。

傳回元素是否為可見狀態。不符合任何元素的 selector 會被視為不可見。

用法

await page.isVisible(selector);
await page.isVisible(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      已棄用

      此選項會被忽略。page.isVisible() 不會等待元素變成可見，並立即傳回。

傳回

press​

在 v1.9 版本之前新增 page.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。ControlOrMeta 在 Windows 和 Linux 上解析為 Control，在 macOS 上解析為 Meta。

按住 Shift 鍵將會輸入與大寫 key 對應的文字。

如果 key 是單一字元，則區分大小寫，因此值 a 和 A 將會產生各自不同的文字。

也支援諸如 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 之類的捷徑。當使用修飾鍵指定時，在按下後續按鍵時，修飾鍵會保持按下狀態。

用法

const page = await browser.newPage();
await page.goto('https://keycode.info');
await page.press('body', 'A');
await page.screenshot({ path: 'A.png' });
await page.press('body', 'ArrowLeft');
await page.screenshot({ path: 'ArrowLeft.png' });
await page.press('body', 'Shift+O');
await page.screenshot({ path: 'O.png' });
await browser.close();

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • key string#

    要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。

  • options Object (選用)

    • delay number (選填)#

      keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項在未來將預設為 true。

      啟動導航的操作正在等待這些導航發生以及頁面開始載入。您可以選擇不等待，透過設定此旗標。您只需要在特殊情況下使用此選項，例如導航到無法訪問的頁面。預設為 false。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

selectOption​

在 v1.9 版本之前新增 page.selectOption
不建議使用

請改用基於定位器的 locator.selectOption()。閱讀更多關於定位器的資訊。

此方法會等待符合 selector 的元素，等待可操作性檢查，等待直到所有指定的選項都出現在 <select> 元素中，然後選取這些選項。

如果目標元素不是 <select> 元素，此方法會拋出錯誤。但是，如果元素位於具有關聯控制項的 <label> 元素內，則會改為使用控制項。

傳回已成功選取的選項值陣列。

一旦選取所有提供的選項，就會觸發 change 和 input 事件。

用法

// Single selection matching the value or label
page.selectOption('select#colors', 'blue');

// single selection matching the label
page.selectOption('select#colors', { label: 'Blue' });

// multiple selection
page.selectOption('select#colors', ['red', 'green', 'blue']);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • 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#

      是否略過可操作性檢查。預設為 false。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

setChecked​

新增於：v1.15 page.setChecked
不建議使用

請改用基於定位器的 locator.setChecked()。閱讀更多關於定位器的資訊。

此方法會透過執行下列步驟，勾選或取消勾選符合 selector 的元素：

  1. 尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
  2. 確保符合的元素是核取方塊或單選按鈕輸入。如果不是，此方法會拋出錯誤。
  3. 如果元素已經處於正確的勾選狀態，此方法會立即傳回。
  4. 等待符合元素的可操作性檢查，除非設定 force 選項。如果元素在檢查期間分離，則會重試整個動作。
  5. 如果需要，將元素滾動到視野中。
  6. 使用 page.mouse 在元素的中心點擊。
  7. 確保元素現在已勾選或取消勾選。如果沒有，此方法會拋出錯誤。

當所有步驟組合在指定的 timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

await page.setChecked(selector, checked);
await page.setChecked(selector, checked, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • checked boolean#

    是否勾選或取消勾選核取方塊。

  • options Object (選用)

    • force boolean (選填)#

      是否略過可操作性檢查。預設為 false。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

      相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選填)#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

    • trial boolean (選填)#

      設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好執行動作時很有用。

傳回

setInputFiles​

在 v1.9 版本之前新增 page.setInputFiles
不建議使用

請改用基於定位器的 locator.setInputFiles()。閱讀更多關於定位器的資訊。

將檔案輸入的值設定為這些檔案路徑或檔案。如果某些 filePaths 是相對路徑，則會相對於目前的工作目錄解析它們。對於空陣列，會清除選取的檔案。對於具有 [webkitdirectory] 屬性的輸入，僅支援單一目錄路徑。

此方法預期 selector 指向 input 元素。但是，如果元素位於具有關聯控制項的 <label> 元素內，則會改為以控制項為目標。

用法

await page.setInputFiles(selector, files);
await page.setInputFiles(selector, files, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

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

  • options Object (選用)

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

tap​

在 v1.9 版本之前新增 page.tap
不建議使用

請改用基於定位器的 locator.tap()。閱讀更多關於定位器的資訊。

此方法會透過執行下列步驟，輕觸符合 selector 的元素：

  1. 尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
  2. 等待符合元素的可操作性檢查，除非設定 force 選項。如果元素在檢查期間分離，則會重試整個動作。
  3. 如果需要，將元素滾動到視野中。
  4. 使用 page.touchscreen 輕觸元素的中心，或指定的 position。

當所有步驟組合在指定的 timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

注意

page.tap() 方法會在瀏覽器內容的 hasTouch 選項為 false 時拋出錯誤。

用法

await page.tap(selector);
await page.tap(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • force boolean (選填)#

      是否略過可操作性檢查。預設為 false。

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

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

      相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

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

      設定後，此方法僅執行可操作性檢查，並跳過操作。預設為 false。可用於等待元素準備好進行操作，而無需執行操作。請注意，鍵盤 modifiers 將始終被按下，無論 trial 設定為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

textContent​

在 v1.9 版本之前新增 page.textContent
不建議使用

請改用基於定位器的 locator.textContent()。閱讀更多關於定位器的資訊。

傳回 element.textContent。

用法

await page.textContent(selector);
await page.textContent(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

type​

在 v1.9 版本之前新增 page.type
已棄用

在大多數情況下，您應該改用 locator.fill()。只有在頁面上有特殊的鍵盤處理時，才需要逐個按鍵 - 在這種情況下，請使用 locator.pressSequentially()。

為文字中的每個字元傳送 keydown、keypress/input 和 keyup 事件。page.type 可用於傳送細緻的鍵盤事件。若要填寫表單欄位中的值，請使用 page.fill()。

若要按下特殊按鍵，例如 Control 或 ArrowDown，請使用 keyboard.press()。

用法

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • text string#

    要輸入到聚焦元素中的文字。

  • options Object (選用)

    • delay number (選填)#

      按鍵之間等待的時間，以毫秒為單位。預設為 0。

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout number (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

uncheck​

在 v1.9 版本之前新增 page.uncheck
不建議使用

請改用基於定位器的 locator.uncheck()。閱讀更多關於定位器的資訊。

此方法會透過執行下列步驟，取消勾選符合 selector 的元素：

  1. 尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
  2. 確保符合的元素是核取方塊或單選按鈕輸入。如果不是，此方法會拋出錯誤。如果元素已經取消勾選，此方法會立即傳回。
  3. 等待符合元素的可操作性檢查，除非設定 force 選項。如果元素在檢查期間分離，則會重試整個動作。
  4. 如果需要，將元素滾動到視野中。
  5. 使用 page.mouse 在元素的中心點擊。
  6. 確保元素現在已取消勾選。如果沒有，此方法會拋出錯誤。

當所有步驟組合在指定的 timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

await page.uncheck(selector);
await page.uncheck(selector, options);

引數

  • selector string#

    用於搜尋元素的選擇器。如果有多個元素滿足選擇器，將使用第一個。

  • options Object (選用)

    • force 布林值 (選填)#

      是否略過可操作性檢查。預設為 false。

    • noWaitAfter 布林值 (選填)#

      已棄用

      此選項無效。

      此選項無效。

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

      相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。

    • strict boolean (選用)新增於：v1.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout 數字 (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

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

      設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好執行動作時很有用。

傳回

waitForNavigation​

在 v1.9 版本之前新增 page.waitForNavigation
已棄用

此方法本質上具有競爭性，請改用 page.waitForURL()。

等待主框架導航並返回主要資源回應。如果發生多次重定向，導航將解析為最後一次重定向的回應。如果導航到不同的錨點或由於 History API 的使用而導航，導航將解析為 null。

用法

當頁面導航到新的 URL 或重新載入時，此方法會解析。當您運行會間接導致頁面導航的程式碼時，此方法非常有用。例如，點擊目標具有一個 onclick 處理程序，該處理程序會從 setTimeout 觸發導航。請考慮以下範例

// Start waiting for navigation before clicking. Note no await.
const navigationPromise = page.waitForNavigation();
await page.getByText('Navigate after timeout').click();
await navigationPromise;
注意

使用 History API 更改 URL 被視為導航。

引數

  • options Object (選用)

    • timeout 數字 (選填)#

      最大操作時間，以毫秒為單位。預設為 0 - 無 timeout。預設值可以透過 config 中的 navigationTimeout 選項更改，或使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法。

    • url 字串 | RegExp | function(URL):布林值 (選填)#

      在等待導航時要比對的 glob 模式、regex 模式或接收 URL 的 predicate。請注意，如果參數是不帶萬用字元的字串，則此方法將等待導航到與該字串完全相等的 URL。

    • waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (選填)#

      何時視為操作成功，預設為 load。事件可以是：

      • 'domcontentloaded' - 當 DOMContentLoaded 事件被觸發時，視為操作完成。
      • 'load' - 當 load 事件被觸發時，視為操作完成。
      • 'networkidle' - 不建議使用 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，請改為依賴 web assertions 來評估就緒狀態。
      • 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

waitForSelector​

在 v1.9 版本之前新增 page.waitForSelector
不建議使用

請改用斷言可見性或基於定位器的 locator.waitFor() 等 Web 斷言。閱讀更多關於定位器的資訊。

當選擇器指定的元素滿足 state 選項時返回。如果等待 hidden 或 detached，則返回 null。

注意

Playwright 會自動等待元素準備就緒，然後再執行操作。使用 Locator 物件和 Web 優先斷言使程式碼無需等待選擇器。

等待 selector 滿足 state 選項（出現在/消失在 DOM 中，或變得可見/隱藏）。如果在呼叫方法時，selector 已經滿足條件，則該方法將立即返回。如果選擇器在 timeout 毫秒內未滿足條件，則該函數將拋出錯誤。

用法

此方法跨導航工作

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

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  for (const currentURL of ['https://google.com', 'https://bbc.com']) {
    await page.goto(currentURL);
    const element = await page.waitForSelector('img');
    console.log('Loaded image: ' + await element.getAttribute('src'));
  }
  await browser.close();
})();

引數

  • selector 字串#

    要查詢的選擇器。

  • 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.14#

      如果為 true，則呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

    • timeout 數字 (選填)#

      以毫秒為單位的最大時間。預設為 0 - 無逾時。預設值可以透過設定中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

waitForTimeout​

在 v1.9 版本之前新增 page.waitForTimeout
不建議使用

永遠不要在生產環境中等待超時。等待時間的測試本質上是不穩定的。請改用自動等待的 Locator 動作和 Web 斷言。

等待給定的 timeout 毫秒數。

請注意，page.waitForTimeout() 僅應用於偵錯。在生產環境中使用計時器的測試將會變得不穩定。請改用網路事件、選擇器變得可見等訊號。

用法

// wait for 1 second
await page.waitForTimeout(1000);

引數

  • timeout 數字#

    等待的超時時間

傳回