如何开发一个用户脚本系列(2)——需要哪些基础知识

在第一篇文章中，我对用户脚本进行了一些介绍，让大家对其有个大概的了解。在这篇文章中，我会对用户脚本开发过程中要用到的基础知识做一些介绍，让大家知道脚本中哪部分代码是干什么的，常用的操作有哪些。主要包括 3 个部分的介绍: 脚本头部 UserScript 包含的脚本属性、脚本管理器提供的 API 以及脚本内容中常用的 JS DOM 操作。在后面的所有介绍中，我将使用 Chrome 浏览器和 Tampermonkey 脚本管理器来操作。

UserScript

打开任何一个脚本的源码，都可以看到前面有这样一段类似的代码:

那么这段代码是干什么用的呢？是必须有还是可有可无呢？如果是必须有，那么新建一个脚本的时候应该怎么写，写哪些？OK，我们来一一解释。
首先，这段代码是用来给脚本设置属性的。比如说脚本叫什么名字，脚本的版本号是多少，脚本的作者是谁，脚本支持在哪些网站上运行等等。其次，这段代码必须有，只是某些属性可以不写。脚本属性的语法如下:

// ==UserScript==
// @key value
// ==/UserScript==

每一行都应该以 // 开头，所有的属性都应该被 ==UserScript== 和 ==/UserScript== 包含，一行只能写一个属性，前面写属性名，后面写属性值，中间用空格隔开。下面让我们来看看常用的属性都有哪些，在什么情况下能用到哪个属性。

@name

脚本的名称，必填项。

@description

脚本的功能描述，必填项。

@namespace

脚本的命名空间，一般如果自己有网站的话，可以写自己网站的 URL。@namespace 和 @name 这两个属性被作为脚本的唯一标识符，脚本管理器根据它们来判断一个脚本是否已安装。如果在更新脚本时更改了任意一项，将发出警告，必填项。

@version

脚本的版本号，主要是为了更新脚本时使用。每一次更新脚本都应该增加版本号，版本号可以写成 0.1 或者 0.0.1 这样，下次更新脚本的时候改为 0.2 或者 0.0.2 这样，必填项。

@author

脚本作者，可选项。

@require

脚本需要的一些外部脚本文件，比如常用的有 jQuery 文件，可选项。

@include

匹配脚本的运行网站，如果脚本要在多个网站上运行，需要写多行，一行写一个网站。跟 @match 二者必须有一项，否则脚本将不会再任何网站上运行。

@match

功能跟 @include 类似，在匹配网站时，如果不想写的过于详细，可以使用 * 来匹配任意字符，例如:

@match    https://www.baidu.com/

这一句只有当网址完全匹配时脚本才能运行，如果 URL 有任何多余字符脚本就不会运行。而下面这一句就可以匹配的更多:

@match    *://*.baidu.com/*

这样不管是以 http 开头还是以 https 开头，都能匹配，后面的网站不管是 www.baidu.com 还是 tieba.baidu.com 还是 www.baidu.com/s?wd=apple 之类的，都能匹配，脚本都会运行。当然真正写脚本的时候，就要注意观察目标网站的 URL 规则，做到在需要运行脚本的网站上才让脚本运行。跟 @include 二者必须有一项，否则脚本将不会再任何网站上运行。

@exclude

排除脚本运行的网站，写在这个属性后面的网站，脚本将不会运行，可选项。

@resource

脚本用到的外部资源，比如说脚本中要用到一些网络图片，就可以将图片链接写在这里，并给图片指定一个名称，这样在脚本中就可以使用指定的名称来拿到图片了。

@grant

指定脚本要用到的脚本管理器的 API，这些 API 能实现数据的存取，将内容复制到剪贴板，网络请求，打开 tab 页等功能，具体会在下一部分介绍。如果用不到就写 none，如果有多个，就写多行，每行一个。
上面介绍的是一些比较常用的属性，详细属性列表可以查看 Tampermonkey 文档 或者 Greasemonkey 文档。

脚本管理器的 API

为了让开发脚本更方便，脚本管理器也为我们提供了很多 API，我们在脚本的开头声明后，就可以在代码里面使用。下面介绍一下常用的 API，有一点需要主要的是，Tampermonkey 和 Violentmonkey 提供的 API 是以 GM_* 的形式存在的，而 Greasemonkey 提供的 API 是以 GM.* 的形式存在的，同时有些 Tampermonkey 有的 API，在 Greasemonkey 里面并没有 API 与之对应。

GM_info

可以获取一些脚本的信息，比如在属性里面设置的脚本名称，脚本作者，脚本描述，脚本版本号等等，但用的比较少。示例:

GM_info.script.name

上述代码可以用来在脚本中获取脚本名称，值类型是 String。

GM_setValue(key,value)

用来存储一些用户设置的数据，如果脚本中有需要用户进行个性化设置的内容，就可以使用这个函数进行存储，比如文件的保存路径之类的。当下一次脚本更新时，用户之前设置的内容依然保留，不会丢失。示例:

GM_setValue("save_path"，"D:\downloads\")

上述代码设置了一条数据，即文件的保存路径。键为 save_path，值为 D:\downloads\。key 的类型为 String，value 的类型可以是 String、Boolean、Integer、Json 串、List 等。有一点需要注意的是，在使用 Greasemonkey 的 GM.setValue(name,value) 时，value 的类型只能是 String、Boolean、Integer。

GM_getValue(key,defaultValue)

用来获取通过 GM_setValue(key,value) 设置的数据，可以设置默认值，这样当取不到值时，会使用默认值代替。示例:

String savePath = GM_getValue("save_path"，"E:\")

如果先使用 GM_setValue("save_path"，"D:\downloads\")设置了值，那么 savePath 的值将为 D:\downloads\，否则 savePath 的值为 E:\。

GM_openInTab(url,loadInBackground)

用来在浏览器的新 tab 页打开给定的 URL，url 是 String 类型，loadInBackground 可以是 Boolean 类型，如果是 true，则当前 tab 不变，如果是 false，则当前 tab 变为新打开的 tab。示例:

GM_openInTab("https://www.baidu.com/",false)

上述代码将会在新的 tab 页打开百度，并将这个 tab 页设置为当前 tab 页。

GM_getResourceURL(name)

用来获取在脚本开头通过 @resource 设置的外部资源的 URL，name 为 String 类型，示例:

// @resource    up_button_icon    https://coding.net/u/mofiter/p/public_files/git/raw/master/back_to_top_button.png

脚本开头通过上述方式设置 icon 的名字为 up_button_icon，地址为 https://coding.net/u/mofiter/p/public_files/git/raw/master/back_to_top_button.png，在脚本中就可以通过下面的方式获取到 icon 的 url:

img.src = GM_getResourceURL("up_button_icon")

GM_xmlhttpRequest(details)

用来进行网络请求，有些脚本中可能需要对一些接口进行数据请求，就可以用到这个函数。details 是 json 类型，示例:

GM_xmlhttpRequest({
    url:"http://127.0.0.1:6800/jsonrpc",
    method:'POST',
    data:JSON.stringify(json_rpc),
    onerror:function(response){
        console.log(response);
    },
    onload:function(response){
        console.log(response);
    }
});

其中，url 是要请求的接口地址，method 是请求方法，一般是 GET 或 POST，data 则是 POST 请求需要发送的数据，onerror 是错误回调函数，如果接口请求出错，就会走这个回调，在函数里面进行错误处理，onload 是成功回调函数，如果接口请求成功，就会走这个回调，在函数里面进行下一步操作。当然还有很多参数可以设置，详见 文档。此段代码详见脚本 网易云课堂下载助手。

unsafeWindow

这个对象可以获取到目标网站中的一些变量和 JavaScript 函数。示例:

unsafeWindow.COVER_INFO

腾讯视频电视剧的播放页面有一个变量叫 COVER_INFO，其中包含许多信息，如果有需要，可以通过这种方式取信息做一些操作。

上面介绍的是一些比较常用的 API，详细 API 函数可以查看 Tampermonkey 文档 或者 Greasemonkey 文档。

常用的 JS DOM 操作

脚本的目的是提供方便，给目标网站添加一些官方没有提供的功能。要对原网站进行操作，可以使用 HTML，比较直观，但比较繁琐，也可以使用 jQuery，比较简洁，但可能可读性稍弱一点。如果要在脚本中使用 jQuery，需要先在脚本开头使用 @resource 引入 jQuery 库，具体引入哪一个版本，可以自己选择。

// @require    https://cdn.bootcss.com/jquery/3.3.1/jquery.min.js

然后在代码开头定义变量 $，这样在后面就可以使用 $(selector).action() 选择 HTML 元素并进行操作了。

var $ = window.$;

添加元素和删除元素

最常见的需求是在目标网站添加一些元素或者删除一些元素。如果要删除元素，那么我们需要先选择我们要删除的元素。在 HTML 中， 选择元素的方法有 getElementById()、getElementsByClassName()、getElementsByName()、getElementsByTagName()、querySelector()、querySelectorAll() 等；在 jQuery 中，选择元素的方法为 $()，其中括号里面的选择器可以用 #id，.class，标签名 等。选择了元素之后，我们就要删除它。在 HTML 中，removeChild() 用来删除当前元素的子元素；在 jQuery 中，remove() 用来删除当前元素和它的子元素，empty() 用来删除当前元素的子元素，hide() 用来隐藏当前元素(相应地，show 用来显示当前元素)。如果我们要添加元素，就要先创建元素。在 HTML 中，createElement 用来创建元素，appendChild() 用来给当前元素添加子元素，insertBefore() 用来在当前子元素前面加入一个新的子元素；在 jQuery 中，append() 用来在当前元素的结尾添加子元素，prepend() 用来在当前元素的开头添加子元素，after() 用来在当前元素后面添加同级元素，before() 用来在当前元素前面添加同级元素。

事件操作

当我们给目标网站添加了元素之后，我们通常希望可以处理一些用户操作。比如当用户点击按钮时，我们希望触发一些操作；当用户鼠标进入某个元素时，我们希望触发一些操作；当用户鼠标移出某个元素时，我们希望触发一些操作等等。在 HTML 中，可以使用 addEventListener(event,function) 函数向某个元素添加时间监听。其中 event 表示用户操作，比如 click、mouseenter、mouseleave 等；而 function 为事件触发后要执行的函数。在 jQuery 中，可以对选择的元素直接调用相应的方法进行相应的操作。示例:

$("#button").click(function(){
    console.log("点击了按钮");
});
$("#button").mouseenter(function(){
    console.log("鼠标移入了按钮");
});
$("#button").mouseleave(function(){
    console.log("鼠标移出了按钮");
});

也可以使用 on(event,function) 方法实现跟上面相同的操作。示例:

$("#button").on("click",function(){
    console.log("点击了按钮");
});
$("#button").on("mouseenter",function(){
    console.log("鼠标移入了按钮");
});
$("#button").on("mouseleave",function(){
    console.log("鼠标移出了按钮");
});

总结

本文对脚本开发中需要用到的基础知识做了一些介绍，包括脚本的属性设置、脚本管理器提供的函数支持以及一些 HTML 的元素操作。如果还有疑问，可以留言，从下一篇文章开始，将结合已经完成的脚本示例，讲解在真正开发一个脚本的时候，要考虑哪些东西，怎么写好一个脚本。