自訂處理器

您也可以建立自訂處理器，告訴 ESLint 如何處理標準 JavaScript 以外的檔案。例如，您可以編寫自訂處理器從 Markdown 檔案中提取和處理 JavaScript（@eslint/markdown 包含用於此目的的自訂處理器）。

自訂處理器規範

為了建立自訂處理器，從您的模組匯出的物件必須符合以下介面

const plugin = {

    meta: {
        name: "eslint-plugin-example",
        version: "1.2.3"
    },
    processors: {
        "processor-name": {
            meta: {
                name: "eslint-processor-name",
                version: "1.2.3"
            },
            // takes text of the file and filename
            preprocess(text, filename) {
                // here, you can strip out any non-JS content
                // and split into multiple strings to lint

                return [ // return an array of code blocks to lint
                    { text: code1, filename: "0.js" },
                    { text: code2, filename: "1.js" },
                ];
            },

            // takes a Message[][] and filename
            postprocess(messages, filename) {
                // `messages` argument contains two-dimensional array of Message objects
                // where each top-level array item contains array of lint messages related
                // to the text that was returned in array from preprocess() method

                // you need to return a one-dimensional array of the messages you want to keep
                return [].concat(...messages);
            },

            supportsAutofix: true // (optional, defaults to false)
        }
    }
};

// for ESM
export default plugin;

// OR for CommonJS
module.exports = plugin;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

preprocess 方法將檔案內容和檔名作為引數，並返回要檢查的程式碼區塊陣列。程式碼區塊將被個別檢查，但仍會註冊到檔名。

程式碼區塊有兩個屬性 text 和 filename。text 屬性是區塊的內容，而 filename 屬性是區塊的名稱。區塊的名稱可以是任何內容，但應包含副檔名，這會告訴 ESLint 如何處理目前的區塊。ESLint 會檢查專案設定中符合的 files 條目，以判斷是否應檢查程式碼區塊。

由外掛程式決定是否只需要返回非 JavaScript 檔案的一個部分，還是多個部分。例如，在處理 .html 檔案的情況下，您可能只想透過合併所有腳本來返回陣列中的一個項目。但是，對於 .md 檔案，您可以返回多個項目，因為每個 JavaScript 區塊可能是獨立的。

postprocess 方法接受一個二維的檢查訊息陣列和檔名。輸入陣列中的每個項目都對應於從 preprocess 方法返回的部分。postprocess 方法必須調整所有錯誤的位置，使其對應於原始、未處理程式碼中的位置，並將其彙總為單一扁平陣列並返回。

回報的問題在每個檢查訊息中都有以下位置資訊

type LintMessage = {

  /// The 1-based line number where the message occurs.
  line?: number;

   /// The 1-based column number where the message occurs.
  column?: number;

  /// The 1-based line number of the end location.
  endLine?: number;

  /// The 1-based column number of the end location.
  endColumn?: number;

  /// If `true`, this is a fatal error.
  fatal?: boolean;

  /// Information for an autofix.
  fix: Fix;

  /// The error message.
  message: string;

  /// The ID of the rule which generated the message, or `null` if not applicable.
  ruleId: string | null;

  /// The severity of the message.
  severity: 0 | 1 | 2;

  /// Information for suggestions.
  suggestions?: Suggestion[];
};

type Fix = {
    range: [number, number];
    text: string;
}

type Suggestion = {
    desc?: string;
    messageId?: string;
    fix: Fix;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

預設情況下，即使在命令列上啟用 --fix 標誌時，ESLint 在使用自訂處理器時也不會執行自動修復。若要允許 ESLint 在使用您的處理器時自動修復程式碼，您應該採取以下額外步驟

更新 postprocess 方法以額外轉換回報問題的 fix 屬性。所有可自動修復的問題都有一個 fix 屬性，這是一個具有以下綱要的物件
```
{
    range: [number, number],
    text: string
}
1
2
3
4
```
range 屬性包含程式碼中的兩個索引，指的是要取代的連續文字區段的開始和結束位置。text 屬性指的是將取代給定範圍的文字。

在初始問題清單中，fix 屬性將參考已處理 JavaScript 中的修復。postprocess 方法應該轉換物件，使其參考原始、未處理檔案中的修復。
在處理器中新增 supportsAutofix: true 屬性。

您可以在單一外掛程式中同時擁有規則和自訂處理器。您也可以在一個外掛程式中擁有多個處理器。為了支援多個副檔名，請將每個副檔名新增至 processors 元素，並將它們指向同一個物件。

如何使用 `meta` 物件

meta 物件可協助 ESLint 快取使用處理器的設定，並提供更友善的偵錯訊息。

外掛程式 `meta` 物件

外掛程式 meta 物件提供有關外掛程式本身的資訊。當使用字串格式 plugin-name/processor-name 指定處理器時，ESLint 會自動使用外掛程式 meta 來產生處理器的名稱。這是處理器的最常見情況。

範例

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        processor: "example/processor-name"
    },
    // ... other configs
];
1
2
3
4
5
6
7
8
9
10
11
12

在此範例中，處理器名稱為 "example/processor-name"，這將是序列化設定所使用的值。

處理器 `meta` 物件

每個處理器也可以指定自己的 meta 物件。當處理器物件直接傳遞至設定中的 processor 時，會使用此資訊。在這種情況下，ESLint 不知道處理器屬於哪個外掛程式。meta.name 屬性應符合處理器名稱，而 meta.version 屬性應符合處理器的 npm 套件版本。完成此操作最簡單的方法是從您的 package.json 中讀取此資訊。

範例

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    {
        processor: example.processors["processor-name"]
    },
    // ... other configs
];
1
2
3
4
5
6
7
8
9

在此範例中，直接指定 example.processors["processor-name"] 會使用處理器自己的 meta 物件，必須定義該物件，以確保在處理器不是透過外掛程式名稱參考時能夠正確處理。

為什麼需要兩個 Meta 物件

建議外掛程式和每個處理器都提供各自的 meta 物件。這可確保依賴 meta 物件的功能，例如 --print-config 和 --cache，無論處理器在設定中如何指定都能正常運作。

在設定檔中指定處理器

為了在設定檔中使用外掛程式的處理器，請匯入外掛程式並將其包含在 plugins 鍵中，指定命名空間。然後，使用該命名空間在 processor 設定中參考處理器，如下所示

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    {
        plugins: {
            example
        },
        processor: "example/processor-name"
    }
];
1
2
3
4
5
6
7
8
9
10
11

如需更多詳細資訊，請參閱外掛程式設定文件中的指定處理器。

編輯此頁面

自訂處理器