@plugin At-Rules

发布于 v2.5.0

导入 JavaScript 插件，添加 Less.js 功能和特性
### 编写您的第一个插件

使用 `@plugin` 规则类似于对 `.less` 文件使用 `@import`。

```less
@plugin "my-plugin";  // automatically appends .js if no extension
```
由于 Less 插件是在 Less 范围内评估的，因此插件定义可以非常简单。

```less
registerPlugin({
    install: function(less, pluginManager, functions) {
        functions.add('pi', function() {
            return Math.PI;
        });
    }
})
```
或使用 `module.exports`（经过优化，可在浏览器和 Node.js 中使用）。

```less
module.exports = {
    install: function(less, pluginManager, functions) {
        functions.add('pi', function() {
            return Math.PI;
        });
    }
};
```
请注意，浏览器中不能使用其他 Node.js CommonJS 约定，如 `require()`。在编写跨平台插件时请记住这一点。

插件能做什么？很多，但我们还是从最基本的开始。我们先来看看安装函数中的内容。比方说，你可以这样写

```less
// my-plugin.js
install: function(less, pluginManager, functions) {
    functions.add('pi', function() {
        return Math.PI;
    });
}
// etc
```
恭喜您，您编写了一个 Less 插件 你编写了一个 Less 插件！

如果您要在样式表中使用它：

```less
@plugin "my-plugin";
.show-me-pi {
  value: pi();
}
```
You would get:

```less
.show-me-pi {
  value: 3.141592653589793;
}
```
不过，如果要将该值与其他值相乘或进行其他 Less 操作，则需要返回一个合适的 Less 节点。否则，您的样式表中的输出将是纯文本（对于您的目的来说，这可能还不错）。

意思是，这样更正确：

```less
functions.add('pi', function() {
    return new tree.Dimension(Math.PI);
});
```
注：维度是一个带或不带单位的数字，如 "10px"，应为 `less.Dimension(10, "px")`。有关单位列表，请参阅 Less API。

现在，您可以在操作中使用您的函数了。

```less
@plugin "my-plugin";
.show-me-pi {
  value: pi() * 2;
}
```
您可能已经注意到，插件文件中有一些可用的全局项，即函数注册表（函数对象）和 less 对象。这些都是为了方便使用。

### 插件作用域

通过 `@plugin` at-rule 添加的函数遵守 Less 的范围界定规则。这对于希望在不引入命名冲突的情况下添加功能的 Less 库作者来说非常有用。

例如，您有来自两个第三方库的两个插件，它们都有一个名为 "foo" 的函数。

```less
// lib1.js
// ...
    functions.add('foo', function() {
        return "foo";
    });
// ...

// lib2.js
// ...
    functions.add('foo', function() {
        return "bar";
    });
// ...
```
没关系！您可以选择哪个库的函数创建哪个输出。

```less
.el-1 {
    @plugin "lib1";
    value: foo();
}
.el-2 {
    @plugin "lib2";
    value: foo();
}
```
这将产生：

```less
.el-1 {
    value: foo;
}
.el-2 {
    value: bar;
}
```
对于共享其插件的插件作者来说，这意味着您也可以通过将其置于特定作用域中来有效地创建私有函数。例如，这会导致错误：

```less
.el {
    @plugin "lib1";
}
@value: foo();
```
从 Less 3.0 开始，函数可以返回任何一种 Node 类型，并可以在任何级别调用。

这意味着，在 2.x 中，函数必须是属性值或变量赋值的一部分，因此会产生错误：

```less
.block {
    color: blue;
    my-function-rules();
}
```
在 3.x 中，情况不再如此，函数可以返回 At-Rules、Rulesets、任何其他 Less 节点、字符串和数字（后两者会转换为匿名节点）。

### 空函数

有时，您可能想调用一个函数，但不想输出任何内容（例如存储一个值以备后用）。在这种情况下，只需从函数中返回 `false` 即可。

```less
var collection = [];

functions.add('store', function(val) {
    collection.push(val);  // imma store this for later
    return false;
});
```
```less
@plugin "collections";
@var: 32;
store(@var);
```
以后你可以这样做：

```less
functions.add('retrieve', function(val) {
    return new tree.Value(collection);
});
```
```less
.get-my-values {
    @plugin "collections";
    values: retrieve();   
}
```
### Less.js 插件对象

Less.js 插件应导出一个具有一个或多个上述属性的对象。

```less
{
    /* Called immediately after the plugin is 
     * first imported, only once. */
    install: function(less, pluginManager, functions) { },

/* Called for each instance of your @plugin. */
    use: function(context) { },

/* Called for each instance of your @plugin, 
     * when rules are being evaluated.
     * It's just later in the evaluation lifecycle */
    eval: function(context) { },

/* Passes an arbitrary string to your plugin 
     * e.g. @plugin (args) "file";
     * This string is not parsed for you, 
     * so it can contain (almost) anything */
    setOptions: function(argumentString) { },

/* Set a minimum Less compatibility string
     * You can also use an array, as in [3, 0] */
    minVersion: ['3.0'],

/* Used for lessc only, to explain 
     * options in a Terminal */
    printUsage: function() { },

}
```
`install()` 函数的 PluginManager 实例提供了添加访问者、文件管理器和后处理器的方法。

下面是一些展示不同插件类型的软件仓库示例。
- post-processor: https://github.com/less/less-plugin-clean-css
- visitor: https://github.com/less/less-plugin-inline-urls
- file-manager: https://github.com/less/less-plugin-npm-import

### Pre-Loaded Plugins

虽然 `@plugin` 调用在大多数情况下都很有效，但有时您可能需要在解析开始前加载插件。

请参阅 "使用 Less.js" 部分中的 "[预加载插件](http://www.bixiaguangnian.com/manual/less/1109.html "预加载插件")"，了解如何做到这一点。