跳到主要內容

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 的原生 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 環境很有用，例如，播種 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 在每次執行或重試需要 可操作性檢查 的動作之前，或在執行自動等待斷言檢查之前，都會檢查覆蓋層。當覆蓋層可見時，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()

在每次可操作性檢查時使用自訂回呼的範例。它使用始終可見的 <body> 定位器，因此處理常式會在每次可操作性檢查之前呼叫。指定 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

將具有所需 url 的 <link rel="stylesheet"> 標籤或具有內容的 <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 (選用)#

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

  • no_wait_after bool (選用)#

    已棄用

    此選項無效。

    此選項無效。

  • source_position Dict (選用)新增於：v1.14#

    在此點按一下來源元素，相對於元素填補框的左上角。如果未指定，則會使用元素的某些可見點。

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

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

  • target_position Dict (選用)新增於：v1.14#

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

  • timeout float (選用)#

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

  • trial bool (選用)#

    設定後，此方法僅執行 可操作性 檢查，並略過動作。預設為 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' 已棄用。

  • contrast "no-preference" | "more" | "null" (選用)新增於：v1.51#

  • 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。如果提供謂詞，它會將 ConsoleMessage 值傳遞到 predicate 函式中，並等待 predicate(message) 傳回真值。如果在 page.on("console") 事件觸發之前頁面已關閉，則會擲回錯誤。

用法

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

引數

傳回

expect_download​

新增於：v1.9 page.expect_download

執行動作並等待新的 Download。如果提供謂詞，它會將 Download 值傳遞到 predicate 函式中，並等待 predicate(download) 傳回真值。如果在下載事件觸發之前頁面已關閉，則會擲回錯誤。

用法

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

引數

傳回

expect_event​

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

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

用法

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

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

用法

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 字串、正則表達式或接收 Request 物件的 predicate。當通過 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

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

用法

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，它將被等待。

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

有關 context 範圍的版本，請參閱 browser_context.expose_binding()。

注意

通過 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，它將被等待。

有關 context 範圍的暴露函數，請參閱 browser_context.expose_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 模式、正則表達式模式或接收 frame 的 url 作為 URL 物件的 predicate。選填。

傳回

frame_locator​

新增於: v1.17 page.frame_locator

當使用 iframe 時，您可以建立一個 frame 定位器，它將進入 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 角色、ARIA 屬性 和 可訪問名稱來定位元素。

用法

考慮以下 DOM 結構。

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

您可以通過其隱含角色定位每個元素

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 角色。

  • 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 定義）會被角色選取器匹配。

    了解更多關於 aria-hidden。

  • level int (選填)#

    數字屬性，通常用於角色 heading、listitem、row、treeitem，對於 <h1>-<h6> 元素具有預設值。

    了解更多關於 aria-level。

  • name str | Pattern (選填)#

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

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

  • pressed bool (選填)#

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

    深入瞭解 aria-pressed。

  • selected bool (選填)#

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

    深入瞭解 aria-selected。

傳回

詳細資訊

角色選擇器無法取代可及性稽核與符合性測試，而是提供關於 ARIA 指導方針的早期回饋。

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

get_by_test_id​

新增於: v1.27 page.get_by_test_id

依測試 ID 定位元素。

用法

考慮以下 DOM 結構。

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

您可以依元素的測試 ID 定位

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

引數

傳回

詳細資訊

預設情況下，data-testid 屬性會作為測試 ID 使用。如有必要，請使用 selectors.set_test_id_attribute() 來設定不同的測試 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

允許依元素的標題屬性定位元素。

用法

考慮以下 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 無效。
  • 導覽期間超過逾時。
  • 遠端伺服器沒有回應或無法連線。
  • 主要資源載入失敗。

當遠端伺服器傳回任何有效的 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 應包含協定，例如 https://。當透過內容選項提供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

傳回彈出式頁面的開啟器，其他頁面則傳回 null。如果開啟器已關閉，則傳回 null。

用法

page.opener()

傳回

pause​

新增於：v1.9 page.pause

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

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

注意

此方法需要以有頭模式啟動 Playwright，並使用 falsey headless 選項。

用法

page.pause()

傳回

pdf​

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

傳回 PDF 緩衝區。

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#

    用於路由請求的 handler 函數。

  • times int (選用)新增於：v1.15#

    路由應該被使用的頻率。預設情況下，它將每次都被使用。

傳回

route_from_har​

加入於：v1.23 page.route_from_har

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

