Actions
簡介
Playwright 可以與 HTML 輸入元素互動,包括文字輸入、核取方塊、單選按鈕、選擇選項、滑鼠點擊、輸入字元、按鍵和快捷鍵,以及上傳檔案和聚焦元素。
文字輸入
使用 Locator.FillAsync()
是填寫表單欄位最簡單的方式。它會聚焦元素並觸發包含輸入文字的 input
事件。適用於 <input>
、<textarea>
和 [contenteditable]
元素。
// Text input
await page.GetByRole(AriaRole.Textbox).FillAsync("Peter");
// Date input
await page.GetByLabel("Birth date").FillAsync("2020-02-02");
// Time input
await page.GetByLabel("Appointment time").FillAsync("13-15");
// Local datetime input
await page.GetByLabel("Local time").FillAsync("2020-03-02T05:15");
核取方塊和單選按鈕
使用 Locator.SetCheckedAsync()
是勾選和取消勾選核取方塊或單選按鈕最簡單的方式。此方法適用於 input[type=checkbox]
、input[type=radio]
和 [role=checkbox]
元素。
// Check the checkbox
await page.GetByLabel("I agree to the terms above").CheckAsync();
// Assert the checked state
await Expect(page.GetByLabel("Subscribe to newsletter")).ToBeCheckedAsync();
// Select the radio button
await page.GetByLabel("XL").CheckAsync();
選擇選項
使用 Locator.SelectOptionAsync()
在 <select>
元素中選擇一個或多個選項。您可以指定選項的 value
或 label
來選擇。可以選擇多個選項。
// Single selection matching the value or label
await page.GetByLabel("Choose a color").SelectOptionAsync("blue");
// Single selection matching the label
await page.GetByLabel("Choose a color").SelectOptionAsync(new SelectOptionValue { Label = "blue" });
// Multiple selected items
await page.GetByLabel("Choose multiple colors").SelectOptionAsync(new[] { "blue", "green", "red" });
滑鼠點擊
執行簡單的人為點擊操作。
// Generic click
await page.GetByRole(AriaRole.Button).ClickAsync();
// Double click
await page.GetByText("Item").DblClickAsync();
// Right click
await page.GetByText("Item").ClickAsync(new() { Button = MouseButton.Right });
// Shift + click
await page.GetByText("Item").ClickAsync(new() { Modifiers = new[] { KeyboardModifier.Shift } });
// Ctrl + click on Windows and Linux
// Meta + click on macOS
await page.GetByText("Item").ClickAsync(new() { Modifiers = new[] { KeyboardModifier.ControlOrMeta } });
// Hover over element
await page.GetByText("Item").HoverAsync();
// Click the top left corner
await page.GetByText("Item").ClickAsync(new() { position = new Position { X = 0, Y = 0 } });
在底層,這個方法以及其他指標相關方法會:
- 等待具有指定選擇器的元素出現在 DOM 中
- 等待元素變為可顯示狀態,即不為空、沒有
display:none
、沒有visibility:hidden
- 等待元素停止移動,例如等待 CSS 轉場效果完成
- 將元素滾動到視圖中
- 等待元素在操作點接收指標事件,例如等待元素不被其他元素遮蔽
- 如果在上述任何檢查過程中元素被分離,則重試
強制點擊
有時,應用程式使用非平凡的邏輯,其中懸停元素會用另一個攔截點擊的元素覆蓋它。這種行為與元素被覆蓋且點擊被分派到其他地方的錯誤無法區分。如果您知道正在發生這種情況,可以繞過可操作性檢查並強制點擊:
await page.GetByRole(AriaRole.Button).ClickAsync(new() { Force = true });
程式化點擊
如果您不想在真實條件下測試應用程式,而想要以任何可能的方式模擬點擊,可以透過使用 Locator.DispatchEventAsync()
在元素上簡單地分派點擊事件來觸發 HTMLElement.click()
行為:
await page.GetByRole(AriaRole.Button).DispatchEventAsync("click");
輸入字元
大多數情況下,您應該使用 Locator.FillAsync()
來輸入文字。請參閱上面的文字輸入部分。只有當頁面上有特殊的鍵盤處理時,才需要輸入字元。
使用 Locator.PressSequentiallyAsync()
逐個字元地輸入到欄位中,就像使用真實鍵盤的使用者一樣。
// Press keys one by one
await Page.Locator("#area").PressSequentiallyAsync("Hello World!");
此方法會發出所有必要的鍵盤事件,包括所有的 keydown
、keyup
、keypress
事件。您甚至可以指定按鍵之間的可選 delay
來模擬真實使用者行為。
按鍵和快捷鍵
// Hit Enter
await page.GetByText("Submit").PressAsync("Enter");
// Dispatch Control+Right
await page.GetByRole(AriaRole.Textbox).PressAsync("Control+ArrowRight");
// Press $ sign on keyboard
await page.GetByRole(AriaRole.Textbox).PressAsync("$");
Locator.PressAsync()
方法會聚焦選定的元素並產生單個按鍵操作。它接受在鍵盤事件的 keyboardEvent.key 屬性中發出的邏輯按鍵名稱:
Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape,
ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight,
ArrowUp, F1 - F12, Digit0 - Digit9, KeyA - KeyZ, etc.
- 您也可以指定想要產生的單個字元,例如
"a"
或"#"
。 - 也支援以下修飾快捷鍵:
Shift, Control, Alt, Meta
。
簡單版本會產生單個字元。此字元區分大小寫,因此 "a"
和 "A"
會產生不同的結果。
// <input id=name>
await page.Locator("#name").PressAsync("Shift+A");
// <input id=name>
await page.Locator("#name").PressAsync("Shift+ArrowLeft");
也支援 "Control+o"
或 "Control+Shift+T"
等快捷鍵。當與修飾鍵一起指定時,修飾鍵會被按下並保持,而後續的按鍵被按下。
請注意,您仍然需要在 Shift-A
中指定大寫 A
才能產生大寫字元。Shift-a
會產生小寫字元,就像您切換了 CapsLock
一樣。
上傳檔案
您可以使用 Locator.SetInputFilesAsync()
方法選擇要上傳的輸入檔案。它期望第一個參數指向類型為 "file"
的輸入元素。可以在陣列中傳遞多個檔案。如果某些檔案路徑是相對的,它們會相對於當前工作目錄解析。空陣列會清除選定的檔案。
// Select one file
await page.GetByLabel("Upload file").SetInputFilesAsync("myfile.pdf");
// Select multiple files
await page.GetByLabel("Upload files").SetInputFilesAsync(new[] { "file1.txt", "file12.txt" });
// Select a directory
await page.GetByLabel("Upload directory").SetInputFilesAsync("mydir");
// Remove all the selected files
await page.GetByLabel("Upload file").SetInputFilesAsync(new[] {});
// Upload buffer from memory
await page.GetByLabel("Upload file").SetInputFilesAsync(new FilePayload
{
Name = "file.txt",
MimeType = "text/plain",
Buffer = System.Text.Encoding.UTF8.GetBytes("this is a test"),
});
如果您手邊沒有輸入元素(它是動態建立的),您可以處理 Page.FileChooser
事件或在您的操作中使用對應的等待方法:
var fileChooser = page.RunAndWaitForFileChooserAsync(async () =>
{
await page.GetByLabel("Upload file").ClickAsync();
});
await fileChooser.SetFilesAsync("myfile.pdf");
聚焦元素
對於處理聚焦事件的動態頁面,您可以使用 Locator.FocusAsync()
聚焦指定的元素。
await page.GetByLabel("Password").FocusAsync();
拖放
您可以使用 Locator.DragToAsync()
執行拖放操作。此方法會:
- 懸停要拖動的元素。
- 按下滑鼠左鍵。
- 將滑鼠移動到將接收放置的元素。
- 釋放滑鼠左鍵。
await page.Locator("#item-to-be-dragged").DragToAsync(page.Locator("#item-to-drop-at"));
Dragging manually
如果您想要對拖放操作進行精確控制,請使用較低階的方法,如 Locator.HoverAsync()
、Mouse.DownAsync()
、Mouse.MoveAsync()
和 Mouse.UpAsync()
。
await page.Locator("#item-to-be-dragged").HoverAsync();
await page.Mouse.DownAsync();
await page.Locator("#item-to-drop-at").HoverAsync();
await page.Mouse.UpAsync();
如果您的頁面依賴於分派 dragover
事件,您需要至少兩次滑鼠移動才能在所有瀏覽器中觸發它。要可靠地發出第二次滑鼠移動,請重複您的 Mouse.MoveAsync()
或 Locator.HoverAsync()
兩次。操作序列應為:懸停拖動元素、滑鼠按下、懸停放置元素、第二次懸停放置元素、滑鼠釋放。
滾動
大多數情況下,Playwright 會在執行任何操作之前自動為您滾動。因此,您不需要明確地滾動。
// Scrolls automatically so that button is visible
await page.GetByRole(AriaRole.Button).ClickAsync();
然而,在極少數情況下,您可能需要手動滾動。例如,您可能想要強制「無限清單」載入更多元素,或者為特定螢幕截圖定位頁面。在這種情況下,最可靠的方法是找到您想要在底部顯示的元素,並將其滾動到視圖中。
// Scroll the footer into view, forcing an "infinite list" to load more content
await page.GetByText("Footer text").ScrollIntoViewIfNeededAsync();
如果您想要更精確地控制滾動,請使用 Mouse.WheelAsync()
或 Locator.EvaluateAsync()
:
// Position the mouse and scroll with the mouse wheel
await page.GetByTestId("scrolling-container").HoverAsync();
await page.Mouse.WheelAsync(0, 10);
// Alternatively, programmatically scroll a specific element
await page.GetByTestId("scrolling-container").EvaluateAsync("e => e.scrollTop += 100");