跳到主要內容

Page

Page 提供了與 Browser 中的單一分頁互動的方法，或是在 Chromium 中的 擴充功能背景頁面 互動的方法。一個 Browser 實例可能有多個 Page 實例。

這個範例建立一個頁面，導航到一個 URL，然後儲存螢幕截圖

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = webkit.launch()
    context = browser.new_context()
    page = context.new_page()
    page.goto("https://example.com")
    page.screenshot(path="screenshot.png")
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

Page 類別會發出各種事件（如下所述），這些事件可以使用 Node.js 原生的 EventEmitter 方法（例如 on、once 或 removeListener）來處理。

這個範例記錄單一頁面 load 事件的訊息

page.once("load", lambda: print("page loaded!"))

若要取消訂閱事件，請使用 removeListener 方法

def log_request(intercepted_request):
    print("a request was made:", intercepted_request.url)
page.on("request", log_request)
# sometime later...
page.remove_listener("request", log_request)

方法​

add_init_script​

在 v1.9 之前新增 page.add_init_script

新增一個腳本，該腳本將在以下情況之一中評估

  • 每當頁面被導航時。
  • 每當子框架被附加或導航時。在這種情況下，腳本會在新附加的框架的上下文中評估。

腳本在文件建立之後但在其任何腳本執行之前評估。這對於修改 JavaScript 環境很有用，例如用於 seed Math.random。

用法

在頁面載入之前覆寫 Math.random 的範例

// preload.js
Math.random = () => 42;
# in your playwright script, assuming the preload.js file is in same directory
page.add_init_script(path="./preload.js")
注意

通過 browser_context.add_init_script() 和 page.add_init_script() 安裝的多個腳本的評估順序未定義。

參數

  • path Union[str, pathlib.Path] (選填)#

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

  • script str (選填)#

    要在瀏覽器上下文中的所有頁面中評估的腳本。選填。

返回

add_locator_handler​

在 v1.42 中新增 page.add_locator_handler

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

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

注意事項

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

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

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

另一個範例是一系列滑鼠操作，其中 mouse.move() 之後是 mouse.down()。同樣，當處理程序在這兩個操作之間執行時，在滑鼠按下期間滑鼠位置將會錯誤。請優先使用獨立的操作，例如 locator.click()，這些操作不依賴於處理程序未更改的狀態。

用法

一個在「註冊電子報」對話框出現時關閉它的範例

# Setup the handler.
def handler():
  page.get_by_role("button", name="No thanks").click()
page.add_locator_handler(page.get_by_text("Sign up to the newsletter"), handler)

# Write the test as usual.
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()

一個在「確認您的安全詳細資訊」頁面顯示時跳過它的範例

# Setup the handler.
def handler():
  page.get_by_role("button", name="Remind me later").click()
page.add_locator_handler(page.get_by_text("Confirm your security details"), handler)

# Write the test as usual.
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()

一個在每次 actionability 檢查時使用自訂回調的範例。它使用一個始終可見的 <body> 定位器，因此處理程序在每次 actionability 檢查之前都會被呼叫。指定 no_wait_after 很重要，因為處理程序不會隱藏 <body> 元素。

# Setup the handler.
def handler():
  page.evaluate("window.removeObstructionsForTestIfNeeded()")
page.add_locator_handler(page.locator("body"), handler, no_wait_after=True)

# Write the test as usual.
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()

處理程序將原始定位器作為參數。您也可以通過設定 times 在多次調用後自動移除處理程序

def handler(locator):
  locator.click()
page.add_locator_handler(page.get_by_label("Close"), handler, times=1)

參數

  • locator Locator#

    觸發處理程序的定位器。

  • handler Callable[Locator]:Promise[Any]#

    一旦 locator 出現就應該運行的函數。此函數應該擺脫阻止點擊等操作的元素。

  • no_wait_after bool (選填)在 v1.44 中新增#

    預設情況下，在呼叫處理程序後，Playwright 將等待直到覆蓋層變得隱藏，然後 Playwright 才會繼續執行觸發處理程序的操作/斷言。此選項允許選擇退出此行為，以便在處理程序運行後覆蓋層可以保持可見。

  • times int (選填)在 v1.44 中新增#

    指定應呼叫此處理程序的最大次數。預設為無限制。

返回

add_script_tag​

在 v1.9 之前新增 page.add_script_tag

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

用法

page.add_script_tag()
page.add_script_tag(**kwargs)

參數

  • content str (選填)#

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

  • path Union[str, pathlib.Path] (選填)#

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

  • type str (選填)#

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

  • url str (選填)#

    要新增的腳本的 URL。

返回

add_style_tag​

在 v1.9 之前新增 page.add_style_tag

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

用法

page.add_style_tag()
page.add_style_tag(**kwargs)

參數

  • content str (選填)#

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

  • path Union[str, pathlib.Path] (選填)#

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

  • url str (選填)#

    <link> 標籤的 URL。

返回

bring_to_front​

在 v1.9 之前新增 page.bring_to_front

將頁面帶到最前面（激活標籤頁）。

用法

page.bring_to_front()

返回

close​

在 v1.9 之前新增 page.close

如果 run_before_unload 為 false，則不執行任何卸載處理程序並等待頁面關閉。如果 run_before_unload 為 true，則該方法將執行卸載處理程序，但不會等待頁面關閉。

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

注意

如果 run_before_unload 作為 true 傳遞，則可能會調用 beforeunload 對話框，應通過 page.on("dialog") 事件手動處理。

用法

page.close()
page.close(**kwargs)

參數

  • reason str (選填)在 v1.40 中新增#

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

  • run_before_unload bool (選填)#

    預設為 false。是否執行 before unload 頁面處理程序。

返回

content​

在 v1.9 之前新增 page.content

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

用法

page.content()

返回

drag_and_drop​

在 v1.13 中新增 page.drag_and_drop

此方法將來源元素拖曳到目標元素。它將首先移動到來源元素，執行 mousedown，然後移動到目標元素並執行 mouseup。

用法