Playwright 將不會從 HAR 檔案提供 Service Worker 攔截的請求。請參閱 此 issue。我們建議在使用請求攔截時停用 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'，則遺失的請求將被發送到網路。

    預設為 abort。

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

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

傳回

route_web_socket​

新增於：v1.48 page.route_web_socket

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

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

用法

以下是一個簡單模擬的範例，它回應單一訊息。有關更多詳細資訊和範例，請參閱 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 時，將擷取完整可滾動頁面的螢幕截圖，而不是目前可見的 viewport。預設為 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 以停用 timeout。

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

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

page.set_viewport_size() 將調整頁面大小。許多網站不希望手機更改大小，因此您應該在導航到頁面之前設定 viewport 大小。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" (可選)#

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

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

傳回

wait_for_event​

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

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

等待給定的 event 觸發。如果提供了謂詞，它會將事件的值傳遞到 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() 可用於觀察 viewport 大小變更

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() 函數的謂詞

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 以停用 timeout。預設值可以使用 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 毫秒沒有網路連線。請勿使用此方法進行測試，而是依賴 web 斷言來評估準備就緒狀態。

  • 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 模式、正則表達式模式或接收 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' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

Properties​

clock​

加入於：v1.45 page.clock

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

用法

page.clock

類型

context​

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

取得頁面所屬的瀏覽器 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 測試 helper。此方法傳回與頁面 context 上的 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

與此頁面相關聯的 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")

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

用法

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")

當請求在下載回應本文後成功完成時發出。對於成功的回應，事件順序為 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. 確保匹配的元素是核取方塊或單選輸入框。如果不是，此方法會拋出錯誤。如果元素已勾選，此方法會立即返回。
  3. 除非設定了 force 選項，否則等待匹配元素上的 可操作性 檢查。如果元素在檢查期間分離，則會重試整個操作。
  4. 如果需要，將元素滾動到視窗中。
  5. 使用 page.mouse 在元素的中心點擊。
  6. 確保元素現在已勾選。如果沒有，此方法會拋出錯誤。

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

用法

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

引數

  • selector str#

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

  • force bool (可選)#

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

  • no_wait_after bool (可選)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (可選)加入於：v1.11#

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

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

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

  • timeout float (可選)#

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

  • trial bool (可選)加入於：v1.11#

    設定後，此方法僅執行 可操作性 檢查，並略過動作。預設為 false。有助於等待直到元素準備好執行動作，而無需執行它。

傳回

click​

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

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

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

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

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

用法

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

引數

  • selector str#

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

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

    預設為 left。

  • click_count int (可選)#

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

  • delay float (可選)#

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

  • force bool (可選)#

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

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

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

  • no_wait_after bool (可選)#

    已棄用

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

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

  • position Dict (可選)#

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

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

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

  • timeout float (可選)#

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

  • trial bool (可選)加入於：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。傳遞零逾時將停用此功能。

注意

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

用法

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

引數

  • selector str#

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

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

    預設為 left。

  • delay float (可選)#

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

  • force bool (可選)#

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

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

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

  • no_wait_after bool (可選)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (可選)#

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

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

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

  • timeout float (可選)#

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

  • trial bool (可選)加入於：v1.11#

    設定後，此方法僅執行 可操作性 檢查，並跳過該動作。預設為 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#

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

  • 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
不建議使用

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

此方法會尋找頁面中符合指定選擇器的元素，並將其作為第一個引數傳遞給 expression。如果沒有元素符合選擇器，則此方法會拋出錯誤。傳回 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#

    要查詢的選擇器。

  • 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 會做得更好。

此方法會尋找頁面中符合指定選擇器的所有元素，並將匹配元素的陣列作為第一個引數傳遞給 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#

    要查詢的選擇器。

  • expression str#

    要在瀏覽器內容中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動調用該函式。

  • arg EvaluationArgument (可選)#

    要傳遞給 expression 的可選引數。

傳回

expect_navigation​

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

此方法本質上是競爭的，請改用 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 模式、正則表達式模式或接收 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 的元素，等待 可操作性 檢查，聚焦元素，填充它，並在填充後觸發 input 事件。請注意，您可以傳遞空字串來清除輸入欄位。

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

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

用法

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

引數

  • selector str#

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

  • value str#

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

  • force bool (可選)新增於：v1.13#

    是否略過 可操作性 檢查。預設為 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.focus()。請閱讀更多關於定位器的資訊。

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

用法

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

引數

  • selector 字串 (str)#

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

  • 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.get_attribute()。請閱讀更多關於定位器的資訊。

