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，该 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，该 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 选项来加载插件。