核心用法 / Core Usage

大多数时候 snapshot 拿到的 @ref 就够用了。但有时 ref 会失效、目标藏在隐藏状态里、或者你干脆不想先截一次 snapshot。 这一页讲另一套锁定目标的手段——find 语义定位器、原始 CSS、坐标点击——以及从结构化定位一路 升级到 eval 的阶梯。

什么时候不用 @ref

@ref 是最快的路径，但它建立在每次 snapshot 之上，页面一变就会过期。 当你遇到下面这些情况，直接用语义定位器或 CSS 更省事：

• 页面结构简单，为定位一个按钮单独跑一次 snapshot 不划算；
• refs 反复失效（导航、表单提交、动态重渲染之后）；
• 你已经知道元素的角色、可见文本、label 或一个稳定的选择器。

find 语义定位器

find 按语义而不是 ref 来锁定元素：角色 + 名字、可见文本、表单 label、placeholder、data-testid，或者「第一个 / 第 N 个」匹配。命中后直接跟一个动作动词 （click / fill / type / hover …）。 find label 不止匹配 <label> 元素——也会匹配 aria-label 和 aria-labelledby，所以只靠 ARIA 标注、没有 <label> 标签的图标按钮和自定义控件也能被找到。

$ chrome-use find role button click --name "Submit"
$ chrome-use find text "Sign In" click
$ chrome-use find text "Sign In" click --exact     # 仅精确匹配
$ chrome-use find label "Email" fill "user@test.com"
$ chrome-use find label "Close" click            # 命中只有 aria-label="Close" 的图标按钮
$ chrome-use find placeholder "Search" type "query"
$ chrome-use find testid "submit-btn" click
$ chrome-use find first ".card" click
$ chrome-use find nth 2 ".card" hover

原始 CSS 选择器

任何动作动词都能直接吃一个 CSS 选择器，无需先 find：

$ chrome-use click "#submit"
$ chrome-use fill "input[name=email]" "user@test.com"
$ chrome-use click "button.primary"

升级阶梯

定位一个元素有一条从便宜到万能的阶梯。按顺序往下走，别在某一档上死磕：

click 的自动滚动与 DOM 回退

click 会先把元素滚动进视口；如果坐标点击被遮挡，它会自动回退到 DOM 的 .click()。如果一次 click 报告成功却什么都没发生——典型的是 自动补全 / 菜单里那种一失焦就关掉的 <li>——用 DOM 点击模式重试那一下，或者干脆 eval：

# 用 DOM 点击模式重试这一下
$ AGENT_BROWSER_CLICK_MODE=dom chrome-use click @e3

# 或者直接用 JS 选中并点击那个条目
$ chrome-use eval "document.querySelector('#stubborn').click()"

按坐标点击

当你手上唯一的把手就是一个坐标时——canvas、来自截图的标记、没有稳定选择器的目标——直接点像素点：

$ chrome-use click 449 320            # 点视口坐标 (x y)
$ chrome-use click 449,320            # 同上，逗号写法
$ chrome-use click --coords 449,320   # 同上，显式 flag

find 触不到的地方

find 和 CSS 选择器都基于页面 DOM（querySelectorAll），所以对两类元素会报 「Element not found」——即使 snapshot -i 明明列出了它们（快照走的是 CDP 无障碍树，能穿透两者）， get text 也能读到它们：

• 闭合（closed）shadow root 里的元素；
• 跨源（cross-origin）iframe 里的元素。

下一步