傳回元素屬性值。

用法

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

引數

  • selector 字串 (str)#

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

  • 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.hover()。請閱讀更多關於定位器的資訊。

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

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

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

用法

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

引數

  • selector 字串 (str)#

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

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

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

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

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

  • no_wait_after bool (選用)新增於: v1.28#

    已棄用

    此選項無效。

    此選項無效。

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

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

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

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

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

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

  • trial bool (可選)加入於：v1.11#

    設定後，此方法僅執行 可操作性 檢查，並跳過該動作。預設為 false。適用於等待元素準備好執行動作，而無需執行它。請注意，鍵盤 modifiers 將會被按下，無論 trial 是否為真，以便測試僅在按下這些鍵時才可見的元素。

傳回

inner_html​

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

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

傳回 element.innerHTML。

用法

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

引數

  • selector 字串 (str)#

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

  • 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.inner_text()。請閱讀更多關於定位器的資訊。

傳回 element.innerText。

用法

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

引數

  • selector 字串 (str)#

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

  • 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.input_value()。請閱讀更多關於定位器的資訊。

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

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

用法

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

引數

  • selector 字串 (str)#

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

  • 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.is_checked()。請閱讀更多關於定位器的資訊。

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

用法

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

引數

  • selector 字串 (str)#

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

  • 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.is_disabled()。請閱讀更多關於定位器的資訊。

傳回元素是否已停用，與啟用相反。

用法

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

引數

  • selector 字串 (str)#

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

  • 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.is_editable()。請閱讀更多關於定位器的資訊。

傳回元素是否為可編輯。

用法

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

引數

  • selector 字串 (str)#

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

  • 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.is_enabled()。請閱讀更多關於定位器的資訊。

傳回元素是否為啟用。

用法

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

引數

  • selector 字串 (str)#

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

  • 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.is_hidden()。請閱讀更多關於定位器的資訊。

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

用法

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

引數

  • selector 字串 (str)#

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

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

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

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

    已棄用

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

傳回

is_visible​

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

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

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

用法

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

引數

  • selector 字串 (str)#

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

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

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

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

    已棄用

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

傳回

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" 之類的快捷鍵。當使用修飾鍵指定時，在按下後續按鍵時，修飾鍵會被按下並保持按住狀態。

用法

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

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

  • 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
不建議使用

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

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

用法

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

引數

  • selector 字串 (str)#

    要查詢的選擇器。

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

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

傳回

query_selector_all​

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

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

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

用法

page.query_selector_all(selector)

引數

傳回

select_option​

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

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

此方法等待符合 selector 的元素，等待可操作性檢查，等待直到所有指定的選項都出現在 <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.set_checked()。請閱讀更多關於定位器的資訊。

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

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

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

用法

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

引數

傳回

set_input_files​

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

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

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

此方法預期 selector 指向 輸入元素。但是，如果元素位於具有相關控制項的 <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. 等待符合元素的可操作性檢查，除非設定了 force 選項。如果在檢查期間元素被分離，則會重試整個動作。
  3. 如果需要，將元素滾動到視窗中。
  4. 使用 page.touchscreen 點擊元素的中心，或指定的 position。

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

注意

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

用法

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

引數

  • selector str#

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

  • force bool (選填)#

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

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

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

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)#

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

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

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

  • timeout float (選填)#

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

  • trial bool (可選)加入於：v1.11#

    設定後，此方法僅執行 可操作性 檢查，並跳過該動作。預設為 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#

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

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

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

  • 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 錯誤。傳遞零逾時將停用此功能。

用法

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

引數

  • selector str#

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

  • force bool (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (可選)加入於：v1.11#

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

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

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

  • timeout float (選填)#

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

  • trial bool (可選)加入於：v1.11#

    設定後，此方法僅執行 可操作性 檢查，並略過動作。預設為 false。有助於等待直到元素準備好執行動作，而無需執行它。

傳回

wait_for_selector​

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

請改用斷言可見性的 Web 斷言或基於 locator 的 locator.wait_for()。深入了解 locators。

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

注意

Playwright 會在執行動作之前自動等待元素準備就緒。使用 Locator 物件和 Web 優先斷言使程式碼無需 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#

    要查詢的選擇器。

  • 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
不建議使用

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

等待指定的 timeout 毫秒。

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

用法

# wait for 1 second
page.wait_for_timeout(1000)

引數

  • timeout float#

    要等待的逾時時間

傳回