跳到主要内容

Playwright for Python：Locator 类中文文档

Locator 是 Playwright 自动等待和重试机制的核心，用于在页面上定位元素，支持动态查找并适配元素状态变化。通过 page.locator() 方法可创建 Locator 实例，本文档详细介绍其方法、属性及使用示例。

一、核心方法（按功能分类）​

（一）元素定位与筛选​

1. all() - 获取所有匹配元素的 Locator 列表​

当 Locator 指向多个元素时，返回对应每个元素的 Locator 数组。

使用示例

# 同步模式
for li in page.get_by_role('listitem').all():
    li.click()

# 异步模式
for li in await page.get_by_role('listitem').all():
    await li.click()

注意事项

  • 不等待元素加载，立即返回页面中当前存在的元素。
  • 元素列表动态变化时可能返回不稳定结果；若列表稳定但动态加载，需先等待列表加载完成再调用。

返回值：List[Locator]

2. and_() - 组合两个 Locator（同时匹配）​

创建同时满足当前 Locator 和参数 Locator 条件的新 Locator。

使用示例

# 同步/异步通用
button = page.get_by_role("button").and_(page.get_by_title("Subscribe"))

参数：locator（Locator）- 需组合的另一个 Locator。

返回值：Locator

3. filter() - 筛选 Locator 结果​

通过文本、子元素等条件缩小 Locator 匹配范围，支持链式调用。

使用示例

# 同步模式
row_locator = page.locator("tr")
row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

# 异步模式
row_locator = page.locator("tr")
await row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

参数说明

  • has（Locator，可选）：筛选包含指定子 Locator 的元素。
  • has_not（Locator，可选，v1.33+）：筛选不包含指定子 Locator 的元素。
  • has_text（str | Pattern，可选）：筛选包含指定文本的元素（字符串匹配不区分大小写，支持子串）。
  • has_not_text（str | Pattern，可选，v1.33+）：筛选不包含指定文本的元素。
  • visible（bool，可选，v1.51+）：仅匹配可见或不可见元素。

返回值：Locator

4. nth() - 获取第 N 个匹配元素​

返回指向第 N 个匹配元素的 Locator（索引从 0 开始）。

使用示例

# 同步模式
banana = page.get_by_role("listitem").nth(2)

# 异步模式
banana = await page.get_by_role("listitem").nth(2)

参数：index（int）- 元素索引（0 为第一个）。

返回值：Locator

5. or_() - 组合两个 Locator（任一匹配）​

创建匹配两个 Locator 中任意一个的新 Locator。

使用示例

# 同步模式
new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
expect(new_email.or_(dialog).first).to_be_visible()
if dialog.is_visible():
    page.get_by_role("button", name="Dismiss").click()
new_email.click()

# 异步模式
new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
await expect(new_email.or_(dialog).first).to_be_visible()
if await dialog.is_visible():
    await page.get_by_role("button", name="Dismiss").click()
await new_email.click()

注意事项：若两个 Locator 同时匹配元素，可能触发严格模式冲突，可使用 first 取第一个匹配项。

参数：locator（Locator）- 可选的另一个 Locator。

返回值：Locator

（二）元素属性与文本获取​

1. all_inner_texts() - 获取所有匹配元素的 innerText​

返回所有匹配元素的 node.innerText 数组。

使用示例

# 同步模式
texts = page.get_by_role("link").all_inner_texts()

# 异步模式
texts = await page.get_by_role("link").all_inner_texts()

注意事项：断言文本推荐使用 expect(locator).to_have_text() 并设置 use_inner_text 选项，避免不稳定。

返回值：List[str]

2. all_text_contents() - 获取所有匹配元素的 textContent​

返回所有匹配元素的 node.textContent 数组。

使用示例

# 同步模式
texts = page.get_by_role("link").all_text_contents()

# 异步模式
texts = await page.get_by_role("link").all_text_contents()

注意事项：断言文本推荐使用 expect(locator).to_have_text()，避免不稳定。

返回值：List[str]

3. get_attribute() - 获取元素属性值​

返回匹配元素的指定属性值。

使用示例

# 同步/异步通用
attr_value = locator.get_attribute("href")

参数说明

  • name（str）：属性名。
  • timeout（float，可选）：超时时间（毫秒），默认 30000，传 0 禁用。

返回值：NoneType | str

4. inner_html() - 获取元素 innerHTML​

返回匹配元素的 element.innerHTML。