page.drag_and_drop("#source", "#target")
# or specify exact positions relative to the top-left corners of the elements:
page.drag_and_drop(
  "#source",
  "#target",
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

參數

  • source str#

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

  • target str#

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

  • force bool (選填)#

    是否繞過 actionability 檢查。預設為 false。

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • source_position Dict (選填)在 v1.14 中新增#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • target_position Dict (選填)在 v1.14 中新增#

    在此點將元素拖放到目標元素上，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

  • trial bool (選填)#

    設定後，此方法僅執行 actionability 檢查並跳過操作。預設為 false。用於等待直到元素準備好執行操作，而無需執行它。

返回

emulate_media​

在 v1.9 之前新增 page.emulate_media

此方法通過 media 參數更改 CSS 媒體類型，和/或使用 colorScheme 參數更改 'prefers-colors-scheme' 媒體功能。

用法

page.evaluate("matchMedia('screen').matches")
# → True
page.evaluate("matchMedia('print').matches")
# → False

page.emulate_media(media="print")
page.evaluate("matchMedia('screen').matches")
# → False
page.evaluate("matchMedia('print').matches")
# → True

page.emulate_media()
page.evaluate("matchMedia('screen').matches")
# → True
page.evaluate("matchMedia('print').matches")
# → False
page.emulate_media(color_scheme="dark")
page.evaluate("matchMedia('(prefers-color-scheme: dark)').matches")
# → True
page.evaluate("matchMedia('(prefers-color-scheme: light)').matches")
# → False

參數

  • color_scheme "light" | "dark" | "no-preference" | "null" (選填)在 v1.9 中新增#

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

  • forced_colors "active" | "none" | "null" (選填)在 v1.15 中新增#

  • media "screen" | "print" | "null" (選填)在 v1.9 中新增#

    更改頁面的 CSS 媒體類型。唯一允許的值為 'Screen'、'Print' 和 'Null'。傳遞 'Null' 會停用 CSS 媒體模擬。

  • reduced_motion "reduce" | "no-preference" | "null" (選填)在 v1.12 中新增#

    模擬 'prefers-reduced-motion' 媒體功能，支援的值為 'reduce'、'no-preference'。傳遞 null 會停用減少動態效果模擬。

返回

evaluate​

在 v1.9 之前新增 page.evaluate

返回 expression 呼叫的值。

如果傳遞給 page.evaluate() 的函數返回 Promise，則 page.evaluate() 將等待 Promise 解析並返回其值。

如果傳遞給 page.evaluate() 的函數返回非 Serializable 值，則 page.evaluate() 解析為 undefined。Playwright 也支援傳輸一些 JSON 無法序列化的其他值：-0、NaN、Infinity、-Infinity。

用法

將參數傳遞給 expression

result = page.evaluate("([x, y]) => Promise.resolve(x * y)", [7, 8])
print(result) # prints "56"

也可以傳遞字串而不是函數

print(page.evaluate("1 + 2")) # prints "3"
x = 10
print(page.evaluate(f"1 + {x}")) # prints "11"

ElementHandle 實例可以作為參數傳遞給 page.evaluate()

body_handle = page.evaluate("document.body")
html = page.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
body_handle.dispose()

參數

  • expression str#

    要在瀏覽器上下文中評估的 JavaScript 表達式。如果表達式評估為函數，則會自動調用該函數。

  • arg EvaluationArgument (選填)#

    要傳遞給 expression 的選填參數。

返回

evaluate_handle​

在 v1.9 之前新增 page.evaluate_handle

將 expression 呼叫的值作為 JSHandle 返回。

page.evaluate() 和 page.evaluate_handle() 之間的唯一區別在於 page.evaluate_handle() 返回 JSHandle。

如果傳遞給 page.evaluate_handle() 的函數返回 Promise，則 page.evaluate_handle() 將等待 Promise 解析並返回其值。

用法

a_window_handle = page.evaluate_handle("Promise.resolve(window)")
a_window_handle # handle for the window object.

也可以傳遞字串而不是函數

a_handle = page.evaluate_handle("document") # handle for the "document"

JSHandle 實例可以作為參數傳遞給 page.evaluate_handle()

a_handle = page.evaluate_handle("document.body")
result_handle = page.evaluate_handle("body => body.innerHTML", a_handle)
print(result_handle.json_value())
result_handle.dispose()

參數

  • expression str#

    要在瀏覽器上下文中評估的 JavaScript 表達式。如果表達式評估為函數，則會自動調用該函數。

  • arg EvaluationArgument (選填)#

    要傳遞給 expression 的選填參數。

返回

expect_console_message​

在 v1.9 中新增 page.expect_console_message

執行操作並等待頁面中記錄 ConsoleMessage。如果提供了 predicate，它會將 ConsoleMessage 值傳遞到 predicate 函數中，並等待 predicate(message) 返回 truthy 值。如果頁面在 page.on("console") 事件觸發之前關閉，則會拋出錯誤。

用法

page.expect_console_message()
page.expect_console_message(**kwargs)

參數

返回

expect_download​

在 v1.9 中新增 page.expect_download

執行操作並等待新的 Download。如果提供了 predicate，它會將 Download 值傳遞到 predicate 函數中，並等待 predicate(download) 返回 truthy 值。如果頁面在 download 事件觸發之前關閉，則會拋出錯誤。

用法

page.expect_download()
page.expect_download(**kwargs)

參數

返回

expect_event​

在 v1.9 之前新增 page.expect_event

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

用法

with page.expect_event("framenavigated") as event_info:
    page.get_by_role("button")
frame = event_info.value

參數

  • event str#

    事件名稱，通常與傳遞至 *.on(event) 的名稱相同。

  • predicate Callable (選填)#

    接收事件資料，並在等待應該結束時解析為真值 (truthy value)。

  • timeout float (選填)#

    最大等待時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 更改預設值。

返回

expect_file_chooser​

在 v1.9 中新增 page.expect_file_chooser

執行動作並等待新的 FileChooser 被建立。如果提供了 predicate，它會將 FileChooser 值傳遞到 predicate 函數中，並等待 predicate(fileChooser) 返回真值 (truthy value)。如果在檔案選擇器開啟之前頁面關閉，將會拋出錯誤。

用法

page.expect_file_chooser()
page.expect_file_chooser(**kwargs)

參數

返回

expect_popup​

在 v1.9 中新增 page.expect_popup

執行動作並等待彈出視窗 Page。如果提供了 predicate，它會將 [Popup] 值傳遞到 predicate 函數中，並等待 predicate(page) 返回真值 (truthy value)。如果在彈出事件觸發之前頁面關閉，將會拋出錯誤。

用法

page.expect_popup()
page.expect_popup(**kwargs)

參數

返回

expect_request​

在 v1.9 之前新增 page.expect_request

等待符合條件的請求並返回它。請參閱 waiting for event 以獲得關於事件的更多詳細資訊。

用法

with page.expect_request("http://example.com/resource") as first:
    page.get_by_text("trigger request").click()
first_request = first.value

# or with a lambda
with page.expect_request(lambda request: request.url == "http://example.com" and request.method == "get") as second:
    page.get_by_text("trigger request").click()
second_request = second.value

參數

  • url_or_predicate str | Pattern | Callable[Request]:bool#

    請求 URL 字串、正則表達式或 predicate，接收 Request 物件。當透過 context 選項提供了 base_url，且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。

  • timeout float (選填)#

    最大等待時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 page.set_default_timeout() 方法變更。

返回

expect_request_finished​

在 v1.12 中新增 page.expect_request_finished

執行動作並等待 Request 完成載入。如果提供了 predicate，它會將 Request 值傳遞到 predicate 函數中，並等待 predicate(request) 返回真值 (truthy value)。如果在 page.on("requestfinished") 事件觸發之前頁面關閉，將會拋出錯誤。

用法

page.expect_request_finished()
page.expect_request_finished(**kwargs)

參數

返回

expect_response​

在 v1.9 之前新增 page.expect_response

返回匹配的回應。請參閱 waiting for event 以獲得關於事件的更多詳細資訊。

用法

with page.expect_response("https://example.com/resource") as response_info:
    page.get_by_text("trigger response").click()
response = response_info.value
return response.ok

# or with a lambda
with page.expect_response(lambda response: response.url == "https://example.com" and response.status == 200 and response.request.method == "get") as response_info:
    page.get_by_text("trigger response").click()
response = response_info.value
return response.ok

參數

返回

expect_websocket​

在 v1.9 中新增 page.expect_websocket

執行動作並等待新的 WebSocket。如果提供了 predicate，它會將 WebSocket 值傳遞到 predicate 函數中，並等待 predicate(webSocket) 返回真值 (truthy value)。如果在 WebSocket 事件觸發之前頁面關閉，將會拋出錯誤。

用法

page.expect_websocket()
page.expect_websocket(**kwargs)

參數

返回

expect_worker​

在 v1.9 中新增 page.expect_worker

執行動作並等待新的 Worker。如果提供了 predicate，它會將 Worker 值傳遞到 predicate 函數中，並等待 predicate(worker) 返回真值 (truthy value)。如果在 worker 事件觸發之前頁面關閉，將會拋出錯誤。

用法

page.expect_worker()
page.expect_worker(**kwargs)

參數

返回

expose_binding​

在 v1.9 之前新增 page.expose_binding

此方法在頁面中每個 frame 的 window 物件上新增一個名為 name 的函數。當調用時，該函數會執行 callback 並返回一個 Promise，該 Promise 會解析為 callback 的返回值。如果 callback 返回一個 Promise，它將會被等待 (awaited)。

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

請參閱 browser_context.expose_binding() 以取得 context 範圍的版本。

注意

透過 page.expose_binding() 安裝的函數在導航後仍然存在。

用法

將頁面 URL 暴露給頁面中所有 frame 的範例

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = webkit.launch(headless=False)
    context = browser.new_context()
    page = context.new_page()
    page.expose_binding("pageURL", lambda source: source["page"].url)
    page.set_content("""
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.pageURL();
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
    """)
    page.click("button")

with sync_playwright() as playwright:
    run(playwright)

參數

  • name str#

    window 物件上的函數名稱。

  • callback Callable#

    將在 Playwright 的 context 中被調用的回調函數。

  • handle bool (選填)#

    已棄用

    此選項將在未來版本中移除。

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

返回

expose_function​

在 v1.9 之前新增 page.expose_function

此方法在頁面中每個 frame 的 window 物件上新增一個名為 name 的函數。當調用時，該函數會執行 callback 並返回一個 Promise，該 Promise 會解析為 callback 的返回值。

如果 callback 返回一個 Promise，它將會被等待 (awaited)。

請參閱 browser_context.expose_function() 以取得 context 範圍的暴露函數 (exposed function)。

注意

透過 page.expose_function() 安裝的函數在導航後仍然存在。

用法

將 sha256 函數新增到頁面的範例

import hashlib
from playwright.sync_api import sync_playwright, Playwright

def sha256(text):
    m = hashlib.sha256()
    m.update(bytes(text, "utf8"))
    return m.hexdigest()


def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = webkit.launch(headless=False)
    page = browser.new_page()
    page.expose_function("sha256", sha256)
    page.set_content("""
        <script>
          async function onClick() {
            document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
          }
        </script>
        <button onclick="onClick()">Click me</button>
        <div></div>
    """)
    page.click("button")

with sync_playwright() as playwright:
    run(playwright)

參數

  • name str#

    window 物件上的函數名稱

  • callback Callable#

    將在 Playwright 的 context 中被調用的回調函數。

返回

frame​

在 v1.9 之前新增 page.frame

返回符合指定條件的 frame。必須指定 name 或 url。

用法

frame = page.frame(name="frame-name")
frame = page.frame(url=r".*domain.*")

參數

  • name str (選填)#

    在 iframe 的 name 屬性中指定的 frame 名稱。選填。

  • url str | Pattern | Callable[URL]:bool (選填)#

    一個 glob 模式、正則表達式模式或 predicate，接收 frame 的 url 作為 URL 物件。選填。

返回

frame_locator​

新增於：v1.17 page.frame_locator

當使用 iframes 時，您可以建立一個 frame 定位器 (locator)，它將進入 iframe 並允許在該 iframe 中選擇元素。

用法

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

locator = page.frame_locator("#my-iframe").get_by_text("Submit")
locator.click()

參數

  • selector str#

    用於解析 DOM 元素的 selector。

返回

get_by_alt_text​

新增於：v1.27 page.get_by_alt_text

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

用法

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

<img alt='Playwright logo'>
page.get_by_alt_text("Playwright logo").click()

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配：區分大小寫且全字串匹配。預設為 false。當透過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白字元。

返回

get_by_label​

新增於：v1.27 page.get_by_label

允許透過相關聯的 <label> 或 aria-labelledby 元素的文字，或透過 aria-label 屬性，來定位輸入元素。

用法

例如，此方法將在以下 DOM 中，透過標籤 "Username" 和 "Password" 找到輸入框

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配：區分大小寫且全字串匹配。預設為 false。當透過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白字元。

返回

get_by_placeholder​

新增於：v1.27 page.get_by_placeholder

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

用法

例如，考慮以下 DOM 結構。

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

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

page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配：區分大小寫且全字串匹配。預設為 false。當透過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白字元。

返回

get_by_role​

新增於：v1.27 page.get_by_role

允許透過元素的 ARIA role、ARIA 屬性 和 可訪問名稱 來定位元素。

用法

考慮以下 DOM 結構。

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

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

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).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。

  • checked bool (選填)#

    一個通常由 aria-checked 或原生 <input type=checkbox> 控制項設定的屬性。

    了解更多關於 aria-checked 的資訊。

  • disabled bool (選填)#

    一個通常由 aria-disabled 或 disabled 設定的屬性。

    注意

    與大多數其他屬性不同，disabled 會透過 DOM 階層繼承。了解更多關於 aria-disabled 的資訊。

  • exact bool (選填)新增於：v1.28#

    name 是否完全匹配：區分大小寫且全字串匹配。預設為 false。當 name 是正則表達式時忽略。請注意，完全匹配仍然會修剪空白字元。

  • expanded bool (選填)#

    一個通常由 aria-expanded 設定的屬性。

    了解更多關於 aria-expanded 的資訊。

  • include_hidden bool (選填)#

    控制是否匹配隱藏元素的選項。預設情況下，只有非隱藏元素，如 ARIA 所定義，會被 role selector 匹配。

    了解更多關於 aria-hidden 的資訊。

  • level int (選填)#

    一個數字屬性，通常存在於 role 為 heading、listitem、row、treeitem 的元素中，<h1>-<h6> 元素有預設值。

    了解更多關於 aria-level 的資訊。

  • name str | Pattern (選填)#

    用於匹配 可訪問名稱 的選項。預設情況下，匹配不區分大小寫並搜尋子字串，使用 exact 來控制此行為。

    了解更多關於 可訪問名稱 的資訊。

  • pressed bool (選填)#

    一個通常由 aria-pressed 設定的屬性。

    了解更多關於 aria-pressed 的資訊。

  • selected bool (選填)#

    一個通常由 aria-selected 設定的屬性。

    了解更多關於 aria-selected 的資訊。

