可编程浏览器
ling.browser 打开一个受插件控制的浏览器窗口:打开网页、点击、输入、等待、执行脚本、截图、导出 PDF 或 Markdown。用法与 uTools 的 ubrowser 相同(名字去掉了 u)。需要 browser 权限。
用法
每次读取 ling.browser 都得到一个新的空队列;链式方法往队列里追加步骤,run() 时一次执行:
ts
const [title, markdown, instance] = await window.ling.browser
.goto('https://example.com')
.wait('h1')
.evaluate(() => document.querySelector('h1')?.textContent)
.markdown('main')
.run({ width: 1200, height: 800, show: false })run() 返回数组:按顺序包含会产出结果的步骤的结果(evaluate、markdown、screenshot、pdf、download、cookies),最后一项是实例信息 { id, url, title, width, height, x, y }。
任何一步失败时 run() reject,错误的 step(从 0 开始)和 method 指出失败的步骤,error.data 为已完成步骤的结果。
步骤
| 分类 | 步骤 |
|---|---|
| 导航 | goto(url, headers?, timeout?) 打开网址并等待加载完成;userAgent(ua);viewport(width, height);device({ userAgent, size }) |
| 鼠标 | click(选择器 | x, y?, button?)、dblclick、mousedown、mouseup、hover;可以传 CSS 选择器或坐标 |
| 键盘与输入 | press(key, ...modifiers) 派发按键;input(selector?, text) 模拟输入文字;value(selector, value) 直接设置表单值;check(selector, checked);focus(selector) |
| 滚动 | scroll(选择器 | x, y?) |
| 文件 | file(selector, 路径或字节) 设置文件输入框;drop(target, 路径或字节) 模拟拖入;paste(文字或图片 Data URL) |
| 等待 | wait(毫秒)、wait(选择器, { timeout?, visible? })、wait(函数, ...参数) 直到返回真值 |
| 条件 | when(选择器或函数) … endWhen():条件为假时跳过中间的步骤,可以嵌套 |
| 脚本与样式 | evaluate(函数, ...参数) 在页面里执行并返回结果(默认 60 秒超时);css(样式) 注入样式 |
| 产出 | markdown(selector?) 转成 Markdown;screenshot(选择器或区域?, 保存路径?);pdf(options?, 保存路径?);download(网址或函数, 保存路径?) |
| Cookie | cookies(名字或过滤条件?)、setCookies(...)、removeCookies(name)、clearCookies(url?) |
| 窗口 | show()、hide() |
传给 evaluate、wait、when 的函数会被序列化后在网页里执行,不能引用插件页面里的变量,需要的值通过参数传进去:
ts
.evaluate((selector) => [...document.querySelectorAll(selector)].map((el) => el.textContent), '.item')窗口选项
run(options) 新建实例时的窗口选项:show(默认 true;隐藏时照常执行)、width / height(默认 800 × 600)、x / y、center、title、resizable、alwaysOnTop、frame、transparent、backgroundColor、fullscreen 等,与 自定义窗口 基本相同。
复用实例
执行完后实例(窗口)留着,可以继续使用:
ts
const result = await window.ling.browser.goto(url).run({ show: false })
const { id } = result.at(-1)
// 在同一个窗口里继续
await window.ling.browser.click('#next').wait(500).run(id)| 方法 | 说明 |
|---|---|
getIdleBrowsers(): Promise<BrowserInstance[]> | 本插件空闲的实例 |
setBrowserProxy({ proxyRules, mode? }): Promise<void> | 设置代理(http://host:port 或 socks5://host:port),下一次 run 起生效;重启后失效 |
clearBrowserCache(): Promise<void> | 清除本插件浏览器的 Cookie、缓存、存储,并关闭全部实例 |
实例正在执行时再 run(id) 以 busy 失败。
说明
- 每个插件的浏览器数据(Cookie、登录状态)独立,和用户自己的浏览器、其他插件都不共享。插件结束运行时它的实例一起关闭。
- 浏览器以用户的网络身份访问网站,请遵守网站的使用条款。
- 模拟的点击、按键事件不是「可信事件」(
isTrusted为false),少数网站会识别。 file、drop读取插件目录外的文件需要fs.read;screenshot、pdf、download保存到插件目录外需要fs。