使用示例

# 同步模式
html = locator.inner_html()

# 异步模式
html = await locator.inner_html()

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：str

5. inner_text() - 获取元素 innerText​

返回匹配元素的 element.innerText。

使用示例

# 同步模式
text = locator.inner_text()

# 异步模式
text = await locator.inner_text()

注意事项：断言文本推荐使用 expect(locator).to_have_text() 并设置 use_inner_text 选项。

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：str

6. input_value() - 获取输入框值​

返回 <input>、<textarea> 或 <select> 元素的当前值。

使用示例

# 同步模式
value = page.get_by_role("textbox").input_value()

# 异步模式
value = await page.get_by_role("textbox").input_value()

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：str

7. text_content() - 获取元素 textContent​

返回匹配元素的 node.textContent。

使用示例

# 同步模式
content = locator.text_content()

# 异步模式
content = await locator.text_content()

注意事项：断言文本推荐使用 expect(locator).to_have_text()，避免不稳定。

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：NoneType | str

（三）元素状态判断​

1. is_checked() - 判断元素是否选中​

返回复选框或单选框的选中状态，非对应元素类型会抛出异常。

使用示例

# 同步模式
checked = page.get_by_role("checkbox").is_checked()

# 异步模式
checked = await page.get_by_role("checkbox").is_checked()

注意事项：断言选中状态推荐使用 expect(locator).to_be_checked()。

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：bool

2. is_disabled() - 判断元素是否禁用​

返回元素是否禁用（与 is_enabled() 相反）。

使用示例

# 同步模式
disabled = page.get_by_role("button").is_disabled()

# 异步模式
disabled = await page.get_by_role("button").is_disabled()

注意事项：断言禁用状态推荐使用 expect(locator).to_be_disabled()。

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：bool

3. is_editable() - 判断元素是否可编辑​

返回元素是否可编辑（支持 <input>、<textarea>、<select>、[contenteditable] 等）。

使用示例

# 同步模式
editable = page.get_by_role("textbox").is_editable()

# 异步模式
editable = await page.get_by_role("textbox").is_editable()

注意事项：断言可编辑状态推荐使用 expect(locator).to_be_editable()。

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：bool

4. is_enabled() - 判断元素是否启用​

返回元素是否启用（与 is_disabled() 相反）。

使用示例

# 同步模式
enabled = page.get_by_role("button").is_enabled()

# 异步模式
enabled = await page.get_by_role("button").is_enabled()

注意事项：断言启用状态推荐使用 expect(locator).to_be_enabled()。

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：bool

5. is_hidden() - 判断元素是否隐藏​

返回元素是否隐藏（与 is_visible() 相反）。

使用示例

# 同步模式
hidden = page.get_by_role("button").is_hidden()

# 异步模式
hidden = await page.get_by_role("button").is_hidden()

注意事项：断言隐藏状态推荐使用 expect(locator).to_be_hidden()，该方法不等待元素状态变化，立即返回结果。

返回值：bool

6. is_visible() - 判断元素是否可见​

返回元素是否可见。

使用示例

# 同步模式
visible = page.get_by_role("button").is_visible()

# 异步模式
visible = await page.get_by_role("button").is_visible()

注意事项：断言可见状态推荐使用 expect(locator).to_be_visible()，该方法不等待元素状态变化，立即返回结果。

返回值：bool

（四）元素交互操作​

1. blur() - 移除元素焦点​

为匹配元素触发失焦事件。

使用示例

# 同步模式
locator.blur()

# 异步模式
await locator.blur()

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：NoneType

2. check() - 选中复选框/单选框​

确保复选框或单选框处于选中状态。

使用示例

# 同步模式
page.get_by_role("checkbox").check()

# 异步模式
await page.get_by_role("checkbox").check()

参数说明

  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • position（Dict，可选）：点击位置（相对于元素内边距左上角的 x/y 坐标）。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。
  • trial（bool，可选）：仅执行可交互性检查，不执行实际操作，默认 false。

返回值：NoneType

3. clear() - 清空输入框​

清空 <input>、<textarea> 或 [contenteditable] 元素的内容。

使用示例

# 同步模式
page.get_by_role("textbox").clear()

# 异步模式
await page.get_by_role("textbox").clear()

参数说明

  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

4. click() - 点击元素​

为匹配元素执行点击操作，支持自定义点击位置、按键修饰符等。

使用示例

# 基础点击（同步）
page.get_by_role("button").click()