返回

詳細資訊

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

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

get_by_test_id​

新增於：v1.27 page.get_by_test_id

透過 test id 定位元素。

用法

考慮以下 DOM 結構。

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

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

page.get_by_test_id("directions").click()

參數

返回

詳細資訊

預設情況下，data-testid 屬性被用作 test id。如果需要，可以使用 selectors.set_test_id_attribute() 來配置不同的 test id 屬性。

get_by_text​

新增於：v1.27 page.get_by_text

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

另請參閱 locator.filter()，它允許通過其他條件（例如可訪問的角色）進行匹配，然後按文字內容進行篩選。

用法

考慮以下 DOM 結構

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

您可以使用文字子字串、精確字串或正規表示式進行定位

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配：區分大小寫且全字串匹配。預設為 false。當透過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白字元。

返回

詳細資訊

即使使用精確匹配，依文字匹配始終會正規化空格。例如，它會將多個空格變成一個空格，將換行符號變成空格，並忽略開頭和結尾的空格。

類型為 button 和 submit 的輸入元素會依其 value 而不是文字內容進行匹配。例如，依文字 "Log in" 定位會匹配 <input type=button value="Log in">。

get_by_title​

新增於：v1.27 page.get_by_title

允許依元素的 title 屬性進行定位。

用法

