2.2. 用元数据描述您的用户脚本 [深入浅出 Greasemonkey]

2.2. 用元数据描述您的用户脚本

每个用户脚本都含有一段元数据，用来向 Greasemonkey 描述这个脚本自身的信息：发行者，执行规则等等。

例 2.2. Hello World 元数据

// ==UserScript==
// @name          Hello World
// @namespace     http://diveintogreasemonkey.org/download/
// @description   example script to alert "Hello world!" on every page
// @include       *
// @exclude       http://diveintogreasemonkey.org/*
// @exclude       http://www.diveintogreasemonkey.org/*
// ==/UserScript==

这里有六条独立的元数据信息，作为一个整体包含在注释中。现在让我们按顺序逐条解释。首先讲最外面的这层包装。

// ==UserScript==
//
// ==/UserScript==

上述标记很重要，必须完全吻合。Greasemonkey 用它们来标记用户脚本的元数据段。这段注释可以放在用户脚本的任何部位，但经常会放在靠近顶部的地方。

在元数据段内，第一项是名字。

// @name          Hello World

这是您的用户脚本的名字。它将会在您第一次安装脚本时在安装对话框（install dialog）中显示出来。之后会显示在“管理用户脚本”对话框中。这个名字应该言简意赅。

@name可选的。如果存在，它只能被定义一次。如果不存在，将会默认显示用户脚本的去掉扩展名.user.js的文件名。

下一个是命名空间(namespace)。

// @namespace     http://diveintogreasemonkey.org/download/

这是一个 URL，Greasemonkey 用它来区分名称相同但是作者不同的用户脚本。如果您有一个域名，您可以使用它作命名空间。另外您也可以用 tag: URI。

@namespace是可选的。如果存在，它只能被定义一次。如果不存在，将会默认使用下载用户脚本的网站域名。

元数据可以以任意次序排列。笔者推荐使用@name，@namespace，@description，@include，最后是@exclude，但是其它的顺序也没关系。

下一项是描述。

// @description   example script to alert "Hello world!" on every page

这是关于用户脚本功能的描述。在您第一次安装脚本时，它将会在安装对话框中显示，之后会在“管理用户脚本”对话框中显示。描述不应多于两句。

@description是可选的。如果使用它，那么它只能被定义一次。如果不使用，默认会显示为空白。

不要忘记写@description。即使您所写的用户脚本是给自己用的。你最后很可能会拥有很多脚本，如果没有描述的话，在“管理用户脚本”对话框中管理脚本将会成为一件令人头疼的事。

下面三行是最重要的 (从 Greasemonkey 的角度来看)：@include和@exclude URL。

// @include       *
// @exclude       http://diveintogreasemonkey.org/*
// @exclude       http://www.diveintogreasemonkey.org/*

这几行让 Greasemonkey 知道在那些网站上执行您的用户脚本。您可以明确的指定一个 URL，或者用通配符*来代替域名或路径中的部分字符。在这个例子中，我们告诉 Greasemonkey 在除了http://diveintogreasemonkey.org/和http://www.diveintogreasemonkey.org/的所有网站上执行。排除(Excludes)优先于包含(includes)，所以即使http://diveintogreasemonkey.org/download/匹配* (所有网站)，它还是会被排除掉，因为它还匹配http://diveintogreasemonkey.org/*。

@include和@exclude 是可选的，可以自定义执行和豁免的 URL，但必须每条规则各占一行。如果您没有任何定义， Greasemonkey 将会对所有的网站执行您的用户脚本。(等同于@include *)。

您需要定义非常精确的@include和@exclude元数据。Greasemonkey 不会对域名作任何的假设，如果一个网站符合http://example.com/和http://www.example.com/，您需要把这两个网址都标示出来。

参考资料

tag: URIs

← Hello World

编写用户脚本代码 →