第三方软件交互

浏览器控制

概述

通过浏览器扩展程序与浏览器通信,从而实现对网页或浏览器本身的控制。目前兼容的浏览器:

  • 谷歌Chrome
  • 微软新版Edge
  • 其它基于chromium内核的第三方浏览器
  • Firefox浏览器


本模块的用途主要有2个大的类别:

  • 获取或更新网页中的内容/触发网页元素事件。
  • 通过后台脚本控制浏览器本身。


注:

  • 本模块为预览测试状态,如发现问题欢迎反馈。
  • 您可能需要了解Html/CSS/Javascript/JQuery等相关知识才能灵活的使用本模块。
  • 文档中有不清楚的地方欢迎留言或在Quicker网站中反馈。
  • 扩展已开源,网址:https://github.com/cuiliang/QuickerConnectorExtension


安装浏览器扩展


谷歌浏览器

方式1:谷歌应用商店

https://chrome.google.com/webstore/detail/quicker-chrome-connector/klggbkjfmbonefdcfkiidhcmfjdfnepa

如果您之前通过zip方式添加了扩展,请先删除该扩展后再从应用商店添加。


方式2:使用crx文件


安装并启用扩展后,在Windows任务管理器的Chrome进程下应该可以看到3个子进程。

image.png


微软新版Edge浏览器

https://microsoftedge.microsoft.com/addons/detail/quicker-connector/hcnknmobjnlekfkbcllhcoldbppkgpda


Firefox浏览器

https://addons.mozilla.org/zh-CN/firefox/addon/quicker-connector/

https://deskpad.oss-cn-shanghai.aliyuncs.com/_sitefiles/chrome/quicker_connector-0.4.1-fx.xpi




扩展使用

点击扩展图标会显示一个弹窗。请确认消息代理已连接。

在动作中使用的后台脚本(主要用于访问和控制浏览器自身信息),可能会使用到一些权限,请根据情况给予权限。

image.png




注意事项