考慮以下 DOM 結構。

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

您可以在依標題文字定位元素後，檢查問題計數

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配：區分大小寫且全字串匹配。預設為 false。當透過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白字元。

返回

go_back​

在 v1.9 之前新增 page.go_back

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

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

用法

page.go_back()
page.go_back(**kwargs)

參數

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

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

    何時視為操作成功，預設為 load。事件可以是下列其中之一

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

返回

go_forward​

在 v1.9 之前新增 page.go_forward

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

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

用法

page.go_forward()
page.go_forward(**kwargs)

參數

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

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

    何時視為操作成功，預設為 load。事件可以是下列其中之一

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

返回

goto​

在 v1.9 之前新增 page.goto

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

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

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

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

注意

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

注意

無頭模式不支援導航到 PDF 文件。請參閱 上游問題。

用法

page.goto(url)
page.goto(url, **kwargs)

參數

  • url str#

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

  • referer str (選填)#

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

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

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

    何時視為操作成功，預設為 load。事件可以是下列其中之一

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

返回

locator​

在 v1.14 中新增 page.locator

此方法傳回元素定位器，可用於在此頁面/框架上執行操作。定位器會在執行操作之前立即解析為元素，因此同一定位器上的一系列操作實際上可以在不同的 DOM 元素上執行。如果這些操作之間的 DOM 結構已變更，則會發生這種情況。

了解更多關於定位器的資訊.

用法

page.locator(selector)
page.locator(selector, **kwargs)

參數

  • selector str#

    用於解析 DOM 元素的 selector。

  • has Locator (選填)#

    將此方法的結果縮小到包含與此相對定位器匹配的元素。例如，具有 text=Playwright 的 article 會匹配 <article><div>Playwright</div></article>。

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

    請注意，外部和內部定位器必須屬於同一個框架。內部定位器不得包含 FrameLocator。

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

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

    請注意，外部和內部定位器必須屬於同一個框架。內部定位器不得包含 FrameLocator。

  • has_not_text str | Pattern (選填)新增於：v1.33#

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

  • has_text str | Pattern (選填)#

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

返回

opener​

在 v1.9 之前新增 page.opener

傳回彈出頁面的 opener，其他頁面則傳回 null。如果 opener 已關閉，則傳回 null。

用法

page.opener()

返回

pause​

在 v1.9 中新增 page.pause

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

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

注意

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

用法

page.pause()

返回

pdf​

在 v1.9 之前新增 page.pdf

傳回 PDF buffer。

page.pdf() 使用 print css 媒體產生頁面的 pdf。若要使用 screen 媒體產生 pdf，請在呼叫 page.pdf() 之前呼叫 page.emulate_media()

注意

預設情況下，page.pdf() 會產生具有修改後顏色的 pdf 以進行列印。使用 -webkit-print-color-adjust 屬性強制呈現精確的顏色。

用法

# generates a pdf with "screen" media type.
page.emulate_media(media="screen")
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 英吋
注意

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

參數

  • display_header_footer bool (選填)#

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

  • footer_template str (選填)#

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

  • format str (選填)#

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

  • header_template str (選填)#

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

    • 'date' 格式化的列印日期
    • 'title' 文件標題
    • 'url' 文件位置
    • 'pageNumber' 目前頁碼
    • 'totalPages' 文件中的總頁數

  • height str | float (選填)#

    紙張高度，接受標記單位的數值。

  • landscape bool (選填)#

    紙張方向。預設為 false。

  • margin Dict (選填)#

    • top str | float (選填)

      上邊界，接受標記單位的數值。預設為 0。

    • right str | float (選填)

      右邊界，接受標記單位的數值。預設為 0。

    • bottom str | float (選填)

      下邊界，接受標記單位的數值。預設為 0。

    • left str | float (選填)

      左邊界，接受標記單位的數值。預設為 0。

    紙張邊界，預設為無。

  • outline bool (選填)在 v1.42 中新增#

    是否將文件外框嵌入 PDF 中。預設為 false。

  • page_ranges str (選填)#

    要列印的紙張範圍，例如 '1-5, 8, 11-13'。預設為空字串，表示列印所有頁面。

  • path Union[str, pathlib.Path] (選填)#

    用於儲存 PDF 的檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，則 PDF 將不會儲存到磁碟。

  • prefer_css_page_size bool (選填)#

    優先使用頁面中宣告的任何 CSS @page 大小，而不是在 width 和 height 或 format 選項中宣告的大小。預設為 false，這將縮放內容以適應紙張大小。

  • print_background bool (選填)#

    列印背景圖形。預設為 false。

  • scale float (選填)#

    網頁呈現的縮放比例。預設為 1。縮放比例必須介於 0.1 和 2 之間。

  • tagged bool (選填)在 v1.42 中新增#

    是否產生已標記 (可存取) 的 PDF。預設為 false。

  • width str | float (選填)#

    紙張寬度，接受標記單位的數值。

返回

reload​

在 v1.9 之前新增 page.reload

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

用法

page.reload()
page.reload(**kwargs)

參數

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

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

    何時視為操作成功，預設為 load。事件可以是下列其中之一

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

返回

remove_locator_handler​

在 v1.44 中新增 page.remove_locator_handler

移除由 page.add_locator_handler() 為特定定位器新增的所有定位器處理常式。

用法

page.remove_locator_handler(locator)

參數

返回

request_gc​

新增於：v1.48 page.request_gc

請求頁面執行垃圾回收。請注意，不保證會回收所有無法訪問的物件。

這有助於偵測記憶體洩漏。例如，如果您的頁面有一個可能洩漏的大型物件 'suspect'，您可以通過使用 WeakRef 來檢查它是否沒有洩漏。

# 1. In your page, save a WeakRef for the "suspect".
page.evaluate("globalThis.suspectWeakRef = new WeakRef(suspect)")
# 2. Request garbage collection.
page.request_gc()
# 3. Check that weak ref does not deref to the original object.
assert page.evaluate("!globalThis.suspectWeakRef.deref()")

用法

page.request_gc()

返回

route​

在 v1.9 之前新增 page.route

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

啟用路由後，每個與 url 模式匹配的請求都會停滯，除非它被繼續、滿足或中止。

注意

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

注意

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

注意

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

用法

中止所有影像請求的簡單處理常式範例

page = browser.new_page()
page.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())
page.goto("https://example.com")
browser.close()

或使用正規表示式模式的相同程式碼片段

page = browser.new_page()
page.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
page.goto("https://example.com")
browser.close()

可以檢查請求以決定路由操作。例如，模擬所有包含一些 post 數據的請求，並保持所有其他請求不變

def handle_route(route: Route):
  if ("my-string" in route.request.post_data):
    route.fulfill(body="mocked-data")
  else:
    route.continue_()
page.route("/api/**", handle_route)

當請求與兩個處理常式都匹配時，頁面路由優先於瀏覽器內容路由（使用 browser_context.route() 設定）。

若要移除具有其處理常式的路由，您可以使用 page.unroute()。

注意

啟用路由會停用 http 快取。