# 带修饰符的右键点击（异步）
await page.locator("canvas").click(
    button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
)

参数说明

  • button（"left" | "right" | "middle"，可选）：点击鼠标按键，默认 left。
  • click_count（int，可选）：点击次数，默认 1。
  • delay（float，可选）：鼠标按下与松开的间隔时间（毫秒），默认 0。
  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • modifiers（List，可选）：修饰键（Alt/Control/ControlOrMeta/Meta/Shift）。
  • position（Dict，可选）：点击位置（相对于元素内边距左上角的 x/y 坐标）。
  • steps（int，可选，v1.57+）：鼠标移动步数，默认 1。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。
  • trial（bool，可选）：仅执行可交互性检查，不执行实际操作，默认 false。

返回值：NoneType

5. dblclick() - 双击元素​

为匹配元素执行双击操作。

使用示例

# 同步模式
locator.dblclick()

# 异步模式
await locator.dblclick()

参数说明：与 click() 一致（无 click_count 参数）。

返回值：NoneType

6. dispatch_event() - 触发元素事件​

为匹配元素编程式触发指定 DOM 事件。

使用示例

# 基础触发（同步）
locator.dispatch_event("click")

# 带参数触发拖拽事件（异步）
data_transfer = await page.evaluate_handle("new DataTransfer()")
await locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

参数说明

  • type（str）：事件类型（如 "click"、"dragstart"）。
  • event_init（EvaluationArgument，可选）：事件初始化参数。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

7. drag_to() - 拖拽元素​

将源元素拖拽至目标元素或指定位置并释放。

使用示例

# 基础拖拽（同步）
source = page.locator("#source")
target = page.locator("#target")
source.drag_to(target)

# 自定义拖拽位置（异步）
await source.drag_to(
    target,
    source_position={"x": 34, "y": 7},
    target_position={"x": 10, "y": 20}
)

参数说明

  • target（Locator）：拖拽目标元素的 Locator。
  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • source_position（Dict，可选）：源元素上的拖拽起始位置。
  • steps（int，可选，v1.57+）：拖拽过程的鼠标移动步数，默认 1。
  • target_position（Dict，可选）：目标元素上的释放位置。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。
  • trial（bool，可选）：仅执行可交互性检查，不执行实际操作，默认 false。

返回值：NoneType

8. fill() - 填充输入框​

为 <input>、<textarea> 或 [contenteditable] 元素设置值。

使用示例

# 同步模式
page.get_by_role("textbox").fill("example value")

# 异步模式
await page.get_by_role("textbox").fill("example value")

参数说明

  • value（str）：要填充的文本值。
  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

9. focus() - 为元素设置焦点​

为匹配元素触发聚焦事件。

使用示例

# 同步模式
locator.focus()

# 异步模式
await locator.focus()

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：NoneType

10. hover() - 悬浮元素​

为匹配元素执行鼠标悬浮操作。

使用示例

# 同步模式
page.get_by_role("link").hover()

# 异步模式
await page.get_by_role("link").hover()

参数说明：与 click() 一致（无 button、click_count 参数）。

返回值：NoneType

11. press() - 按下按键​

聚焦元素后按下指定按键或组合键。

使用示例

# 同步模式
page.get_by_role("textbox").press("Backspace")

# 异步模式
await page.get_by_role("textbox").press("Control+Enter")

参数说明

  • key（str）：按键名称（如 "Backspace"、"ArrowLeft"）或组合键（如 "Control+o"）。
  • delay（float，可选）：按键按下与松开的间隔时间（毫秒），默认 0。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

12. press_sequentially() - 逐字符输入​

聚焦元素后逐字符输入文本，支持模拟用户输入速度。

使用示例

# 同步模式
locator.press_sequentially("hello")  # 即时输入
locator.press_sequentially("world", delay=100)  # 延迟 100ms 输入每个字符

# 异步模式
await locator.press_sequentially("hello")
await locator.press_sequentially("world", delay=100)

参数说明

  • text（str）：要输入的文本。
  • delay（float，可选）：字符间输入延迟（毫秒），默认 0。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

13. select_option() - 选择下拉框选项​

为 <select> 元素选择指定选项，支持单选和多选。

使用示例

# 单选（同步）
element.select_option("blue")

# 多选（异步）
await element.select_option(value=["red", "green", "blue"])

