Playwright Locator 类 API

Locator 是 Playwright 的定位器对象，提供链式筛选、操作和断言。

Locator 操作方法

方法	说明
`locator.click(options?)`	点击元素
`locator.dblclick(options?)`	双击元素
`locator.hover(options?)`	鼠标悬停
`locator.fill(value, options?)`	清空并填入文本
`locator.type(text, options?)`	逐字符输入
`locator.clear(options?)`	清空输入框
`locator.check(options?)`	勾选复选框
`locator.uncheck(options?)`	取消勾选
`locator.setChecked(checked, options?)`	设置复选框状态
`locator.selectOption(values, options?)`	选择下拉框选项
`locator.setInputFiles(files, options?)`	设置文件上传
`locator.dragTo(target, options?)`	拖拽到目标元素
`locator.press(key, options?)`	按键
`locator.screenshot(options?)`	元素截图
`locator.scrollIntoViewIfNeeded(options?)`	滚动到可见

方法	说明
`locator.first()`	取第一个匹配元素
`locator.last()`	取最后一个匹配元素
`locator.nth(index)`	取第 n 个（从 0 开始）
`locator.filter(options?)`	按条件过滤（hasText、has、hasNot）
`locator.locator(selector)`	在匹配结果中继续查找
`locator.getByRole(role, options?)`	在匹配结果中按角色查找
`locator.getByText(text)`	在匹配结果中按文本查找
`locator.getByLabel(text)`	在匹配结果中按标签查找
`locator.and(locator)`	逻辑与（1.63+）
`locator.or(locator)`	逻辑或（1.63+）

方法	说明
`locator.textContent(options?)`	获取文本内容
`locator.innerHTML(options?)`	获取 innerHTML
`locator.innerText(options?)`	获取可见文本
`locator.inputValue(options?)`	获取 input 值
`locator.getAttribute(name)`	获取属性值
`locator.count()`	获取匹配数量
`locator.isVisible(options?)`	是否可见
`locator.isHidden(options?)`	是否隐藏
`locator.isEnabled(options?)`	是否启用
`locator.isDisabled(options?)`	是否禁用
`locator.isEditable(options?)`	是否可编辑
`locator.isChecked(options?)`	是否已勾选
`locator.boundingBox(options?)`	获取元素位置和大小

方法	说明
`locator.evaluate(fn, arg?, options?)`	在元素上下文执行 JS
`locator.evaluateAll(fn, arg?)`	在所有匹配元素上执行 JS
`locator.evaluateHandle(fn, arg?, options?)`	执行 JS 并返回 JSHandle

断言方法	说明
`expect(locator).toBeAttached()`	元素在 DOM 中
`expect(locator).toBeChecked()`	已勾选
`expect(locator).toBeDisabled()`	已禁用
`expect(locator).toBeEditable()`	可编辑
`expect(locator).toBeEmpty()`	内容为空
`expect(locator).toBeEnabled()`	已启用
`expect(locator).toBeFocused()`	已获得焦点
`expect(locator).toBeHidden()`	元素不可见
`expect(locator).toBeInViewport()`	元素在视口内
`expect(locator).toBeVisible()`	元素可见
`expect(locator).toContainText(text)`	包含文本
`expect(locator).toHaveAccessibleDescription(desc)`	有无障碍描述
`expect(locator).toHaveAccessibleName(name)`	有无障碍名称
`expect(locator).toHaveAttribute(name, value?)`	有 DOM 属性
`expect(locator).toHaveClass(className)`	有 CSS 类名
`expect(locator).toHaveCount(count)`	有指定数量
`expect(locator).toHaveCSS(name, value)`	有 CSS 属性值
`expect(locator).toHaveId(id)`	有 ID
`expect(locator).toHaveText(text)`	文本内容匹配
`expect(locator).toHaveValue(value)`	输入值匹配
`expect(locator).toHaveValues(values)`	多值匹配（多选）
`expect(locator).toHaveScreenshot(options?)`	元素截图对比

方法	说明
`frameLocator.getByRole(role, options?)`	按角色定位
`frameLocator.getByText(text)`	按文本定位
`frameLocator.getByLabel(text)`	按标签定位
`frameLocator.getByPlaceholder(text)`	按占位符定位
`frameLocator.getByTestId(id)`	按 testId 定位
`frameLocator.locator(selector)`	CSS/XPath 定位
`frameLocator.frameLocator(selector)`	嵌套 iframe 定位
`frameLocator.first()`	取第一个
`frameLocator.last()`	取最后一个
`frameLocator.nth(index)`	取第 n 个