參數

  • url str | Pattern | Callable[URL]:bool#

    在路由時要匹配的 glob 模式、正規表示式模式或接收 URL 的述詞。當通過 context 選項提供 base_url 且傳遞的 URL 是路徑時，它會通過 new URL() 建構函式合併。

  • handler Callable[Route, Request]:Promise[Any] | Any#

    用於路由請求的處理常式函式。

  • times int (選填)在 v1.15 中新增#

    路由應使用的頻率。預設情況下，每次都會使用。

返回

route_from_har​

新增於：v1.23 page.route_from_har

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

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

用法

page.route_from_har(har)
page.route_from_har(har, **kwargs)

參數

  • har Union[str, pathlib.Path]#

    具有預先錄製網路數據的 HAR 檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。

  • not_found "abort" | "fallback" (選填)#

    • 如果設定為 'abort'，則任何在 HAR 檔案中找不到的請求都將被中止。
    • 如果設定為 'fallback'，則遺失的請求將被傳送到網路。

    預設為中止。

  • update bool (選填)#

    如果指定，則使用實際網路資訊更新給定的 HAR，而不是從檔案提供服務。當呼叫 browser_context.close() 時，檔案會寫入磁碟。

  • update_content "embed" | "attach" (選填)新增於：v1.32#

    用於控制資源內容管理的選填設定。如果指定 attach，則資源會以個別檔案或 ZIP 封存中的條目形式保存。如果指定 embed，則內容會以內嵌方式儲存在 HAR 檔案中。

  • update_mode "full" | "minimal" (選填)新增於：v1.32#

    當設定為 minimal 時，僅記錄從 HAR 路由所需的資訊。這省略了在從 HAR 重新播放時未使用的尺寸、計時、頁面、Cookie、安全性和其他類型的 HAR 資訊。預設為 minimal。

  • url str | Pattern (選填)#

    符合請求網址的 glob 模式、正規表示式或判斷條件。只有網址符合此模式的請求才會從 HAR 檔案提供服務。若未指定，所有請求都會從 HAR 檔案提供服務。

返回

route_web_socket​

新增於：v1.48 page.route_web_socket

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

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

用法

以下是一個簡單模擬回應單一訊息的範例。詳情和範例請參閱 WebSocketRoute。

def message_handler(ws: WebSocketRoute, message: Union[str, bytes]):
  if message == "request":
    ws.send("response")

def handler(ws: WebSocketRoute):
  ws.on_message(lambda message: message_handler(ws, message))

page.route_web_socket("/ws", handler)

參數

返回

screenshot​

在 v1.9 之前新增 page.screenshot

傳回包含已擷取螢幕截圖的緩衝區。

用法

page.screenshot()
page.screenshot(**kwargs)

參數

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

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

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

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

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

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

  • clip Dict (選填)#

    • x float

      剪裁區域左上角的 x 座標

    • y float

      剪裁區域左上角的 y 座標

    • width float

      剪裁區域的寬度

    • height float

      剪裁區域的高度

    一個物件，指定結果影像的剪裁範圍。

  • full_page bool (選填)#

    若為 true，則擷取整個可捲動頁面的螢幕截圖，而不是目前可見的視窗。預設值為 false。

  • mask List[Locator] (選填)#

    指定在擷取螢幕截圖時應遮罩的 locator。被遮罩的元素將會被粉紅色方框 #FF00FF (可透過 mask_color 自訂) 覆蓋，完全遮蓋其邊界框。

  • mask_color str (選填)新增於：v1.35#

    指定遮罩元素的覆蓋方框顏色，以 CSS 顏色格式 表示。預設顏色為粉紅色 #FF00FF。

  • omit_background bool (選填)#

    隱藏預設白色背景，並允許擷取具有透明度的螢幕截圖。不適用於 jpeg 影像。預設值為 false。

  • path Union[str, pathlib.Path] (選填)#

    儲存影像的檔案路徑。螢幕截圖類型將從檔案副檔名推斷。如果 path 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，則影像將不會儲存到磁碟。

  • quality int (選填)#

    影像品質，介於 0-100 之間。不適用於 png 影像。

  • scale "css" | "device" (選填)#

    當設定為 "css" 時，螢幕截圖在頁面上每個 css 像素會佔用單一像素。對於高 DPI 裝置，這將使螢幕截圖保持較小。使用 "device" 選項將會讓每個裝置像素產生單一像素，因此高 DPI 裝置的螢幕截圖將會大兩倍甚至更大。

    預設值為 "device"。

  • style str (選填)新增於：v1.41#

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

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

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

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

返回

set_content​

在 v1.9 之前新增 page.set_content

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

用法

page.set_content(html)
page.set_content(html, **kwargs)

參數

  • html str#

    要指派給頁面的 HTML 標記。

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

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

    何時視為操作成功，預設為 load。事件可以是下列其中之一

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

返回

set_default_navigation_timeout​

在 v1.9 之前新增 page.set_default_navigation_timeout

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

注意

page.set_default_navigation_timeout() 的優先順序高於 page.set_default_timeout()、browser_context.set_default_timeout() 和 browser_context.set_default_navigation_timeout()。

用法

page.set_default_navigation_timeout(timeout)

參數

  • timeout float#

    以毫秒為單位的最大導航時間

set_default_timeout​

在 v1.9 之前新增 page.set_default_timeout

此設定將變更所有接受 timeout 選項之方法的預設最大時間。

注意

page.set_default_navigation_timeout() 的優先順序高於 page.set_default_timeout()。

用法

page.set_default_timeout(timeout)

參數

  • timeout float#

    以毫秒為單位的最大時間。傳遞 0 以停用逾時。

set_extra_http_headers​

在 v1.9 之前新增 page.set_extra_http_headers

額外的 HTTP 標頭將會與頁面啟動的每個請求一起傳送。

注意

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

用法

page.set_extra_http_headers(headers)

參數

  • headers Dict[str, str]#

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

返回

set_viewport_size​

在 v1.9 之前新增 page.set_viewport_size

在單一瀏覽器中有多個頁面的情況下，每個頁面都可以有自己的視窗大小。但是，browser.new_context() 允許一次為上下文中的所有頁面設定視窗大小 (以及更多)。

page.set_viewport_size() 將會調整頁面大小。許多網站不希望手機變更大小，因此您應該在導航至頁面之前設定視窗大小。page.set_viewport_size() 也會重設 screen 大小，如果您需要更好地控制這些屬性，請使用帶有 screen 和 viewport 參數的 browser.new_context()。

用法

page = browser.new_page()
page.set_viewport_size({"width": 640, "height": 480})
page.goto("https://example.com")

參數

  • viewport_size Dict#

    • width int

      頁面寬度，以像素為單位。

    • height int

      頁面高度，以像素為單位。

返回

title​

在 v1.9 之前新增 page.title

傳回頁面的標題。

用法

page.title()

返回

unroute​

在 v1.9 之前新增 page.unroute

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

用法

page.unroute(url)
page.unroute(url, **kwargs)

參數

返回

unroute_all​

新增於：v1.41 page.unroute_all

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

用法

page.unroute_all()
page.unroute_all(**kwargs)

參數

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

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

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

返回

wait_for_event​

在 v1.9 之前新增 page.wait_for_event
注意

在大多數情況下，您應該使用 page.expect_event()。

等待給定的 event 觸發。如果提供 predicate，它會將事件的值傳遞到 predicate 函式中，並等待 predicate(event) 傳回 truthy 值。如果頁面在 event 觸發之前關閉，將會拋出錯誤。

