Appearance
ubrowser
uTools browser 简称 ubrowser,是根据 uTools 的特性,量身打造的一个可编程浏览器。利用 ubrowser 可以轻而易举连接一切互联网服务,且与 uTools 完美结合。
小技巧
ubrowser 拥有优雅的链式调用接口,可以用口语化的数行代码,实现一系列匪夷所思的操作。例如:
- RPA 自动化
- 网页内容魔改
- 网页内容抓取
ubrowser.goto(url[, headers][, timeout])
打开一个 ubrowser 窗口,并跳转到指定网页
类型定义
ts
function goto(url: string, headers?: Record<string, string>, timeout?: number): UBrowser;
url
: 要跳转的网页地址headers
: 请求头timeout
: 超时时间,单位毫秒
ubrowser.useragent(ua)
设置用户代理(User-Agent)
类型定义
ts
function useragent(ua: string): UBrowser;
ua
: User-Agent 字符串
ubrowser.viewport(width, height)
设置浏览器视窗大小
类型定义
ts
function viewport(width: number, height: number): UBrowser;
width
: 视窗宽度height
: 视窗高度
ubrowser.hide()
隐藏 ubrowser 窗口
类型定义
ts
function hide(): UBrowser;
ubrowser.show()
显示 ubrowser 窗口
类型定义
ts
function show(): UBrowser;
网页操作
ubrowser 支持网页内容魔改,即在网页加载前对网页内容进行修改,例如添加自定义 CSS、JavaScript 等。
ubrowser.css(css)
添加自定义 CSS
类型定义
ts
function css(css: string): UBrowser;
css
: 自定义 CSS
ubrowser.evaluate(func[, params])
在网页中执行自定义 JS 代码
类型定义
ts
function evaluate(func: Function, params?: any[]): UBrowser;
func
: 网页内执行的 JS 函数,函数若有返回值,则会在run
Promise 结果返回params
: 传递给func
的参数
ubrowser.press(key[, modifiers])
模拟键盘按键
类型定义
ts
function press(key: string, ...modifiers: string[]): UBrowser;
key
: 要模拟的按键modifiers
: 要模拟的修饰键,一般为shift
、ctrl
、alt
、meta
ubrowser.click(selector)
执行点击操作
类型定义
ts
function click(selector: string): UBrowser;
selector
: CSS 选择器或 XPath 选择器
ubrowser.mousedown(selector)
执行鼠标按下操作
类型定义
ts
function mousedown(selector: string): UBrowser;
selector
: CSS 选择器或 XPath 选择器
ubrowser.mouseup(selector)
执行鼠标抬起操作
类型定义
ts
function mouseup(selector: string): UBrowser;
selector
: CSS 选择器或 XPath 选择器
ubrowser.file(selector, payload)
对网页中的 input 元素设置文件
类型定义
ts
function file(selector: string, payload: string | string[] | Buffer): UBrowser;
selector
元素必须是可选择文件的输入元素input[type=file]
payload
可以是文件路径、文件路径集合以及文件 Buffer
ubrowser.value(selector, payload)
对网页中的 input 元素设置值
类型定义
ts
function value(selector: string, payload: string): UBrowser;
selector
必须是input
、textarea
、select
元素,使用 CSS 选择器或 XPath 选择器payload
将会设置到value
属性上
ubrowser.check(selector, checked)
执行勾选操作
类型定义
ts
function check(selector: string, checked: boolean): UBrowser;
selector
必须是checkbox
、radio
元素,使用 CSS 选择器或 XPath 选择器checked
为true
时,勾选,否则取消勾选
ubrowser.focus(selector)
执行聚焦操作
类型定义
ts
function focus(selector: string): UBrowser;
selector
: CSS 选择器或 XPath 选择器
ubrowser.scroll(selector)
执行滚动操作
类型定义
ts
function scroll(selector: string): UBrowser;
function scroll(y: number): UBrowser;
function scroll(x: number, y: number): UBrowser;
selector
为string
时,滚动到指定元素, 使用 CSS 选择器或 XPath 选择器selector
为number
时,只有一个参数表示 y 轴,滚动到纵向指定位置。两个参数则表示 x 轴。- 传递
x
和y
,滚动到指定位置
ubrowser.download(url[, savePath])
执行下载操作
类型定义
ts
function download(url: string, savePath?: string): UBrowser;
function download(func: (...params: any[]) => string, savePath: string | null, ...params: any[]): UBrowser;
url
待下载的资源 URLsavePath
指定下载路径,不传则下载到默认路径func
网页内执行的 JS 函数, 函数可返回资源 URL,再根据返回 URL 下载资源params
传递给func
的参数
ubrowser.paste(text)
先复制再执行粘贴操作
类型定义
ts
function paste(text: string): UBrowser;
text
: 要粘贴的内容,支持普通文本跟图像 Base64 Data URL
ubrowser.screenshot(target[, savePath])
对网页进行截屏并保持到指定路径,将会保存成为 png 格式
类型定义
ts
function screenshot(target?: string | Rect, savePath?: string ): UBrowser;
- 没有参数时,整个网页窗口截屏
- 当
target
为string
时,target
为选择器。可以传入一个Rect
对象,表示截取指定区域。 savePath
保存路径,没有传递savePath
的时,默认存储在临时目录。
Rect
类型定义
ts
interface Rect {
x: number;
y: number;
width: number;
height: number;
}
ubrowser.pdf(options[, savePath])
将网页保存为 PDF
类型定义
ts
function pdf(options: PdfOptions, savePath?: string): UBrowser;
PdfOptions
参考 ElectronPrintToPDFOptions
savePath
保存路径,没有传递savePath
的时,默认存储在临时目录。
ubrowser.device(options)
模拟移动设备
类型定义
ts
function device(options: DeviceOptions): UBrowser;
options
模拟设备信息
DeviceOptions
类型定义
ts
interface DeviceOptions {
userAgent: string;
size: {
width: number;
height: number;
};
}
ubrowser.wait(ms)
执行等待操作
类型定义
ts
// 等待时间
function wait(ms: number): this;
// 等待元素出现
function wait(selector: string, timeout?: number): this;
// 等待函数返回 true
function wait(func: (...params: any[]) => boolean, timeout?: number, ...params: any[]): this;
ms
等待指定毫秒数selector
等待元素出现,使用 CSS 选择器或 XPath 选择器timeout
等待超时时间,默认为 60000 ms (60秒)func
网页内执行的 JS 函数, 返回true
等待结束params
传递给func
的参数
ubrowser.when(selector)
条件判断
类型定义
ts
// 判断存在元素
function when(selector: string): UBrowser;
// 判断函数结果
function when(func: ((...params: any[]) => boolean), ...params: any[]): UBrowser;
selector
判断是否存在元素,使用 CSS 选择器或 XPath 选择器func
网页内执行的 JS 函数, 判断函数返回的结果params
传递给func
的参数
ubrowser.end()
结束上一个 when
类型定义
ts
function end(): UBrowser;
ubrowser.devTools([mode])
打开 ubrowser 开发者工具。
类型定义
ts
function devTools(mode?: string): void;
mode
: 可选值 'right' | 'bottom' | 'undocked' | 'detach' ,默认 'detach'
ubrowser.cookies([name])
获取 ubrowser cookie
类型定义
ts
// 在当前 url 根据名称获取 cookie, 为空获取当前 url 全部 cookie
function cookies(name?: string): UBrowser;
// 根据条件获取 Cookie
function cookies(filter: CookieFilter): UBrowser;
name
cookie 名称filter
过滤对象
CookieFilter
类型定义
ts
interface CookieFilter {
url ?: string;
name?: string;
domain?: string;
path?: string;
secure?: boolean;
session?: boolean;
httpOnly?: boolean;
}
url
检索与 url 相关的 cookie。 空意味着检索所有 URL 的 cookie 。name
按名称筛选 cookie。domain
检索与域名或者 domain 子域名匹配的cookie。path
检索路径与 path 匹配的 cookie。secure
通过其 Secure 属性筛选 cookie。session
筛选出 session 内可用或持久性 cookie。httpOnly
通过其 httpOnly 属性筛选 cookie。
ubrowser.setCookies
设置 ubrowser 的 cookie
类型定义
ts
function setCookies(name: string, value: string): UBrowser;
function setCookies(cookies: { name: string, value: string }[]): UBrowser;
name
cookie 名称value
cookie 值cookies
cookie 名称和值对象的集合
ubrowser.removeCookies(name)
删除 ubrowser 的 cookie
类型定义
ts
function removeCookies(name: string): UBrowser;
name
cookie 名称
ubrowser.clearCookies([url])
清空 ubrowser 的 cookie 信息。
类型定义
ts
function clearCookies(url?: string): UBrowser;
url
: 根据 url 清除 cookie,clearCookies
在goto
函数之前调用时url
不能为空。在goto
之后调用则清空当前 url 的 cookie
ubrowser.run()
开始运行 ubrowser 实例,并返回执行结果
类型定义
ts
function run(ubrowserId?: number, options?: UBrowserOptions): Promise<[...any, UBrowserInstance]>;
ubrowserId
一般以下两种形式获取:ubrowser.run
返回的UBrowserInstance
的id
属性(ubrowser 窗口仍在显示时)。utools.getIdleUBrowser
返回的UBrowserInstance
的id
属性。
run
返回将会返回一个包含数组的 Promise 对象,数组的最后一个元素是当前未关闭窗口的 UBrowser 实例,其余的元素则是运行过程中,其他 ubrowser 方法的返回值,比如evaluate
、cookies
等。
UBrowserOptions
类型定义
ts
interface UBrowserOptions {
show?: boolean;
width?: number;
height?: number;
x?: number;
y?: number;
center?: boolean;
minWidth?: number;
minHeight?: number;
maxWidth?: number;
maxHeight?: number;
resizable?: boolean;
movable?: boolean;
minimizable?: boolean;
maximizable?: boolean;
alwaysOnTop?: boolean;
fullscreen?: boolean;
fullscreenable?: boolean;
enableLargerThanScreen?: boolean;
opacity?: number;
}
show
: 是否显示浏览器窗口width
: 浏览器窗口宽度,默认800
height
: 浏览器窗口高度,默认600
x
: 浏览器窗口位置 x 坐标y
: 浏览器窗口位置 y 坐标center
: 浏览器窗口是否居中minWidth
: 浏览器窗口最小宽度,默认0
minHeight
: 浏览器窗口最小高度,默认0
maxWidth
: 浏览器窗口最大宽度,默认无限制maxHeight
: 浏览器窗口最大高度,默认无限制resizable
: 浏览器窗口是否可缩放,默认true
movable
: 浏览器窗口是否可移动,默认true
minimizable
: 浏览器窗口是否可最小化,默认true
maximizable
: 浏览器窗口是否可最大化,默认true
alwaysOnTop
: 浏览器窗口是否置顶,默认false
fullscreen
: 浏览器窗口是否全屏,默认false
fullscreenable
: 浏览器窗口是否可全屏,默认true
enableLargerThanScreen
: 浏览器窗口是否可超出屏幕,默认false
,仅在 macOS 下生效opacity
: 浏览器窗口透明度,默认1
,支持0
-1
之间的值,仅在 macOS 跟 Windows 下生效
UBrowserInstance
类型定义
ts
interface UBrowserInstance {
id: string;
url: string;
title: string;
width: number;
height: number;
x: number;
y: number;
}
示例代码
js
const address = '福州烟台山'
// 在地图上显示地址位置
utools.ubrowser
// 打开百度地图站点
.goto('https://map.baidu.com')
// 等待出现搜索框
.wait('#sole-input')
// 搜索框获得焦点
.focus('#sole-input')
// 地址搜索框输入地址
.value('#sole-input', address)
// 等待 300 毫秒
.wait(300)
// 按下回车
.press('enter')
// 开始运行
.run({ width: 1200, height: 800 })
js
const expressNo = 'YT8933937901850'
// 快递 100 查询快递单号
utools.ubrowser
// 打开快递 100
.goto('https://www.kuaidi100.com/')
// 等待输入框
.wait('#input')
// 滚动到合适位置
.scroll(0, 450)
// 输入快递单号
.value('#input', expressNo)
// 点击查询
.click('#query')
// 开始运行(窗口大小 1280x720)
.run({ width: 1280, height: 720 })
js
const image = '/path/to/test.png'
// 图片自动去背景
utools.ubrowser
// 清空 cookies
.clearCookies('https://www.remove.bg')
// 前往站点
.goto('https://www.remove.bg/zh/upload')
// 等界面加载出现上传按钮
.wait('//div[text() = "上传图片"]')
// 粘贴图片
.paste(image)
// 处理中,等待出现下载按钮
.wait('//div[text() = "下载"]')
// 再等待 3 秒,等结果返回
.wait(3000)
// 下载图片
.download(function () {
document.evaluate('//div[text() = "下载"]',document,null,XPathResult.FIRST_ORDERED_NODE_TYPE,null).singleNodeValue?.click()
}, utools.getPath('downloads') + '/removebg_' + Date.now() + '.png')
// 关闭窗口
.hide()
// 开始运行
.run({ width: 880, height: 720 })
js
const filePath = `/path/to/test.zip`
// 发送文件到微信文件传输助手
utools.ubrowser
.goto('https://filehelper.weixin.qq.com')
// 等待扫码登录
.wait('textarea')
// 上传文件,自动发送
.file('#btnFile', filePath)
// 开始运行
.run({ width: 720, Height: 680 })
js
const text = `https://pan.baidu.com/s/1ekPm-ooS0uvVA_J7ZqVGDQ 提取码: kvr5`
const matchs = text.match(/(https?:\/\/[a-z0-9-._~:/?=#]+)\s*(?:\(|()?(?:提取密?码?|访问密?码|密码)\s*(?::|:)?\s*([a-z0-9]{4,6})/i)
// 网盘自动提取
utools.ubrowser
// 打开网盘地址
.goto(matchs[1])
// 等待页面加载完成出现 input 元素
.wait('input')
// 等待 500 ms
.wait(500)
// 让提取码输入框获得焦点
.evaluate(function () {
const inputDoms = Array.from(document.querySelectorAll('input'))
const targetInput = inputDoms.find(x => x.placeholder.includes('提取码') || x.placeholder.includes('访问码')) || inputDoms[0]
targetInput.focus()
})
// 粘贴提取码
.paste(matchs[2])
// 等待 300 ms
.wait(300)
// 回车
.press('enter')
.run({ width: 1280, height: 720 })