編寫node 外掛

會會會發表於2019-05-10

編寫外掛

外掛是社群構建的規則和規則集

我們推薦使用您自己熟悉的，並且秉承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，來新增你的外掛到外掛列表。

相關文章