用法

page.wait_for_event(event)
page.wait_for_event(event, **kwargs)

參數

  • event str#

    事件名稱，通常與傳遞至 *.on(event) 的名稱相同。

  • predicate Callable (選填)#

    接收事件資料，並在等待應該結束時解析為真值 (truthy value)。

  • timeout float (選填)#

    最大等待時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 更改預設值。

返回

wait_for_function​

在 v1.9 之前新增 page.wait_for_function

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

用法

page.wait_for_function() 可用於觀察視窗大小變更

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = webkit.launch()
    page = browser.new_page()
    page.evaluate("window.x = 0; setTimeout(() => { window.x = 100 }, 1000);")
    page.wait_for_function("() => window.x > 0")
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

若要將引數傳遞至 page.wait_for_function() 函式的 predicate

selector = ".foo"
page.wait_for_function("selector => !!document.querySelector(selector)", selector)

參數

  • expression str#

    要在瀏覽器上下文中評估的 JavaScript 表達式。如果表達式評估為函數，則會自動調用該函數。

  • arg EvaluationArgument (選填)#

    要傳遞至 expression 的選填引數。

  • polling float | "raf" (選填)#

    如果 polling 為 'raf'，則 expression 會在 requestAnimationFrame 回呼中持續執行。如果 polling 是一個數字，則會將其視為函數執行的間隔 (以毫秒為單位)。預設值為 raf。

  • timeout float (選填)#

    等待的最大時間 (以毫秒為單位)。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

返回

wait_for_load_state​

在 v1.9 之前新增 page.wait_for_load_state

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

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

注意

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

用法

page.get_by_role("button").click() # click triggers navigation.
page.wait_for_load_state() # the promise resolves after "load" event.
with page.expect_popup() as page_info:
    page.get_by_role("button").click() # click triggers a popup.
popup = page_info.value
# Wait for the "DOMContentLoaded" event.
popup.wait_for_load_state("domcontentloaded")
print(popup.title()) # popup is ready to use.

參數

  • state "load" | "domcontentloaded" | "networkidle" (選填)#

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

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

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

返回

wait_for_url​

新增於：v1.11 page.wait_for_url

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

用法

page.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
page.wait_for_url("**/target.html")

參數

  • url str | Pattern | Callable[URL]:bool#

    一個 glob 模式、regex 模式或判斷條件，接收 URL 以在等待導航時進行比對。請注意，如果參數是不含萬用字元的字串，則此方法將等待導航到與該字串完全相等的 URL。

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

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

    何時視為操作成功，預設為 load。事件可以是下列其中之一

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

返回

屬性​

clock​

新增於：v1.45 page.clock

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

用法

page.clock

類型

context​

在 v1.9 之前新增 page.context

取得頁面所屬的瀏覽器上下文。

用法

page.context

返回

frames​

在 v1.9 之前新增 page.frames

附加到頁面的所有框架陣列。

用法

page.frames

返回

is_closed​

在 v1.9 之前新增 page.is_closed

指示頁面是否已關閉。

用法

page.is_closed()

返回

keyboard​

在 v1.9 之前新增 page.keyboard

用法

page.keyboard

類型

main_frame​

在 v1.9 之前新增 page.main_frame

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

用法

page.main_frame

返回

mouse​

在 v1.9 之前新增 page.mouse

用法

page.mouse

類型

request​

新增於：v1.16 page.request

與此頁面相關聯的 API 測試輔助程式。此方法傳回與頁面上下文上的 browser_context.request 相同的實例。請參閱 browser_context.request 以取得更多詳細資訊。

用法

page.request

類型

touchscreen​

在 v1.9 之前新增 page.touchscreen

用法

page.touchscreen

類型

url​

在 v1.9 之前新增 page.url

用法

page.url

返回

video​

在 v1.9 之前新增 page.video

與此頁面相關聯的影片物件。

用法

page.video

返回

viewport_size​

在 v1.9 之前新增 page.viewport_size

用法

page.viewport_size

返回

  • NoneType | Dict#

    • width int

      頁面寬度，以像素為單位。

    • height int

      頁面高度，以像素為單位。

workers​

在 v1.9 之前新增 page.workers

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

注意

這不包含 ServiceWorkers

用法

page.workers

返回

事件​

on("close")​

在 v1.9 之前新增 page.on("close")

當頁面關閉時發出。

用法

page.on("close", handler)

事件資料

on("console")​

在 v1.9 之前新增 page.on("console")

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

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

用法

def print_args(msg):
    for arg in msg.args:
        print(arg.json_value())

page.on("console", print_args)
page.evaluate("console.log('hello', 5, { foo: 'bar' })")

事件資料

on("crash")​

在 v1.9 之前新增 page.on("crash")

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

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

try:
    # crash might happen during a click.
    page.click("button")
    # or while waiting for an event.
    page.wait_for_event("popup")
except Error as e:
    pass
    # when the page crashes, exception message contains "crash".

用法

page.on("crash", handler)

事件資料

on("dialog")​

在 v1.9 之前新增 page.on("dialog")

當 JavaScript 對話方塊出現時發出，例如 alert、prompt、confirm 或 beforeunload。監聽器必須 dialog.accept() 或 dialog.dismiss() 對話方塊 - 否則頁面將會 凍結 等待對話方塊，並且點擊等動作將永遠不會完成。

用法

page.on("dialog", lambda dialog: dialog.accept())
注意

當沒有 page.on("dialog") 或 browser_context.on("dialog") 監聽器存在時，所有對話方塊都會自動關閉。

事件資料

on("domcontentloaded")​

在 v1.9 中新增 page.on("domcontentloaded")

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

用法

page.on("domcontentloaded", handler)

事件資料

on("download")​

在 v1.9 之前新增 page.on("download")

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

用法

page.on("download", handler)

事件資料

on("filechooser")​

在 v1.9 中新增 page.on("filechooser")

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

page.on("filechooser", lambda file_chooser: file_chooser.set_files("/tmp/myfile.pdf"))

用法

page.on("filechooser", handler)

事件資料

on("frameattached")​

在 v1.9 中新增 page.on("frameattached")

當框架附加時發出。

用法

page.on("frameattached", handler)

事件資料

on("framedetached")​

在 v1.9 中新增 page.on("framedetached")

當框架分離時發出。

用法

page.on("framedetached", handler)

事件資料

on("framenavigated")​

在 v1.9 中新增 page.on("framenavigated")

當框架導航到新的網址時發出。

用法

page.on("framenavigated", handler)

事件資料

on("load")​

在 v1.9 之前新增 page.on("load")

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

用法

page.on("load", handler)

事件資料

on("pageerror")​

在 v1.9 中新增 page.on("pageerror")

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

# Log all uncaught errors to the terminal
page.on("pageerror", lambda exc: print(f"uncaught exception: {exc}"))

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

用法

page.on("pageerror", handler)

事件資料

on("popup")​

在 v1.9 之前新增 page.on("popup")

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

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

with page.expect_event("popup") as page_info:
    page.get_by_text("open the popup").click()
popup = page_info.value
print(popup.evaluate("location.href"))
注意

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

用法

page.on("popup", handler)

事件資料

on("request")​

在 v1.9 之前新增 page.on("request")

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

用法

page.on("request", handler)

事件資料

on("requestfailed")​

在 v1.9 中新增 page.on("requestfailed")

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

page.on("requestfailed", lambda request: print(request.url + " " + request.failure.error_text))
注意

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

