ubrowser

uTools browser 简称 ubrowser，是根据 uTools 的特性，量身打造的一个可编程浏览器。利用 ubrowser 可以轻而易举连接一切互联网服务，且与 uTools 完美结合。

小技巧

ubrowser 拥有优雅的链式调用接口，可以用口语化的数行代码，实现一系列匪夷所思的操作。例如：

1. RPA 自动化
2. 网页内容魔改
3. 网页内容抓取

浏览器控制

utools.ubrowser.goto(url[, headers][, timeout])

打开一个 ubrowser 窗口，并跳转到指定网页

类型定义

function goto(url: string): UBrowser;
function goto(url: string, headers: Record<string, string>): UBrowser;
function goto(
  url: string,
  headers: Record<string, string>,
  timeout: number
): UBrowser;

• url: 要跳转的网页地址
• headers: 请求头
• timeout: 超时时间，单位毫秒

utools.ubrowser.useragent(ua)

设置用户代理（User-Agent）

类型定义

function useragent(ua: string): UBrowser;

• ua: User-Agent 字符串

utools.ubrowser.viewport(width, height)

设置浏览器视窗大小

类型定义

function viewport(width: number, height: number): UBrowser;

• width: 视窗宽度
• height: 视窗高度

utools.ubrowser.hide()

隐藏 ubrowser 窗口

类型定义

function hide(): UBrowser;

utools.ubrowser.show()

显示 ubrowser 窗口

类型定义

function show(): UBrowser;

网页操作

ubrowser 支持网页内容魔改，即在网页加载前对网页内容进行修改，例如添加自定义 CSS、JavaScript 等。

utools.ubrowser.css(css)

添加自定义 CSS

类型定义

function css(css: string): UBrowser;

• css: 自定义 CSS

utools.ubrowser.evaluate(func[, params])

在网页中执行自定义 JS 代码

类型定义

function evaluate(func: Function): UBrowser;
function evaluate(func: Function, params: any[]): UBrowser;

• func: 自定义 JS 函数，函数若有返回值，则会在run函数的返回值里传递
• params: 传递给func的参数

自动化

utools.ubrowser.press(key[, modifiers])

模拟键盘按键

类型定义

function press(key: string, ...modifiers: string[]): UBrowser;

• key: 要模拟的按键
• modifiers: 要模拟的修饰键，一般为 shift、ctrl、alt、meta

utools.ubrowser.click(selector)

执行点击操作

类型定义

function click(selector: string): UBrowser;

selector: 要点击的元素选择器

utools.ubrowser.mousedown(selector)

执行鼠标按下操作

类型定义

function mousedown(selector: string): UBrowser;

utools.ubrowser.mouseup(selector)

执行鼠标抬起操作

类型定义

function mouseup(selector: string): UBrowser;

utools.ubrowser.file(selector, payload)

对网页中的 input 元素设置文件

类型定义

function file(selector: string, payload: string | string[] | Buffer): UBrowser;

• selector 的对象必须是 input[type=file]
• payload 可以是文件路径、文件路径集合以及文件 Buffer

utools.ubrowser.value(selector, payload)

对网页中的 input 元素设置值

类型定义

function value(selector: string, payload: string): UBrowser;

• selector 的对象必须是 input、textarea、select 元素
• payload 将会设置到 value 属性上

utools.ubrowser.check(selector, checked)

执行勾选操作

类型定义

function check(selector: string, checked: boolean): UBrowser;

• selector 的对象必须是 checkbox、radio 元素
• checked 为 true 时，勾选，否则取消勾选

utools.ubrowser.focus(selector)

执行聚焦操作

类型定义

function focus(selector: string): UBrowser;

utools.ubrowser.scroll(selector)

执行滚动操作

类型定义

function scroll(selector: string): UBrowser;
function scroll(y: number): UBrowser;
function scroll(x: number, y: number): UBrowser;

• selector 为 string 时，滚动到指定元素
• 单独传递y，滚动到纵向指定位置
• 传递x和y，滚动到指定位置

utools.ubrowser.download(url[, savePath])

执行下载操作

类型定义

function download(url: string): UBrowser;
function download(url: string, savePath: string): UBrowser;

• savePath 为 string 时，下载到指定路径，不传递savePath，则下载到默认路径

utools.ubrowser.paste(text)

执行粘贴操作

类型定义

function paste(text: string): UBrowser;

• text: 要粘贴的内容，支持普通文本跟图片 Base64

utools.ubrowser.screenshot(target[, savePath])

对网页进行截屏并保持到指定路径，将会保存成为 png 格式

类型定义

function screenshot(): UBrowser;
function screenshot(target: string, savePath?: string): UBrowser;
function screenshot(target: Rect, savePath?: string): UBrowser;

• 没有参数时，截屏全屏
• 当 target 为 string 时，target 为选择器。可以传入一个 Rect 对象，表示截取指定区域。
• savePath 是截图保存路径（PNG 图片），没有传递 savePath 的时候，默认存储在临时目录。

