Playwright Python Locator API

📚 Playwright Python Locator API 速查手册#

按照官方文档原有分类整理，包含方法名、用途说明、调用格式、单句示例。

📂 集合操作#

方法	说明	调用格式	示例
`all()`	返回匹配元素数组	`locator.all()`	`for li in page.get_by_role('listitem').all(): li.click()`
`all_inner_texts()`	所有元素的 `innerText` 数组	`locator.all_inner_texts()`	`texts = links.all_inner_texts()`
`all_text_contents()`	所有元素的 `textContent` 数组	`locator.all_text_contents()`	`texts = links.all_text_contents()`

🔍 组合 / 过滤#

方法	说明	调用格式	示例
`and_(locator)`	同时匹配两个 Locator	`locator.and_(other_locator)`	`btn = page.get_by_role("button").and_(page.get_by_title("OK"))`
`or_(locator)`	匹配任意一个 Locator	`locator.or_(other_locator)`	`loc = a.or_(b)`
`filter(...)`	按条件过滤	`locator.filter(has_text="foo")`	`rows.filter(has=btn)`
`nth(index)`	第 n 个元素（从 0 开始）	`locator.nth(2)`	`third = items.nth(2)`

🧾 元素信息#

方法	说明	调用格式	示例
`aria_snapshot()`	获取 ARIA 快照	`locator.aria_snapshot()`	`snap = el.aria_snapshot()`
`bounding_box()`	获取元素位置尺寸	`locator.bounding_box()`	`box = btn.bounding_box()`
`get_attribute(name)`	获取属性值	`locator.get_attribute("href")`	`href = link.get_attribute("href")`
`inner_html()`	获取 `innerHTML`	`locator.inner_html()`	`html = el.inner_html()`
`inner_text()`	获取 `innerText`	`locator.inner_text()`	`text = el.inner_text()`
`text_content()`	获取 `textContent`	`locator.text_content()`	`txt = el.text_content()`
`input_value()`	获取输入值	`locator.input_value()`	`val = input.input_value()`
`count()`	匹配元素数量	`locator.count()`	`num = items.count()`

✅ 状态判断#

方法	说明	调用格式	示例
`is_visible()` / `is_hidden()`	可见 / 隐藏状态	`locator.is_visible()`	`if el.is_visible(): ...`
`is_checked()`	是否选中	`locator.is_checked()`	`if cb.is_checked(): ...`
`is_disabled()` / `is_enabled()`	禁用 / 启用状态	`locator.is_disabled()`	`if btn.is_enabled(): ...`
`is_editable()`	是否可编辑	`locator.is_editable()`	`if input.is_editable(): ...`

🎯 操作动作#

方法	说明	调用格式	示例
`click()` / `dblclick()`	单击 / 双击	`locator.click()`	`btn.click()`
`tap()`	触摸点击	`locator.tap()`	`btn.tap()`
`hover()`	鼠标悬停	`locator.hover()`	`link.hover()`
`press(key)`	按键	`locator.press("Enter")`	`input.press("Enter")`
`press_sequentially(text)`	模拟逐字键入	`locator.press_sequentially("abc")`	`input.press_sequentially("hello")`
`fill(value)`	填充	`locator.fill("text")`	`username.fill("john")`
`clear()`	清空	`locator.clear()`	`search.clear()`
`check()` / `uncheck()`	勾选 / 取消	`locator.check()`	`cb.uncheck()`
`set_checked(bool)`	设选中状态	`locator.set_checked(True)`	`cb.set_checked(False)`
`set_input_files(...)`	上传文件	`locator.set_input_files("file.txt")`	`upload.set_input_files(["a.txt","b.txt"])`
`select_option(...)`	选择下拉项	`locator.select_option("value")`	`sel.select_option(label="blue")`
`select_text()`	选中文本	`locator.select_text()`	`input.select_text()`
`drag_to(target)`	拖拽到目标	`locator.drag_to(target)`	`src.drag_to(dst)`
`scroll_into_view_if_needed()`	滚动到可见位置	`locator.scroll_into_view_if_needed()`	`el.scroll_into_view_if_needed()`
`screenshot(...)`	元素截图	`locator.screenshot(path="img.png")`	`img = el.screenshot()`
`focus()` / `blur()`	聚焦 / 失焦	`locator.focus()`	`input.blur()`

⚡ 事件#

方法	说明	调用格式	示例
`dispatch_event(type, init)`	触发事件	`locator.dispatch_event("click")`	`el.dispatch_event("mouseover")`

🧭 定位扩展#

方法	说明	调用格式	示例
`locator(selector)`	在当前结果中查找	`locator.locator("span")`	`row.locator(".cell")`
`frame_locator(selector)`	进入 iframe	`page.frame_locator("iframe")`	`frm.locator("button").click()`

🛠 评估执行#

方法	说明	调用格式	示例
`evaluate(js, arg)`	在浏览器执行 JS	`locator.evaluate("el=>el.textContent")`	`txt = el.evaluate("e=>e.id")`
`evaluate_all(js, arg)`	所有匹配元素执行 JS	`locator.evaluate_all("(els)=>els.length")`	`count = loc.evaluate_all(...)`
`evaluate_handle(js, arg)`	返回 JSHandle	`locator.evaluate_handle("el=>el")`	`handle = el.evaluate_handle(...)`

⏳ 等待#

方法	说明	调用格式	示例
`wait_for(state="visible")`	等待状态变化	`locator.wait_for(state="hidden")`	`loading.wait_for(state="detached")`

🐞 调试辅助#

方法	说明	调用格式	示例
`highlight()`	高亮显示	`locator.highlight()`	`btn.highlight()`
`describe(desc)`	添加定位器描述	`locator.describe("desc")`	`btn.describe("提交按钮")`

🎯 特定条件定位#

方法	说明	调用格式	示例
`get_by_alt_text(text)`	按图片 alt	`page.get_by_alt_text("logo")`	`logo.click()`
`get_by_label(text)`	按 label	`page.get_by_label("Username")`	`user.fill("john")`
`get_by_placeholder(text)`	按 placeholder	`page.get_by_placeholder("email")`	`email.fill("me@x.com")`
`get_by_role(role, name=...)`	按 ARIA role	`page.get_by_role("button", name="Submit")`	`submit.click()`
`get_by_test_id(id)`	按 data-testid	`page.get_by_test_id("id")`	`btn.click()`
`get_by_text(text)`	按文本内容	`page.get_by_text("Hello")`	`div.get_by_text("world")`
`get_by_title(text)`	按 title 属性	`page.get_by_title("Issues count")`	`count_el.get_by_title("数量")`

On This Page

📚 Playwright Python Locator API 速查手册
📂 集合操作
🔍 组合 / 过滤
🧾 元素信息
✅ 状态判断
🎯 操作动作
⚡ 事件
🧭 定位扩展
🛠 评估执行
⏳ 等待
🐞 调试辅助
🎯 特定条件定位