Greasemonkey 元数据
元数据 包含了用户脚本的元数据。一般包含脚本名称、作者、版本、更新地址、命名空间、允许执行和不执行的页面地址。 这些数据一般以 JavaScript 注释形式储存于脚本顶部。
示例
// ==UserScript==
// @name New Userscript
// @namespace https://xiaobai.wang/
// @version 0.1
// @description try to take over the world!
// @author You
// @match https://jixunmoe.github.io/gmDevBook/
// @icon https://www.google.com/s2/favicons?sz=64&domain=github.io
// @grant none
// ==/UserScript==语法
元数据必须按照以下格式填写
// ==UserScript==
// @属性名 属性值
// ==/UserScript==
每一条属性必须使用双斜杠//开头，不得使用块注释/* */。
与此同时，所有的脚本元数据必须放置于 // ==UserScript== 和 // ==/UserScript== 之间才会被认定为有效的元数据。
元数据名和值中间可以为了保持美观添加多个空格。
Meta属性
@name
// @name 测试用脚本
用于指示该脚本名称，将显示于「脚本管理」及「油猴菜单」。该值同时为相同命名空间的唯一识别码。
如果未指定该参数，将尝试从文件名获取。
@description
// @description This script even does the laundry!
简单描述当前脚本的功能。也会于用户脚本管理界面显示。
@namespace
// @namespace https://xiaobai.wang/
命名空间和脚本名称是 GM 用于识别脚本唯一性的方法。如果两个脚本的名称和命名空间均相同，那么后安装的脚本将覆盖之前安装的脚本。
一般脚本作者将其项目使用相同命名空间，然后每个项目使用不同名称。
同时因为命名空间没有语法限制，一些作者直接使用项目首页作为其命名空间。该值只要不与他人重复即可。
@version
// @version 1.0
指定脚本的版本号，GM 用来判断脚本是否更新的依据。
@require
// @require http://cdn.staticfile.org/jquery/2.1.1/jquery.min.js
引用一个外部链接的脚本作为库使用。最常见的外部库为 jQuery。
因为 GM 对 IE 的支援不佳，因此一般不用考虑 IE 的兼容性，放心去搞吧~
@downloadURL
// @downloadURL https://www.xiaobai.wang/myscript.user.js
GM 的默认设定要求该值使用 https:// 协议。
该值用于指定发现更新后使用的脚本地址。若未指定则使用安装脚本地址。
@updateURL
// @updateURL https://www.xiaobai.wang/myscript.meta.js
用于检查更新使用的地址。该地址应只包含元数据而不包含脚本内容。
@grant
// @grant GM_xmlhttpRequest
指定脚本所请求的权限，如 unsafeWindow 用于访问浏览器的 window 对象。
其它可选值则为 GM 提供的 GM_ 开头的 API。
@include / @exclude
// ==UserScript==
// @include http://www.xiaobai.wang/foo/*
// @include http://www.xiaobai.wang/*.bar
// @exclude http://www.xiaobai.wang/foo/baz
// GM 0.9.8 开始, @include 允许使用正则表达式匹配
// @include /^https?://www\.example\.com/.*$/
// @include /^http://www\.example\.(org|net)//
// ==/UserScript==
@include 和 @exclude 使用 * 表示任意字符，或标准正则表达式对象。
同时，它还支持一个特殊的匹配符，.tld。
@include http://www.example.tld/* 请注意: 如果使用 tld 匹配请务必确保数据不会被泄露给无关网站。
其中， @exclude 的匹配权限比 @include 要高。
@match
// @match *://mail.google.com/*
GM 根据 Chrome 的 Match Patterns 实现的另外一种匹配方案，比 @include / @exclude 的匹配更严格。详细请参考上述 Chrome 开发者页面。推荐使用该方式
@icon
// @icon http://www.example.org/icon.png
为脚本定制一个图标，显示在脚本列表以及浏览器扩展菜单中的图标。可以是一个url图标资源或者Base64编码的 Data URI。
如果你的脚本是在某一个网站上面使用的，可以通过下面的方法获取文章的favicon
// @icon https://www.google.com/s2/favicons?sz=64&domain=github.io
@resource
// @resource 资源名 http://www.xiaobai.wang/example.png
该参数可指定任意数量的资源。但请注意，同一脚本下资源名不得重复。
资源将在安装脚本的时候下载一次，之后不会进行更新。
这些资源可以稍后通过 GM_getResourceURL 或 GM_getResourceText 获取其内容或地址。
自从 GM 0.9.0, 如果 GM 发现 @resource 的值被更改后将尝试重新下载。
@run-at
// @run-at document-end
该值用于指定脚本执行的时机，可用的参数只能为 document-start 和 document-end 两种。
Chrome 下的 TamperMonkey 还提供了 document-body 这一选项，但是 GM 官方文档找不到说明，最好避免使用。
如果不填写该值，GM 将采用 document-end 作为默认值。
检查脚本是否执行于 document-start，检查 document.readyState 的值即可:
if ('loading' == document.readyState) {
alert("脚本执行于 document-start。");
} else {
alert("脚本当前的 document.readyState: " + document.readyState);
}
元数据标记@run-at 的取值如下
| 取值 | 描述 |
|---|---|
| document-start | 指定脚本在DOM树开始的时候执行，需要脚本尽早执行的时候添加此声明。 |
| document-end | 指定脚本在DOM数据加载完毕的时候执行 |
| document-idle | 页面加载完毕的时候执行。当元数据没有@run-at声明时，脚本默认在此时机执行 |
| main-menu | X浏览器的扩展声明，表示此脚本不自动执行，用户通过主菜单扩展选项手动执行。 |
| context-menu | X浏览器扩展声明,表示此脚本不自动执行，用户通过长按菜单的扩展选项执行 |
| tool-menu | X浏览器扩展声明，表示此脚本不自动执行，用户通过页面工具菜单的扩展选项执行 |