描述

元数据 包含了用户脚本的元数据。一般包含脚本名称、命名空间、执行地址和不执行的地址。

这些数据一般为 JavaScript 注释形式储存于脚本顶部。

例子

  1. // ==UserScript==
  2. // @name          我的第一个脚本
  3. // @namespace     http://www.example.com/gmscripts
  4. // @description   看我突破天际的钻头
  5. // @include       http://www.example.com/*
  6. // @include       http://www.example.org/*
  7. // @exclude       http://www.example.org/foo
  8. // @require       https://example.com/foo.js
  9. // @resource      logo logo.png
  10. // @resource      yooo http://www.example.com/resource2.png
  11. // @version       1.0
  12. // @icon          http://www.example.net/icon.png
  13. // ==/UserScript==

语法

元数据必须按照以下格式填写

  1. // ==UserScript==
  2. // @属性名 属性值
  3. // ==/UserScript==

每一条属性必须使用双斜杠//开头，不得使用块注释/* */。

与此同时，所有的脚本元数据必须放置于 // ==UserScript== 和 // ==/UserScript== 之间才会被认定为有效的元数据。

元数据名和值中间可以为了保持美观添加多个空格。

值

用于指示该脚本名称，将显示于「脚本管理」及「猴子菜单」。该值同时为相同命名空间的唯一识别码。 如果未指定该参数，将尝试从文件名获取。 简单描述当前脚本的功能。也会于用户脚本管理界面显示。 命名空间和脚本名称是 GM 用于识别脚本唯一性的方法。如果两个脚本的名称和命名空间均相同，那么后安装的脚本将覆盖之前安装的脚本。 一般脚本作者将其项目使用相同命名空间，然后每个项目使用不同名称。 同时因为命名空间没有语法限制，一些作者直接使用项目首页作为其命名空间。该值只要不与他人重复即可。 指定脚本的版本号，GM 用来判断脚本是否更新的依据。 引用一个外部链接的脚本作为库使用。最常见的外部库为 jQuery。 因为 GM 对 IE 的支援不佳，因此一般不用考虑 IE 的兼容性，放心去搞吧~ GM 的默认设定要求该值使用 https:// 协议。 该值用于指定发现更新后使用的脚本地址。若未指定则使用安装脚本地址。 用于检查更新使用的地址。该地址应只包含元数据而不包含脚本内容。 指定脚本所请求的权限，如 unsafeWindow 用于访问浏览器的 window 对象。 其它可选值则为 GM 提供的 GM_ 开头的 API。 
  1. // ==UserScript==
  2. // @include     http://www.example.com/foo/
  3. // @include     http://www.example.org/*.bar
  4. // @exclude     http://www.example.com/foo/baz
  5.  
  6. // GM 0.9.8 开始, @include 允许使用正则表达式匹配
  7. // @include     /^https?://www.example.com/.$/
  8. // @include     /^http://www\.example\.(org|net)//
  9. // ==/UserScript==
@include 和 @exclude 使用 \ 表示任意字符，或标准正则表达式对象。 同时，它还支持一个特殊的匹配符，.tld。 
  1. @include http://www.example.tld/*
请注意: 如果使用 tld 匹配请务必确保数据不会被泄露给无关网站。 其中， @exclude 的匹配权限比 @include 要高。 GM 根据 Chrome 的 Match Patterns 实现的另外一种匹配方案，比 @include / @exclude 的匹配更严格。详细请参考上述 Chrome 开发者页面。 用于脚本管理界面显示的图标。虽然什么图片都可以，但建议使用 32x32 大小的图标。 该参数可指定任意数量的资源。但请注意，同一脚本下资源名不得重复。 资源将在安装脚本的时候下载一次，之后不会进行更新。 这些资源可以稍后通过 GM_getResourceURL 或 GM_getResourceText 获取其内容或地址。 自从 GM 0.9.0, 如果 GM 发现 @resource 的值被更改后将尝试重新下载。 该值用于指定脚本执行的时机，可用的参数只能为 document-start 和 document-end 两种。 Chrome 下的 TamperMonkey 还提供了 document-body 这一选项，但是 GM 官方文档找不到说明，最好避免使用。 如果不填写该值，GM 将采用 document-end 作为默认值。 检查脚本是否执行于 document-start，检查 document.readyState 的值即可: 
  1. if ('loading' == document.readyState) {
  2.     alert("脚本执行于 document-start。");
  3. } else {
  4.     alert("脚本当前的 document.readyState: " + document.readyState);
  5. }
 该功能在 GM 1.0+ 已经被抛弃使用，后期的 GM 默认启用该功能。 
  1. // @unwrap
该元数据表示代码将不会使用 (function () { /* 代码 */ })(); 这样的形式执行，因此请注意不要在外部填写 return 语句。