跳到主要內容

動作

簡介​

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

手動拖曳​

如果您想要精確控制拖曳操作，請使用較低層級的方法，例如 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");