用法

page.on("requestfailed", handler)

事件資料

on("requestfinished")​

在 v1.9 中新增 page.on("requestfinished")

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

用法

page.on("requestfinished", handler)

事件資料

on("response")​

在 v1.9 之前新增 page.on("response")

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

用法

page.on("response", handler)

事件資料

on("websocket")​

在 v1.9 中新增 page.on("websocket")

當 WebSocket 請求被發送時發出。

用法

page.on("websocket", handler)

事件資料

on("worker")​

在 v1.9 之前新增 page.on("worker")

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

用法

page.on("worker", handler)

事件資料

已棄用​

accessibility​

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

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

用法

page.accessibility

類型

check​

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

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

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

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

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

用法

page.check(selector)
page.check(selector, **kwargs)

參數

  • selector str#

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

  • force bool (選填)#

    是否繞過 actionability 檢查。預設為 false。

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)新增於：v1.11#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

  • trial bool (選填)新增於：v1.11#

    設定後，此方法僅執行 actionability 檢查並跳過操作。預設為 false。用於等待直到元素準備好執行操作，而無需執行它。

返回

click​

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

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

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

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

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

用法

page.click(selector)
page.click(selector, **kwargs)

參數

  • selector str#

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

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

    預設為 left。

  • click_count int (選填)#

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

  • delay float (選填)#

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

  • force bool (選填)#

    是否繞過 actionability 檢查。預設為 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

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

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

  • position Dict (選填)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

  • trial bool (選填)新增於：v1.11#

    當設定時，此方法僅執行 actionability 檢查並跳過動作。預設為 false。適用於等待元素準備好執行動作，但不執行該動作。請注意，鍵盤 modifiers 將始終被按下，而與 trial 無關，以允許測試僅在按下這些鍵時才可見的元素。

返回

dblclick​

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

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

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

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

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

注意

page.dblclick() 分派兩個 click 事件和一個 dblclick 事件。

用法

page.dblclick(selector)
page.dblclick(selector, **kwargs)

參數

  • selector str#

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

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

    預設為 left。

  • delay float (選填)#

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

  • force bool (選填)#

    是否繞過 actionability 檢查。預設為 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

  • trial bool (選填)新增於：v1.11#

    當設定時，此方法僅執行 actionability 檢查並跳過動作。預設為 false。適用於等待元素準備好執行動作，但不執行該動作。請注意，鍵盤 modifiers 將始終被按下，而與 trial 無關，以允許測試僅在按下這些鍵時才可見的元素。

返回

dispatch_event​

在 v1.9 之前新增 page.dispatch_event
不建議使用

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

以下程式碼片段會在元素上分派 click 事件。無論元素的顯示狀態如何，都會分派 click。這相當於呼叫 element.click()。

用法

page.dispatch_event("button#submit", "click")

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

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

如果您希望將即時物件傳遞到事件中，您也可以將 JSHandle 指定為屬性值

# note you can only create data_transfer in chromium and firefox
data_transfer = page.evaluate_handle("new DataTransfer()")
page.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })

參數

  • selector str#

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

  • type str#

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

  • event_init EvaluationArgument (選填)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

eval_on_selector​

在 v1.9 中新增 page.eval_on_selector
不建議使用

此方法不會等待元素通過 actionability 檢查，因此可能導致測試不穩定。請改用 locator.evaluate()、其他 Locator 輔助方法或 web-first assertions。

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

如果 expression 返回 Promise，則 page.eval_on_selector() 將等待 promise 解析並返回其值。

用法

search_value = page.eval_on_selector("#search", "el => el.value")
preload_href = page.eval_on_selector("link[rel=preload]", "el => el.href")
html = page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello")

參數

  • selector str#

    要查詢的 selector。

  • expression str#

    要在瀏覽器上下文中評估的 JavaScript 表達式。如果表達式評估為函數，則會自動調用該函數。

  • arg EvaluationArgument (選填)#

    要傳遞給 expression 的選填引數。

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

返回

eval_on_selector_all​

在 v1.9 中新增 page.eval_on_selector_all
不建議使用

在大多數情況下，locator.evaluate_all()、其他 Locator 輔助方法和 web-first assertions 可以更好地完成工作。

此方法在頁面中尋找符合指定 selector 的所有元素，並將符合元素的陣列作為第一個引數傳遞給 expression。返回 expression 調用的結果。

如果 expression 返回 Promise，則 page.eval_on_selector_all() 將等待 promise 解析並返回其值。

用法

div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)

參數

  • selector str#

    要查詢的 selector。

  • expression str#

    要在瀏覽器上下文中評估的 JavaScript 表達式。如果表達式評估為函數，則會自動調用該函數。

  • arg EvaluationArgument (選填)#

    要傳遞給 expression 的選填引數。

返回

expect_navigation​

在 v1.9 之前新增 page.expect_navigation
已棄用

此方法本質上是 race condition 的，請改用 page.wait_for_url()。

等待主框架導航，並傳回主資源回應。在多次重定向的情況下，導航將解析為最後一次重定向的回應。在導航到不同的錨點或由於 History API 使用而導航的情況下，導航將解析為 null。

用法

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

with page.expect_navigation():
    # This action triggers the navigation after a timeout.
    page.get_by_text("Navigate after timeout").click()
# Resolves after navigation has finished
注意

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

參數

  • timeout float (選填)#

    最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • url str | Pattern | Callable[URL]:bool (選填)#

    一個 glob 模式、regex 模式或判斷條件，接收 URL 以在等待導航時進行比對。請注意，如果參數是不含萬用字元的字串，則此方法將等待導航到與該字串完全相等的 URL。

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

    何時視為操作成功，預設為 load。事件可以是下列其中之一

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

返回

fill​

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

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

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

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

要發送細粒度的鍵盤事件，請使用 locator.press_sequentially()。

用法

page.fill(selector, value)
page.fill(selector, value, **kwargs)

參數

  • selector str#

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

  • value str#

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

  • force bool (選填)在 v1.13 中新增#

    是否繞過 actionability 檢查。預設為 false。

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

focus​

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

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

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

用法

page.focus(selector)
page.focus(selector, **kwargs)

參數

  • selector str#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

get_attribute​

在 v1.9 之前新增 page.get_attribute
不建議使用

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

傳回元素屬性值。

用法

page.get_attribute(selector, name)
page.get_attribute(selector, name, **kwargs)

參數

  • selector str#

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

  • name str#

    要取得值的屬性名稱。

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

hover​

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

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

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

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

當所有步驟組合起來在指定的 timeout 時間內尚未完成時，此方法會拋出 TimeoutError 錯誤。傳遞零 timeout 值會停用此功能。

用法