参数说明

  • element（ElementHandle | List[ElementHandle]，可选）：要选择的选项元素。
  • index（int | List[int]，可选）：按索引选择选项。
  • value（str | List[str]，可选）：按 value 属性选择选项。
  • label（str | List[str]，可选）：按标签文本选择选项。
  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：List[str] - 成功选中的选项 value 数组。

14. select_text() - 选中元素文本​

聚焦元素并选中其所有文本内容。

使用示例

# 同步模式
locator.select_text()

# 异步模式
await locator.select_text()

参数说明

  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

15. set_checked() - 设置复选框/单选框状态​

手动设置复选框或单选框的选中/未选中状态。

使用示例

# 同步模式
page.get_by_role("checkbox").set_checked(True)

# 异步模式
await page.get_by_role("checkbox").set_checked(True)

参数说明

  • checked（bool）：目标状态（True 为选中，False 为未选中）。
  • force（bool，可选）：是否跳过可交互性检查，默认 false。
  • position（Dict，可选）：点击位置（相对于元素内边距左上角的 x/y 坐标）。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。
  • trial（bool，可选）：仅执行可交互性检查，不执行实际操作，默认 false。

返回值：NoneType

16. set_input_files() - 上传文件​

为 <input type=file> 元素设置要上传的文件或目录。

使用示例

# 上传单个文件（同步）
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# 上传内存缓冲区文件（异步）
await page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ]
)

参数说明

  • files（Union[str, pathlib.Path] | List | Dict | List[Dict]）：文件路径、目录路径或包含文件名、类型、缓冲区的字典。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

17. tap() - 模拟触摸点击​

为匹配元素执行触摸tap手势（需开启 hasTouch 选项）。

使用示例

# 同步模式
locator.tap()

# 异步模式
await locator.tap()

参数说明：与 click() 一致（无 button、click_count 参数）。

返回值：NoneType

18. uncheck() - 取消选中复选框/单选框​

确保复选框或单选框处于未选中状态。

使用示例

# 同步模式
page.get_by_role("checkbox").uncheck()

# 异步模式
await page.get_by_role("checkbox").uncheck()

参数说明：与 check() 一致。

返回值：NoneType

（五）其他核心方法​

1. aria_snapshot() - 捕获 ARIA 快照​

捕获元素的 ARIA 状态快照，用于断言元素状态。

使用示例

# 同步模式
snapshot = page.get_by_role("link").aria_snapshot()

# 异步模式
snapshot = await page.get_by_role("link").aria_snapshot()

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：str - YAML 格式的 ARIA 快照字符串。

2. bounding_box() - 获取元素边界框​

返回元素的边界框信息（相对于主框架视口），元素不可见时返回 null。

使用示例

# 同步模式
box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

# 异步模式
box = await page.get_by_role("button").bounding_box()
await page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：NoneType | Dict - 包含 x、y、width、height 字段的字典。

3. count() - 获取匹配元素数量​

返回当前匹配 Locator 的元素个数。

使用示例

# 同步模式
count = page.get_by_role("listitem").count()

# 异步模式
count = await page.get_by_role("listitem").count()

注意事项：断言元素数量推荐使用 expect(locator).to_have_count()。

返回值：int

4. describe() - 为 Locator 添加描述​

为 Locator 设置描述，用于跟踪日志和测试报告。

使用示例

# 同步模式
button = page.get_by_test_id("btn-sub").describe("Subscribe button")
button.click()

# 异步模式
button = page.get_by_test_id("btn-sub").describe("Subscribe button")
await button.click()

参数：description（str）- Locator 的描述文本。

返回值：Locator

5. evaluate() - 执行 JavaScript 代码​

在浏览器上下文执行 JavaScript 代码，将匹配元素作为参数传入。

使用示例

# 同步模式
result = page.get_by_testid("myId").evaluate(
    "(element, [x, y]) => element.textContent + ' ' + x * y", [7, 8]
)

# 异步模式
result = await page.get_by_testid("myId").evaluate(
    "(element, [x, y]) => element.textContent + ' ' + x * y", [7, 8]
)

参数说明

  • expression（str）：要执行的 JavaScript 表达式或函数。
  • arg（EvaluationArgument，可选）：传递给表达式的参数。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：Dict - 表达式执行结果。

6. evaluate_all() - 为所有匹配元素执行 JavaScript​

在浏览器上下文执行 JavaScript 代码，将所有匹配元素数组作为参数传入。

使用示例

# 同步模式
locator = page.locator("div")
more_than_ten = locator.evaluate_all("(divs, min) => divs.length > min", 10)

