編寫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，來添加你的插件到插件列表。