API · Prettier 繁體中文

如果您想以程式化的方式執行 Prettier，請查看此頁面。

import * as prettier from "prettier";

我們公開的 API 都是非同步的，如果您必須使用同步版本，您可以嘗試 @prettier/sync。

`prettier.format(source, options)`

format 用於使用 Prettier 格式化文字。必須根據您正在格式化的語言設定 options.parser（請參閱可用解析器的清單）。或者，可以指定 options.filepath 讓 Prettier 從檔案副檔名推斷解析器。可以提供其他選項來覆蓋預設值。

await prettier.format("foo ( );", { semi: false, parser: "babel" });
// -> 'foo()\n'

`prettier.check(source [, options])`

check 檢查檔案是否已使用指定的選項透過 Prettier 格式化，並返回一個 Promise<boolean>。這類似於 CLI 中的 --check 或 --list-different 參數，適用於在 CI 情境中運行 Prettier。

`prettier.formatWithCursor(source [, options])`

formatWithCursor 會格式化程式碼，並將未格式化程式碼中的游標位置轉換為格式化程式碼中的游標位置。這對於編輯器整合很有用，可以防止在格式化程式碼時游標移動。

應該提供 cursorOffset 選項來指定游標的位置。

await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });
// -> { formatted: '1;\n', cursorOffset: 1 }

`prettier.resolveConfig(fileUrlOrPath [, options])`

resolveConfig 可用於解析給定原始程式檔的設定，將其路徑或 url 作為第一個參數傳遞。設定搜尋將從檔案所在目錄開始，並繼續向上搜尋目錄。或者，如果您不想搜尋設定檔，可以直接將設定檔的路徑作為 options.config 傳遞。返回的 promise 將解析為：

一個選項物件，如果找到設定檔。
null，如果找不到檔案。

如果解析設定檔時發生錯誤，promise 將被拒絕。

如果 options.useCache 為 false，將會略過所有快取。

const text = await fs.readFile(filePath, "utf8");
const options = await prettier.resolveConfig(filePath);
const formatted = await prettier.format(text, options);

如果 options.editorconfig 為 true 且您的專案中有一個 .editorconfig 檔案，Prettier 將會解析它並將其屬性轉換為相對應的 Prettier 設定。此設定將會被 .prettierrc 等覆蓋。目前支援以下 EditorConfig 屬性：

end_of_line
indent_style
indent_size/tab_width
max_line_length

`prettier.resolveConfigFile([fileUrlOrPath])`

resolveConfigFile 可用於查找解析設定時（即呼叫 resolveConfig 時）將使用的 Prettier 設定檔的路徑。返回的 promise 將解析為：

設定檔的路徑。
null，如果找不到檔案。

如果解析設定檔時發生錯誤，promise 將被拒絕。

搜尋從 process.cwd() 開始，如果提供 fileUrlOrPath，則從 fileUrlOrPath 的目錄開始。

const configFile = await prettier.resolveConfigFile(filePath);
// you got the path of the configuration file

`prettier.clearConfigCache()`

當 Prettier 載入設定檔和插件時，檔案系統結構會被快取以提高效能。這個函式將會清除快取。通常只有在編輯器整合知道檔案系統自上次格式化後已更改時才需要使用這個函式。

`prettier.getFileInfo(fileUrlOrPath [, options])`

編輯器擴充套件可以使用 getFileInfo 來決定是否需要格式化特定檔案。這個方法會回傳一個 Promise，它會解析為一個具有以下屬性的物件：

{
  ignored: boolean;
  inferredParser: string | null;
}

如果 fileUrlOrPath 的類型不是 string 或 URL，Promise 將會被拒絕。

設定 options.ignorePath (string | URL | (string | URL)[]) 和 options.withNodeModules (boolean) 會影響 ignored 的值（預設為 false）。

如果指定的 fileUrlOrPath 被忽略，則 inferredParser 永遠為 null。

在 options.plugins (string[]) 中提供插件路徑有助於為 Prettier 核心不支援的檔案提取 inferredParser。

將 options.resolveConfig（boolean，預設值為 true）設定為 false 時，Prettier 不會搜尋設定檔。如果此函式僅用於檢查檔案是否被忽略，這會很有用。

`prettier.getSupportInfo()`

回傳一個 Promise，它會解析為一個表示 Prettier 支援的選項、解析器、語言和檔案類型的物件。

支援資訊如下所示：

{
  languages: Array<{
    name: string;
    parsers: string[];
    group?: string;
    tmScope?: string;
    aceMode?: string;
    codemirrorMode?: string;
    codemirrorMimeType?: string;
    aliases?: string[];
    extensions?: string[];
    filenames?: string[];
    linguistLanguageId?: number;
    vscodeLanguageIds?: string[];
  }>;
}

自訂解析器 API（已移除）

在 v3.0.0 中移除（由插件 API 取代）

在插件出現之前，Prettier 有一個類似但功能更有限的功能，稱為自訂解析器。它已在 v3.0.0 中移除，因為它的功能是插件 API 的一個子集。如果您使用過它，請查看以下範例，了解如何遷移。

❌ 自訂解析器 API（已移除）

import { format } from "prettier";

format("lodash ( )", {
  parser(text, { babel }) {
    const ast = babel(text);
    ast.program.body[0].expression.callee.name = "_";
    return ast;
  },
});
// -> "_();\n"

✔️ 插件 API

import { format } from "prettier";
import * as prettierPluginBabel from "prettier/plugins/babel";

const myCustomPlugin = {
  parsers: {
    "my-custom-parser": {
      async parse(text) {
        const ast = await prettierPluginBabel.parsers.babel.parse(text);
        ast.program.body[0].expression.callee.name = "_";
        return ast;
      },
      astFormat: "estree",
    },
  },
};

await format("lodash ( )", {
  parser: "my-custom-parser",
  plugins: [myCustomPlugin],
});
// -> "_();\n"

注意：總體而言，不建議以這種方式進行程式碼修改。Prettier 使用 AST 節點的位置數據來處理許多事情，例如保留空行和附加註釋。在解析後修改 AST 時，位置數據通常會不同步，這可能會導致不可預測的結果。如果您需要程式碼修改，請考慮使用 jscodeshift。

作為已移除的自訂解析器 API 的一部分，以前可以透過 --parser 選項傳遞一個模組的路徑，該模組匯出一個 parse 函式。請改用 --plugin CLI 選項或 plugins API 選項來載入插件。