Rect 类型定义

interface Rect {
  x: number;
  y: number;
  width: number;
  height: number;
}

utools.ubrowser.pdf(options[, savePath])

将网页保存为 PDF

类型定义

function pdf(): UBrowser;
function pdf(options: PdfOptions, savePath?: string): UBrowser;

• PdfOptions 参考 Electron PrintToPDFOptions

• savePath 是 PDF 保存路径，没有传递 savePath 的时候，默认存储在临时目录。

utools.ubrowser.device(options)

模拟设备信息

类型定义

function device(options: string): UBrowser;
function device(options: DeviceOptions): UBrowser;

• options 为 string 时，传递设备名称，例如 'iPhone 11' | 'iPhone X' | 'iPad' | 'iPhone 6/7/8 Plus' | 'iPhone 6/7/8' | 'iPhone 5/SE' | 'HUAWEI Mate10' | 'HUAWEI Mate20' | 'HUAWEI Mate30' | 'HUAWEI Mate30 Pro'

• options 为 DeviceOptions 时，传递模拟设备信息

DeviceOptions 类型定义

interface DeviceOptions {
  userAgent: string;
  size: {
    width: number;
    height: number;
  };
}

延时等待

utools.ubrowser.wait(ms)

执行等待操作

类型定义

function wait(ms: number): UBrowser;
function wait(selector: string, timeout?: number): UBrowser;
function wait(
  wating: (...args: any[]) => boolean,
  timeout?: number,
  ...args: any[]
): UBrowser;

TIP

• wait 将会阻塞 ubrowser 实例其他的链式操作，直到执行完毕，但是不会阻塞 ubrowser 内网页的运行
• 当传递的参数为 number 时，表示等待指定毫秒数
• 当传递的参数为 string 时，表示等待指定选择器出现，通过 timeout 参数设置超时时间，默认为 60000 ms
• 当传递的参数为 function 时，会在网页内执行该函数，并在函数返回 true 时结束等待，通过 timeout 参数设置超时时间，默认为 60000 ms

utools.ubrowser.when(selector)

条件等待操作

类型定义

function when(selector: string): UBrowser;
function when(wating: (...args: any[]) => boolean, ...args: any[]): UBrowser;

TIP

• when 在匹配内容存在时执行，遇到 end 后不再生效
• 当传递的参数为 string 时，表示等待指定选择器出现
• 当传递的参数为 function 时，会在网页内执行该函数

utools.ubrowser.end()

结束上一个 when

类型定义

function end(): UBrowser;

运行实例

utools.ubrowser.run()

运行 ubrowser 实例，并返回执行结果

类型定义

function run(): Promise<[...any, UBrowserInstance]>;
function run(ubrowserId: number): Promise<[...any, UBrowserInstance]>;
function run(options: UBrowserRunOptions): Promise<[...any, UBrowserInstance]>;

ubrowserId 一般以下两种形式获取：

1. utools.browser.run 返回的 UBrowserInstance 的 id 属性（ubrowser 窗口仍在显示时）。
2. utools.getIdleUBrowser 返回的 UBrowserInstance 的 id 属性。
3. run 返回将会返回一个包含数组的 Promise 对象，数组的最后一个元素是当前窗口的 UBrowser 实例，其余的元素则是运行过程中，其他 ubrowser 方法的返回值，比如evaluate、cookies等。

UBrowserRunOptions 类型定义

interface UBrowserRunOptions {
  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 类型定义

interface UBrowserInstance {
  id: string;
  url: string;
  title: string;
  width: number;
  height: number;
  x: number;
  y: number;
}

开发与调试

utools.ubrowser.devTools([mode])

打开浏览器开发者工具。

类型定义

function devTools(mode?: string): void;

mode: 可选值 'right' | 'bottom' | 'undocked' | 'detach' ，默认 'detach'

Cookies

utools.ubrowser.cookies([name])

获取 ubrowser 的 cookie 信息。

类型定义

function cookies(): UBrowser;
function cookies(name: string): UBrowser;

• 不传递参数时，返回所有 cookie 信息。
• cookies 的返回值将在run的返回值中传递。

utools.ubrowser.setCookies

设置 ubrowser 的 cookie 信息。

类型定义

function setCookies(name: string, value: string): UBrowser;
function setCookies(cookies: [name: string, value: string][]): UBrowser;

utools.ubrowser.removeCookies(name)

删除 ubrowser 的 cookie 信息。

类型定义

function removeCookies(name: string): UBrowser;

utools.ubrowser.clearCookies([url])

清空 ubrowser 的 cookie 信息。

类型定义

function clearCookies(): UBrowser;
function clearCookies(url: string): UBrowser;

url: 需要清楚 cookie 的目标 url，当在clearCookies在run函数之前调用时，url参数不能为空。