编写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，来添加你的插件到插件列表。

转载于:https://juejin.im/post/5cd57059e51d456e2a64b387