编写node 插件

编写插件

插件是社区构建的规则和规则集

咱们推荐使用您本身熟悉的，而且秉承stylelint的编写规则惯例，包括命名、选项、消息、测试和文档。

插件详解

// 小例子
var stylelint = require("stylelint")

var ruleName = "plugin/foo-bar"
var messages =  stylelint.utils.ruleMessages(ruleName, {
  expected: "Expected ...",
})

module.exports = stylelint.createPlugin(ruleName, function(primaryOption, secondaryOptionObject) {
  return function(postcssRoot, postcssResult) {
    var validOptions = stylelint.utils.validateOptions(postcssResult, ruleName, { .. })
    if (!validOptions) { return }
    // ... some logic ...
    stylelint.utils.report({ .. })
  }
})

module.exports.ruleName = ruleName
module.exports.messages = messages
复制代码

您的插件规则命名必须有命名空间，例如：your-namespace/your-rule-name。若是您的插件只提供一个简单的规则或者您不能想到一个很好命名空间，您可简单用`plugin/my-rule来命名。这个命名空间确保了，这个插件的规则不会与核心规则冲突。*请确保你的文档里面，对用户提供了你的插件的规则名字（和命名空间），由于他们须要在他们的配置config里面用到。

stylelint.createPlugin(ruleName, ruleFunction) 能够确保你的插件能与其余规则正确的工做。

为了使你的插件能够和 标准配置格式一块儿正常工做, ruleFunction 能够接受两个参数：第一个是主要选项，第二个是可选对象。

若是您的插件规则支持自动修复, 那么ruleFunction也能够接受第三个参数:上下文（context)。 而且，强烈建议在你的第二个参数配置对象里面支持 disableFix。 这样，当用户对你的规则设置了disableFix选项时，就不会自动修复了。

ruleFunction 能够返回一个函数，这个函数本质上是一个小的PostCSS 插件：它接受两个参数：一个是PostCSS Root (the parsed AST)，另一个是PostCSS LazyResult。因此你能够去了解 PostCSS API.

异步规则

PostCSS插件的异步规则也能够实现。您只须要返回一个您插件函数的实例。

// 异步小例子
var stylelint = require("stylelint")

var ruleName = "plugin/foo-bar-async"
var messages =  stylelint.utils.ruleMessages(ruleName, {
  expected: "Expected ...",
})

module.exports = stylelint.createPlugin(ruleName, function(primaryOption, secondaryOptionObject) {
  return function(postcssRoot, postcssResult) {
    var validOptions = stylelint.utils.validateOptions(postcssResult, ruleName, { .. })
    if (!validOptions) { return }

    return new Promise(function(resolve) {
      // 一些异步的设置
      setTimeout(function() {
        // ... 一些业务逻辑 ...
        stylelint.utils.report({ .. })
        resolve()
      }, 1)
    })
  }
})

module.exports.ruleName = ruleName
module.exports.messages = messages
复制代码

stylelint.utils

stylelint对外暴露一个有用的工具函数，关于这些函数的详细APIs,请参考源码的注释和一些标准规则的例子。

stylelint.utils.report

添加违例列表里面你插件的违例，这样stylelint就就能够报给用户。

不要直接使用PostCSS的node.warn() 方法. 当你使用 stylelint.utils.report的时候，你的插件会遵照禁用范围和其余将来stylelint的特性。这将会提供一个更好的用户体验和更好的匹配stylelint的规则规范。

stylelint.utils.ruleMessages

自定义你消息的来知足stylelint规则规范的格式

stylelint.utils.validateOptions

验证您的规则选项

stylelint.utils.checkAgainstRule

用你本身的规则校验CSS，依照标准的stylelint规范。这个函数对插件和但愿改进、约束与扩展已有stylelint规则功能开发者，是有效的、灵活的。

接受一个对象选项，而且返回一个返回值，这个返回值调用指定规则的警告。这些选项是：

• ruleName: 调用规则的名字。.
• ruleSettings: 设置调用规则的配置， 在.stylelintrc 里的配置对象中，同一格式化.
• root: 根运行这个规则的根node环境.

使用历来自stylelint.utils.report的报出的你的插件规则中的警告，来建立一个新警告

好比，假设你想要建立一个插件，使用一个忽略你的选择预处理器配置的规则的内置列表，来运行at-rule-no-unknown。

const allowableAtRules = [..]

function myPluginRule(primaryOption, secondaryOptions) {
  return (root, result) => {
    const defaultedOptions = Object.assign({}, secondaryOptions, {
      ignoreAtRules: allowableAtRules.concat(options.ignoreAtRules || []),
    })

    stylelint.utils.checkAgainstRule({
      ruleName: 'at-rule-no-unknown',
      ruleSettings: [primaryOption, defaultedOptions],
      root: root
    }, (warning) => {
      stylelint.utils.report({
        message: myMessage,
        ruleName: myRuleName,
        result: result,
        node: warning.node,
        line: warning.line,
        column: warning.column,
      })
    })
  }
}
复制代码

stylelint.rules

全部的规则函数都支持stylelint.rules。这样你能够在现有的规则上针对实际需求来构建。

一个典型的常规使用方式是，在更复杂的规则选项容许条件下编译。例如，也许你的代码库想使用特定的注释指令，来对特殊的样式表自定义规则选项。你能够构建一个插件来检查这些指令，而后运行用正确的选项（或者不是所有运行它们）适当的规则。

全部的规则使用一个公共的签名。他们是一个接受两个参数的函数：一个主选项和一个次选项对象。而且这个函数返回一个带有PostCSS插件签名的函数。

这里有个小插件的小例子，只有当样式表某个地方有特定的@@check-color-hex-case值时运行color-hex-case。

export default stylelint.createPlugin(ruleName, function (expectation) {
  const runColorHexCase = stylelint.rules["color-hex-case"](expectation)
  return (root, result) => {
    if (root.toString().indexOf("@@check-color-hex-case") === -1) return
    runColorHexCase(root, result)
  }
})
复制代码

容许主选项数组

若是你的插件能够接受一个数组做为他的主选项，你能够在你的规则函数上指定设置primaryOptionArray = true的值。更多信息请参考"使用规则"文档

外部帮助模块

除了在"使用规则" 文档中提到的标准解析器, 咱们还推荐使用，在stylelint里面用到的其余的外部模块. 它们包括:

• normalize-selector: 标准化 CSS 选择器.
• postcss-resolve-nested-selector: 在PostCSS虚拟语法树（AST）中提供一个（嵌套）选择器，返回一个解析后的选择器的数组。
• style-search: Search CSS (and CSS-like) strings, with sensitivity to whether matches occur inside strings, comments, and functions.
• style-search: 查询 CSS (和类CSS) 字符串, 敏感匹配出如今字符串、注释和函数的字符串。

请了解一下stylelint的内部工具函数 ，若是你遇到一个你的插件须要的函数，请考虑帮助咱们把它扩展成为一个外部模块。

同版本依赖

你能够，在你插件的package.json文件里面的 peerDependencies键值（注意不是在dependencies键值里面配置，你的插件可使用的stylelint的版本号。这个保证了不一样版本的stylelint不会被意外安装的风险。

例如，下面表示你的插件能够正常使用，依赖stylelint版本7或者版本8。

{
  "peerDependencies": {
    "stylelint": "^7.0.0 || ^8.0.0"
  }
}
复制代码

测试插件

为了测试你的插件，你能够考虑使用和stylelint内部使用的同样的规则测试函数，: stylelint-test-rule-tape。

插件包

使用一个简单的模块来提供多项规则，简单暴露一个插件对象集合的数组（而不是一个对象）。

共享插件和插件包

• 在你的package.json文件里面，请使用stylelint-plugin关键字。
• 一旦你的插件被发布了，请给咱们提交一个Pull Request，来添加你的插件到插件列表。