操作

介绍

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 过渡完成
• 将元素滚动到视图中
• 等待它在操作点接收指针事件，例如，等待直到元素不被其他元素遮挡
• 如果元素在上述任何检查期间被分离，则重试

强制点击

有时，应用程序会使用复杂的逻辑，当悬停在元素上时，另一个元素会覆盖它并拦截点击。这种行为与元素被覆盖导致点击发送到其他位置的 bug 无法区分。如果你知道正在发生这种情况，可以绕过 可点击性 检查并强制执行点击。

await page.GetByRole(AriaRole.Button).ClickAsync(new() { Force = true });

程序化点击

如果你不想在真实条件下测试你的应用程序，并希望通过任何可能的方式模拟点击，你可以通过使用 Locator.DispatchEventAsync() 在元素上简单地分派一个 click 事件来触发 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() 方法选择要上传的输入文件。它期望第一个参数指向 type 为 "file" 的 input 元素。可以在数组中传递多个文件。如果某些文件路径是相对路径，它们将相对于当前工作目录解析。空数组会清除选定的文件。

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