限制

  1. 因为浏览器本身的限制,在浏览器本身的功能页面中(以chrome://开始)通常无法工作。

image.png

  1. 无痕模式(隐身模式)下默认不可使用。如需使用,请尝试在浏览器扩展设置页面中开启允许选项。

image.png

  1. 浏览器有各类安全限制,可能导致:
    1. 部分网页交互需要人工操作才能触发,如文件上传、document.execCommand脚本。(部分操作可能在人工点击页面一次之后可以通过脚本触发)


  1. 此模块功能实现原理比较复杂,涉及到多次信息中转:

Quicker模块 <----> ChromeAgent.exe消息代理(浏览器插件的NativeMessageHost) <----> 插件后台脚本 <----> 标签页内容脚本。有的内容无法支持传输。




多种浏览器兼容问题

  • 您的电脑可以同时在Chrome浏览器和新Edge浏览器中使用Quicker浏览器扩展。
  • 其他第三方基于Chromium的浏览器(如QQ/360),以及谷歌Chrome浏览器本身,请只在一个浏览器上安装并使用插件(它们都会被识别为chrome浏览器)。


在某个动作中第一次使用“浏览器控制”模块时,Quicker会根据前台窗口进程猜测要连接哪个浏览器,并且在后续的操作中持续连接此浏览器。


如果在第一次运行到“浏览器控制”模块时,前台窗口不是谷歌Chrome或微软Edge浏览器,则使用配置中设定的“默认连接的浏览器”。

image.png

也可以通过在动作中添加“设置连接的浏览器”操作(添加到其他浏览器操作步骤之前),设置此动作要连接的浏览器。

image.png


可能还有其他无法正常工作的情况,如有遇到欢迎反馈。



通用参数

【标签页ID】指定要操作的标签页,如果留空,则表示操作当前活动标签页。


【选择器】用于指定要操作的网页元素的CSS选择器

选择器对于操作网页是极其基础和重要的知识,请务必了解:https://www.runoob.com/cssref/css-selectors.html


在浏览器中可以通过如下方式获得单个元素的选择器:

image.png

如果需要通过xpath的方式指定元素,以xpath:开始,如:

xpath://*[@id="lark-text-editor"]/div/div/div[2]/div[1]/div[2]/div[1]/a[11]

如果要选择一类元素,比如所有的链接或图片,就需要手写选择器了。


【修正选择器文本】(1.10.3版本提供)从Chrome中复制的选择器文本,如果含有\字符,需要将其替换成\\才能正常定位。此参数可选:

  • 自动:自动判断是否需要将\替换为\\。
  • 不修正:不替换\字符。
  • 替换\为\\:将\替换为\\。


各操作类型

添加模块后,选择操作类型,并根据操作类型填写输入输出参数。

image.png


打开网址

打开一个网址,并获得其“标签页id”,以方便后续对此标签页进行其他自动化操作。

image.png

【网址】要打开的完整网址。需要带有协议头(http://或https://)。

【窗口ID】使用哪个窗口打开网址。可选值:

  • 新窗口;
  • 当前活动窗口;
  • 也可以使用之前打开的窗口,并通过表达式 $={窗口ID} 的指定变量。

image.png

【窗口信息】可选。仅用于使用新窗口打开网址时,设定窗口参数。参数请参考Chrome API 文档chrome.windows.create 的 createData参数。示例(所有字段都是可选的):

{
    left: 100,
    top: 100,
    width: 400,
    height: 400,
    incognito: true,
    type: 'popup'    
}

【等待操作完成】等待网页加载完成(标签页前面不转圈了)。资源比较多的网页加载时间会比较长,有的带有长连接的网页,会一直是加载不完成的状态,后续的操作不一定要等待加载完成。

image.png


【超时时间】等待网页加载的时间。


输出

【是否成功】操作是否出错。

【标签页ID】新打开的标签页ID号数字。后续如果需要对打开的网页进行操作,需要提供此标签页ID。

【窗口ID】打开新窗口时,输出新打开的窗口的编号。

【原始返回结果】从浏览器插件返回的原始结果反序列化后的JToken对象。JToken可以用来方便的访问Json内容。



等待加载完成

等待某个标签页的内容加载完成。通常用于使用脚本提交了表单等造成页面刷新或表单提交的情况。根据网页资源的多少,加载完成时间可能比较长。

image.png

参数

【标签页Id】要操作的标签页编号。如果为空,表示当前活动标签页。

【超时时间】等待网页状态变为加载完成状态。

【失败后停止】超时后是否停止动作。注:不是所有的操作都需要彻底加载完成才能继续。


输出

【原始返回结果】空。




获得标签页信息

获得某个标签页的信息。不指定标签页ID时,获取当前活动标签页的信息。

image.png


输入

【标签页Id】要获取信息的标签页序号。 不填写时表示获取当前活动标签页的信息。


输出

【标签页Id】在获取当前活动标签页信息时,得到标签页的Id。

【窗口Id】标签页所在窗口的Id。

【网址】标签页所打开的网址。

【网页标题】网页的标题文字。

【Favicon图标网址】网页图标的网址。

【浏览器】当前连接的浏览器名称,支持chrome/msedge。

【插件版本】浏览器扩展的版本号。

【原始返回结果】当前标签页的Tab对象信息



关闭标签页

关闭指定的标签页。

image.png


输入

【标签页Id】要关闭的标签页。未指定标签页Id时,关闭当前活动标签页。



对标签页运行脚本

对指定的标签页网页运行js脚本。

浏览器插件已自动加载JQuery 3.5.1,因此可以直接在脚本中使用JQuery库的功能。

脚本将通过浏览器的chrome.tabs.executeScript接口运行,详情可参考该文档。

image.png

输入

【标签页Id】要运行脚本的标签页,未指定时,对当前活动标签页运行脚本。

【脚本内容】要运行的js脚本内容。


输出

【原始返回结果】js脚本的返回值JToken对象。


返回值

返回值是一个数组,表示每个Frame的运行结果。如果网页只有一个Frame,则该数组只有一项。(请参考chrome.tabs.executeScript文档


js脚本的值通常是脚本中最后一个语句的返回值。


如下面的脚本返回网页的文本内容:

document.body.innerText;

可以在浏览器插件的背景页面控制台查看到脚本的运行结果。

image.png

如果需要返回复杂的对象,也可以使用js函数。

(function (){
  return {
    title: document.title,
    bodyText:document.body.innerText,
    val: 100
  };   //返回一个复杂对象
})();  // 定义一个函数并且执行它



获取元素信息

获取网页元素的信息。

image.png

输入

【标签页ID】要获取信息的标签页,未指定时,获取前活动标签页中的网页元素。

【选择器】用于选择要操作元素的CSS选择器


【元素信息类型】要获取元素哪方面的信息。

支持的类型有:

  • 值:通过jquery的val()方法获取元素的值。主要用于获取input、select和textarea类型元素的值。要获取选中的radio button或 checkbox的值,需要在选择器中使用:checked修饰符,如:
    • select#foo option:checked 获得一个下拉框的选中项的值
    • select#foo 获得一个下拉框的值
    • input[type=checkbox][name=bar]:checked 获得某个选中的检查框的值
    • input[type=radio][name=baz]:checked 获得某个选中的单选按钮的值
  • 某个Attribute属性:通过jquery的attr()方法获取元素的属性值。attr通常是网页代码里设置的属性值。
  • 某个Property属性:通过jquery的prop()方法获取元素的属性值。prop通常是属性运行时的值,如果链接的网址,在href='/index'的情况下,attr得到的是'/index',prop得到的是根据当前网址计算得到的完整网址。
  • innerText:元素节点及其后代(子节点)的“渲染”文本内容。此信息通过jquery的text()方法获取。
  • innerHTML:元素内的HTML内容。此信息通过jquery的html()方法获取。
  • outerHTML:包含元素自身的HTML内容。此方法通过DOM元素的outerHTML属性获得。


【属性名】当要获取的元素信息类型位“某个Attribute”或“某个Property”时,指定属性名。如链接的网址属性为“href”。


输出

【第一个值】获取第一个符合选择器条件的元素的指定信息。一般用于取某一个特定元素的信息。

【所有的值】所有符合选择器条件的元素的值的列表。一般用于取某一类元素的信息。


示例动作



更新元素信息

更新元素某方面的信息。参数输入请参考“获取元素信息”。

更新元素时,所有符合“选择器”条件的元素的对应信息都会被更新。



更新下拉框select元素的值

首先请确定要设置的选项的值(value)

image.png

然后使用“更新元素信息”操作,元素信息类型为“值”

image.png


更新选择检查框和单选框的选择状态

在1.9.10版本之后,可以通过更新checked 的属性(Property)选择或取消选择checkbox 或 radio 的选择状态。

image.png

更早的版本,可以使用在对标签页运行js代码:

$('选择器').prop('checked', true);  //选择检查框
$('选择器').prop('checked', false);  //取消选择

需要使用input元素本身的选择器来更新选中状态。

image.png



触发事件

对指定的元素触发事件。

image.png

输入

【标签页ID】要操作的标签页,未指定时表示操作当前活动标签页。

【选择器】要操作的网页元素。

【触发事件类型】要触发的事件。可以选择预置的事件,也可以直接写事件名称。

image.pngimage.png

注:

除单击事件外,本功能主要通过jquery.trigger()方法实现。单击事件则直接调用DOM的click()方法(方便支持点击链接)。

提交表单时,需要使用form元素本身的选择器。


设置连接的浏览器

设置当前动作要连接哪个浏览器的插件。请参考“多种浏览器的兼容问题”章节。





运行后台脚本

使用脚本控制浏览器本身而不是某个网页。

可以在后台脚本中调用Chrome Extension API。(国内访问


从后台脚本返回内容


1)选中“等待操作完成”选项。

image.png


2)返回结果



在脚本内容中使用sendReplyToQuicker(isSuccess, message, data, qk_msg_serial) 返回自定义内容(0.3.0版本插件+1.9.3版本Quicker)。

  • isSuccess:表示操作是否成功,布尔类型,可选值true/false。
  • message:消息内容。在操作失败时返回错误消息。
  • data:返回的数据内容。
  • qk_msg_serial:quicker的消息序号。在执行脚本时会被添加到window窗口,所以在脚本中直接写此变量名即可。
//.js  获取当前窗口的所有网址。动作网址:
chrome.windows.getLastFocused({populate:true}, function(win){
    var urlList = win.tabs.map(x=>x.url);
    sendReplyToQuicker(true, "ok", urlList, qk_msg_serial)
});

返回数据的示例动作:


3)输出返回结果

在脚本中使用sendReplyToQuicker返回的data参数,如果是object类型,将会直接返回;

如果对象是简单类型(如数字、字符串等),会封装为一个对象返回:

{
  "data":qk_bgmsg_result
}


输出结果为JToken对象。请参考后面的“从JToken提取数据”章节。


其他后台脚本示例动作:





排错

查看日志

查看背景页面控制台信息

在浏览器扩展页面中开启“开发者模式”。然后点击扩展的“背景页”

image.png

在背景页的控制台可以看到一些log输出。

image.png

查看ChromeAgent日志

ChromeAgent.exe是与浏览器通信的中间件程序,由浏览器启动。Quicker在首次使用浏览器控制模块时与该程序建立连接。

为避免更新Quicker软件时文件被锁定,ChromeAgent.exe将会在Quicker安装后首次启动时,由Quicker程序复制到应用数据文件夹下并注册。位置为:Quicker应用数据文件夹\bin\NativeMessageHost(一般为:C:\Users\用户名\AppData\Local\Quicker\bin\NativeMessageHost)


该文件夹下有一个native-messaging.log文件保存了ChromeAgent.exe与浏览器和Quicker的通信日志。

image.png


常见错误

插件显示未连接


image.png

请安装Quicker 1.9.2+版本。




其它信息


组件构成

Quicker:发送指令并获取返回结果;

ChromeAgent.exe:消息代理程序,连接Quicker和浏览器插件。会在Quicker安装或升级版本后首次启动时拷贝到“应用数据文件夹\bin\NativeMessageHost”子文件夹下。

Chrome浏览器插件:负责接收指令、执行指令,并返回结果。


从JToken中提取信息

注意:

  • 对标签页运行脚本,返回的结果是数组,表示每个Frame框架中的运行结果。
  • 运行后台脚本返回的是通过qk_bgmsg_result变量设置的object类型的结果或者封装的{data: qk_bgmsg_result}封装的简单值结果。


JToken可以在表达式中使用 [数组的序号] [对象的属性名] 访问到某个值,然后通过.ToString() 方法得到文本。

下图的表达式,得到了返回结果数组第0个对象的title属性的值。

image.png

也可以使用SelectToken获取对象(或SelectTokens获取数组)。

image.png


也可以获取其原始类型的值(根据实际的类型),下面的表达式得到 "val" 属性的整数值:

image.png



参考文档

  • JQuery教程:
  • Chrome开发文档:
语雀在语雀上查看