# 异步模式
locator = page.locator("div")
more_than_ten = await locator.evaluate_all("(divs, min) => divs.length > min", 10)

参数说明：与 evaluate() 一致。

返回值：Dict - 表达式执行结果。

7. evaluate_handle() - 执行 JavaScript 并返回 JSHandle​

执行 JavaScript 代码，返回包装执行结果的 JSHandle 对象。

使用示例

# 同步模式
handle = locator.evaluate_handle("element => element.scrollHeight")

# 异步模式
handle = await locator.evaluate_handle("element => element.scrollHeight")

参数说明：与 evaluate() 一致。

返回值：JSHandle - 包装执行结果的对象。

8. frame_locator() - 创建 Frame Locator​

为 iframe 元素创建 FrameLocator，用于定位 iframe 内的元素。

使用示例

# 同步模式
locator = page.frame_locator("iframe").get_by_text("Submit")
locator.click()

# 异步模式
locator = page.frame_locator("iframe").get_by_text("Submit")
await locator.click()

参数：selector（str）- iframe 的选择器。

返回值：FrameLocator

9. highlight() - 高亮元素​

在页面上高亮显示匹配元素（仅用于调试，不要提交到生产代码）。

使用示例

# 同步/异步通用
locator.highlight()

返回值：NoneType

10. screenshot() - 元素截图​

捕获匹配元素的截图，支持保存到文件或返回缓冲区。

使用示例

# 保存截图到文件（同步）
page.get_by_role("link").screenshot(animations="disabled", path="link.png")

# 返回截图缓冲区（异步）
buffer = await page.get_by_role("link").screenshot()

参数说明

  • animations（"disabled" | "allow"，可选）：是否禁用动画，默认 allow。
  • caret（"hide" | "initial"，可选）：是否隐藏文本光标，默认 hide。
  • mask（List[Locator]，可选）：需要遮挡的元素列表。
  • mask_color（str，可选，v1.35+）：遮挡框颜色（CSS 格式），默认 #FF00FF。
  • omit_background（bool，可选）：是否隐藏背景（仅 PNG 支持透明），默认 false。
  • path（Union[str, pathlib.Path]，可选）：截图保存路径。
  • quality（int，可选）：图片质量（0-100，仅 JPEG 支持）。
  • scale（"css" | "device"，可选）：截图缩放模式，默认 device。
  • style（str，可选，v1.41+）：截图时应用的样式表。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。
  • type（"png" | "jpeg"，可选）：截图格式，默认 png。

返回值：bytes - 截图的二进制缓冲区。

11. scroll_into_view_if_needed() - 滚动元素到可视区域​

将元素滚动到视口内（仅当元素未完全可见时执行）。

使用示例

# 同步模式
locator.scroll_into_view_if_needed()

# 异步模式
await locator.scroll_into_view_if_needed()

参数：timeout（float，可选）- 超时时间（毫秒），默认 30000。

返回值：NoneType

12. wait_for() - 等待元素状态​

等待元素满足指定状态（如可见、存在），超时未满足则抛出异常。

使用示例

# 同步模式
order_sent = page.locator("#order-sent")
order_sent.wait_for()

# 异步模式
order_sent = page.locator("#order-sent")
await order_sent.wait_for()

参数说明

  • state（"attached" | "detached" | "visible" | "hidden"，可选）：目标状态，默认 visible。
  • timeout（float，可选）：超时时间（毫秒），默认 30000。

返回值：NoneType

（六）元素定位快捷方法​

1. get_by_alt_text() - 通过 alt 文本定位​

根据元素的 alt 属性定位元素（常用于图片）。

使用示例

# 同步模式
page.get_by_alt_text("Playwright logo").click()

# 异步模式
await page.get_by_alt_text("Playwright logo").click()

参数说明

  • text（str | Pattern）：alt 文本或正则表达式。
  • exact（bool，可选）：是否精确匹配（区分大小写、全字符匹配），默认 false。

返回值：Locator

2. get_by_label() - 通过标签定位​

根据关联的 <label> 文本、aria-labelledby 或 aria-label 定位输入元素。

使用示例

# 同步模式
page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

# 异步模式
await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")

参数说明：与 get_by_alt_text() 一致。

返回值：Locator

3. get_by_placeholder() - 通过占位符定位​

根据 input 元素的 placeholder 属性定位。

使用示例