page.hover(selector)
page.hover(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • force 布林值 (bool) (選填)#

    是否繞過 actionability 檢查。預設為 false。

  • modifiers 列表 (List)["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after bool (選填)新增於：v1.28#

    已棄用

    此選項無效。

    此選項無效。

  • position 字典 (Dict) (選填)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

  • trial bool (選填)新增於：v1.11#

    當設定時，此方法僅執行 actionability 檢查並跳過動作。預設為 false。適用於等待元素準備好執行動作，但不執行該動作。請注意，鍵盤 modifiers 將始終被按下，而與 trial 無關，以允許測試僅在按下這些鍵時才可見的元素。

返回

inner_html​

在 v1.9 之前新增 page.inner_html
不建議使用

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

傳回 element.innerHTML。

用法

page.inner_html(selector)
page.inner_html(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

inner_text​

在 v1.9 之前新增 page.inner_text
不建議使用

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

傳回 element.innerText。

用法

page.inner_text(selector)
page.inner_text(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

input_value​

在 v1.13 中新增 page.input_value
不建議使用

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

傳回所選取 <input> 或 <textarea> 或 <select> 元素的 input.value。

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

用法

page.input_value(selector)
page.input_value(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

is_checked​

在 v1.9 之前新增 page.is_checked
不建議使用

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

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

用法

page.is_checked(selector)
page.is_checked(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

is_disabled​

在 v1.9 之前新增 page.is_disabled
不建議使用

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

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

用法

page.is_disabled(selector)
page.is_disabled(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

is_editable​

在 v1.9 之前新增 page.is_editable
不建議使用

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

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

用法

page.is_editable(selector)
page.is_editable(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

is_enabled​

在 v1.9 之前新增 page.is_enabled
不建議使用

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

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

用法

page.is_enabled(selector)
page.is_enabled(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

is_hidden​

在 v1.9 之前新增 page.is_hidden
不建議使用

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

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

用法

page.is_hidden(selector)
page.is_hidden(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    已棄用

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

返回

is_visible​

在 v1.9 之前新增 page.is_visible
不建議使用

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

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

用法

page.is_visible(selector)
page.is_visible(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    已棄用

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

返回

press​

在 v1.9 之前新增 page.press
不建議使用

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

聚焦元素，然後使用 keyboard.down() 和 keyboard.up()。

key 可以指定預期的 keyboardEvent.key 值或產生文字的單一字元。key 值的超集合可以在 這裡 找到。按鍵範例包括

F1 - F12、Digit0- Digit9、KeyA- KeyZ、Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、ArrowUp 等。

也支援下列修改鍵快捷鍵：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析為 Control，在 macOS 上解析為 Meta。

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

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

也支援例如 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 等快捷鍵。當使用修改鍵指定時，按下修改鍵並保持按住狀態，同時按下後續按鍵。

用法

page = browser.new_page()
page.goto("https://keycode.info")
page.press("body", "A")
page.screenshot(path="a.png")
page.press("body", "ArrowLeft")
page.screenshot(path="arrow_left.png")
page.press("body", "Shift+O")
page.screenshot(path="o.png")
browser.close()

參數

  • selector 字串 (str)#

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

  • key 字串 (str)#

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

  • delay 浮點數 (float) (選填)#

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

  • no_wait_after 布林值 (bool) (選填)#

    已棄用

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

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

query_selector​

在 v1.9 中新增 page.query_selector
不建議使用

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

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

用法

page.query_selector(selector)
page.query_selector(selector, **kwargs)

參數

  • selector 字串 (str)#

    要查詢的 selector。

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

返回

query_selector_all​

在 v1.9 中新增 page.query_selector_all
不建議使用

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

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

用法

page.query_selector_all(selector)

參數

返回

select_option​

在 v1.9 之前新增 page.select_option
不建議使用

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

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

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

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

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

用法

# Single selection matching the value or label
page.select_option("select#colors", "blue")
# single selection matching both the label
page.select_option("select#colors", label="blue")
# multiple selection
page.select_option("select#colors", value=["red", "green", "blue"])

參數

返回

set_checked​

在 v1.15 中新增 page.set_checked
不建議使用

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

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

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

當所有步驟組合起來在指定的 timeout 時間內尚未完成時，此方法會拋出 TimeoutError 錯誤。傳遞零 timeout 值會停用此功能。

用法

page.set_checked(selector, checked)
page.set_checked(selector, checked, **kwargs)

參數

返回

set_input_files​

在 v1.9 之前新增 page.set_input_files
不建議使用

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

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

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

用法

page.set_input_files(selector, files)
page.set_input_files(selector, files, **kwargs)

參數

返回

tap​

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

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

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

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

當所有步驟組合起來在指定的 timeout 時間內尚未完成時，此方法會拋出 TimeoutError 錯誤。傳遞零 timeout 值會停用此功能。

注意

如果瀏覽器內容的 has_touch 選項為 false，則 page.tap() 方法會拋出錯誤。

用法

page.tap(selector)
page.tap(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • force 布林值 (bool) (選填)#

    是否繞過 actionability 檢查。預設為 false。

  • modifiers 列表 (List)["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after 布林值 (bool) (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position 字典 (Dict) (選填)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

  • trial bool (選填)新增於：v1.11#

    當設定時，此方法僅執行 actionability 檢查並跳過動作。預設為 false。適用於等待元素準備好執行動作，但不執行該動作。請注意，鍵盤 modifiers 將始終被按下，而與 trial 無關，以允許測試僅在按下這些鍵時才可見的元素。

返回

text_content​

在 v1.9 之前新增 page.text_content
不建議使用

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

傳回 element.textContent。

用法

page.text_content(selector)
page.text_content(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

type​

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

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

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

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

用法

參數

  • selector 字串 (str)#

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

  • text 字串 (str)#

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

  • delay 浮點數 (float) (選填)#

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

  • no_wait_after 布林值 (bool) (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

uncheck​

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

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

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

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

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

用法

page.uncheck(selector)
page.uncheck(selector, **kwargs)

參數

  • selector 字串 (str)#

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

  • force 布林值 (bool) (選填)#

    是否繞過 actionability 檢查。預設為 false。

  • no_wait_after 布林值 (bool) (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)新增於：v1.11#

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

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

  • trial bool (選填)新增於：v1.11#

    設定後，此方法僅執行 actionability 檢查並跳過操作。預設為 false。用於等待直到元素準備好執行操作，而無需執行它。

返回

wait_for_selector​

在 v1.9 之前新增 page.wait_for_selector
不建議使用

使用網路斷言來斷言可見性，或使用基於定位器的 locator.wait_for()。閱讀更多關於 定位器 的資訊。

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

注意

Playwright 會自動等待元素準備就緒後再執行動作。使用 Locator 物件和網路優先斷言，使程式碼無需 wait-for-selector。

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

用法

此方法適用於跨頁面導航

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    chromium = playwright.chromium
    browser = chromium.launch()
    page = browser.new_page()
    for current_url in ["https://google.com", "https://bbc.com"]:
        page.goto(current_url, wait_until="domcontentloaded")
        element = page.wait_for_selector("img")
        print("Loaded image: " + str(element.get_attribute("src")))
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

參數

  • selector 字串 (str)#

    要查詢的 selector。

  • state "attached" | "detached" | "visible" | "hidden" (選填)#

    預設為 'visible'。可以是下列其中之一

    • 'attached' - 等待元素出現在 DOM 中。
    • 'detached' - 等待元素從 DOM 中移除。
    • 'visible' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，並且不被視為可見。
    • 'hidden' - 等待元素從 DOM 中分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。

  • strict bool (選填)在 v1.14 中新增#

    當為 true 時，呼叫需要選擇器解析為單個元素。如果給定的選擇器解析為多個元素，則呼叫會拋出例外。

  • timeout 浮點數 (float) (選填)#

    最大時間（以毫秒為單位）。預設為 30000（30 秒）。傳遞 0 以停用超時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改預設值。

返回

wait_for_timeout​

在 v1.9 之前新增 page.wait_for_timeout
不建議使用

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

等待指定的 timeout 毫秒數。

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

用法

# wait for 1 second
page.wait_for_timeout(1000)

參數

返回