# 同步模式
page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

# 异步模式
await page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

参数说明：与 get_by_alt_text() 一致。

返回值：Locator

4. get_by_role() - 通过 ARIA 角色定位​

根据元素的 ARIA 角色、属性和可访问名称定位元素。

使用示例

# 同步模式
expect(page.get_by_role("heading", name="Sign up")).to_be_visible()
page.get_by_role("checkbox", name="Subscribe").check()

# 异步模式
await expect(page.get_by_role("heading", name="Sign up")).to_be_visible()
await page.get_by_role("checkbox", name="Subscribe").check()

参数说明

  • role（str，必填）：ARIA 角色（如 "button"、"checkbox"、"heading"）。
  • checked（bool，可选）：匹配 aria-checked 状态。
  • disabled（bool，可选）：匹配 aria-disabled 或 disabled 状态。
  • exact（bool，可选，v1.28+）：名称是否精确匹配，默认 false。
  • expanded（bool，可选）：匹配 aria-expanded 状态。
  • include_hidden（bool，可选）：是否包含隐藏元素，默认 false。
  • level（int，可选）：角色层级（如 heading 的 1-6 级）。
  • name（str | Pattern，可选）：可访问名称（支持子串、正则）。
  • pressed（bool，可选）：匹配 aria-pressed 状态。
  • selected（bool，可选）：匹配 aria-selected 状态。

返回值：Locator

5. get_by_test_id() - 通过测试 ID 定位​

根据测试 ID 属性定位元素（默认使用 data-testid）。

使用示例

# 同步模式
page.get_by_test_id("directions").click()

# 异步模式
await page.get_by_test_id("directions").click()

参数：test_id（str | Pattern）- 测试 ID 或正则表达式。

返回值：Locator

6. get_by_text() - 通过文本定位​

根据元素包含的文本定位元素。

使用示例

# 同步模式
page.get_by_text("world").click()  # 匹配包含 "world" 的元素
page.get_by_text("Hello", exact=True).click()  # 精确匹配 "Hello"

# 异步模式
await page.get_by_text(re.compile("^hello$", re.IGNORECASE)).click()  # 正则匹配

参数说明：与 get_by_alt_text() 一致。

返回值：Locator

7. get_by_title() - 通过 title 属性定位​

根据元素的 title 属性定位元素。

使用示例

# 同步模式
expect(page.get_by_title("Issues count")).to_have_text("25 issues")

# 异步模式
await expect(page.get_by_title("Issues count")).to_have_text("25 issues")

参数说明：与 get_by_alt_text() 一致。

返回值：Locator

二、属性​

1. content_frame - 获取 FrameLocator​

返回指向当前元素（iframe）的 FrameLocator 对象。

使用示例

# 同步模式
locator = page.locator("iframe[name=\"embedded\"]")
frame_locator = locator.content_frame
frame_locator.get_by_role("button").click()

# 异步模式
locator = page.locator("iframe[name=\"embedded\"]")
frame_locator = locator.content_frame
await frame_locator.get_by_role("button").click()

返回值：FrameLocator

2. description - 获取 Locator 描述​

返回通过 describe() 方法设置的描述，未设置则返回 None。

使用示例

# 同步模式
button = page.get_by_role("button").describe("Subscribe button")
print(button.description)  # 输出 "Subscribe button"

# 异步模式
input = page.get_by_role("textbox")
print(input.description)  # 输出 None

返回值：NoneType | str

3. first - 获取第一个匹配元素​

返回指向第一个匹配元素的 Locator。

使用示例

# 同步/异步通用
first_item = page.get_by_role("listitem").first

返回值：Locator

4. last - 获取最后一个匹配元素​

返回指向最后一个匹配元素的 Locator。

使用示例

# 同步模式
last_item = page.get_by_role("listitem").last

# 异步模式
last_item = await page.get_by_role("listitem").last

返回值：Locator

5. page - 获取所属页面​

返回当前 Locator 所属的 Page 对象。

使用示例

# 同步/异步通用
page = locator.page

返回值：Page

三、废弃方法（不推荐使用）​

1. element_handle()​

解析 Locator 到第一个匹配的 ElementHandle，存在竞争风险，推荐使用 Locator 原生方法。

2. element_handles()​

解析 Locator 到所有匹配的 ElementHandle 列表，存在竞争风险，推荐使用 all() 方法。

3. type()​

已废弃，推荐使用 fill() 或 press_sequentially() 替代。