Zum Hauptinhalt springen

API

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

Wenn Sie Prettier programmatisch ausführen möchten, finden Sie auf dieser Seite die entsprechenden Informationen.

import * as prettier from "prettier";

Unsere öffentlichen APIs sind alle asynchron. Wenn Sie aus bestimmten Gründen eine synchrone Version benötigen, können Sie @prettier/sync ausprobieren.

prettier.format(source, options)​

format dient zum Formatieren von Text mit Prettier. options.parser muss entsprechend der zu formatierenden Sprache gesetzt werden (siehe Liste verfügbarer Parser). Alternativ kann options.filepath angegeben werden, damit Prettier den Parser anhand der Dateiendung ableitet. Weitere Optionen können zur Überschreibung der Standardeinstellungen bereitgestellt werden.

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

prettier.check(source [, options])​

check überprüft, ob die Datei mit den gegebenen Optionen durch Prettier formatiert wurde, und gibt ein Promise<boolean> zurück. Dies entspricht dem Parameter --check oder --list-different in der CLI und ist nützlich für den Einsatz von Prettier in CI-Szenarien.

prettier.formatWithCursor(source [, options])​

formatWithCursor formatiert sowohl den Code als auch übersetzt eine Cursorposition vom unformatierten zum formatierten Code. Dies ist nützlich für Editor-Integrationen, um zu verhindern, dass sich der Cursor bei der Codeformatierung verschiebt.

Die Option cursorOffset sollte angegeben werden, um die Cursorposition zu definieren.

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

prettier.resolveConfig(fileUrlOrPath [, options])​

resolveConfig kann verwendet werden, um die Konfiguration für eine bestimmte Quelldatei aufzulösen, indem ihr Pfad oder URL als erstes Argument übergeben wird. Die Konfigurationssuche beginnt im Verzeichnis des Dateistandorts und durchläuft die übergeordneten Verzeichnisse. Alternativ können Sie direkt den Pfad der Konfigurationsdatei als options.config übergeben, wenn Sie nicht suchen möchten. Es wird ein Promise zurückgegeben, das sich auflöst zu:

  • Einem Options-Objekt, falls eine Konfigurationsdatei gefunden wurde.

  • null, falls keine Datei gefunden wurde.

Das Promise wird abgelehnt, wenn ein Fehler beim Parsen der Konfigurationsdatei auftrat.

Wenn options.useCache auf false gesetzt ist, wird der Cache vollständig umgangen.

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

Wenn options.editorconfig auf true gesetzt ist und eine .editorconfig-Datei in Ihrem Projekt vorhanden ist, wird Prettier diese parsen und ihre Eigenschaften in die entsprechende Prettier-Konfiguration umwandeln. Diese Konfiguration wird durch .prettierrc usw. überschrieben. Derzeit werden folgende EditorConfig-Eigenschaften unterstützt:

  • end_of_line

  • indent_style

  • indent_size/tab_width

  • max_line_length

prettier.resolveConfigFile([fileUrlOrPath])​

resolveConfigFile kann verwendet werden, um den Pfad der Prettier-Konfigurationsdatei zu finden, die bei der Konfigurationsauflösung verwendet wird (d.h. beim Aufruf von resolveConfig). Es wird ein Promise zurückgegeben, das sich auflöst zu:

  • Dem Pfad der Konfigurationsdatei.

  • null, falls keine Datei gefunden wurde.

Das Promise wird abgelehnt, wenn ein Fehler beim Parsen der Konfigurationsdatei auftrat.

Die Suche beginnt bei process.cwd() oder im Verzeichnis von fileUrlOrPath, falls angegeben.

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

prettier.clearConfigCache()​

Wenn Prettier Konfigurationsdateien und Plugins lädt, wird die Dateisystemstruktur zur Leistungsoptimierung zwischengespeichert. Diese Funktion löscht den Cache. Im Allgemeinen ist dies nur für Editor-Integrationen notwendig, die wissen, dass sich das Dateisystem seit der letzten Formatierung geändert hat.

prettier.getFileInfo(fileUrlOrPath [, options])​

getFileInfo kann von Editor-Erweiterungen verwendet werden, um zu entscheiden, ob eine bestimmte Datei formatiert werden muss. Diese Methode gibt ein Promise zurück, das zu einem Objekt mit folgenden Eigenschaften aufgelöst wird:

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

Das Promise wird abgelehnt, wenn der Typ von fileUrlOrPath nicht string oder URL ist.

Die Einstellung von options.ignorePath (string | URL | (string | URL)[]) und options.withNodeModules (boolean) beeinflusst den Wert von ignored (standardmäßig false).

Wenn die angegebene fileUrlOrPath ignoriert wird, ist inferredParser immer null.

Das Bereitstellen von Plugin-Pfaden in options.plugins ((string | URL | Plugin)[]) hilft dabei, inferredParser für Dateien zu extrahieren, die nicht vom Prettier-Kern unterstützt werden.

Wenn options.resolveConfig (boolean, Standard true) auf false gesetzt wird, sucht Prettier nicht nach Konfigurationsdateien. Dies kann nützlich sein, wenn diese Funktion nur zur Überprüfung verwendet wird, ob eine Datei ignoriert wird.

prettier.getSupportInfo()​

Gibt ein Promise zurück, das zu einem Objekt aufgelöst wird, das die Optionen, Parser, Sprachen und Dateitypen darstellt, die Prettier unterstützt.

Die Support-Informationen sehen wie folgt aus:

{
  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[];
    isSupported?(options: { filepath: string }): boolean;
  }>;
}
Hinweis

Prettier kann nicht sicherstellen, dass filepath auf dem Datenträger existiert.
Bei Verwendung über APIs (z. B. prettier.format()) kann Prettier auch nicht sicherstellen, dass es sich um einen gültigen Pfad handelt.

Benutzerdefinierte Parser-API (entfernt)​

Entfernt in v3.0.0 (ersetzt durch die Plugin-API)

Bevor Plugins existierten, hatte Prettier eine ähnliche, aber eingeschränktere Funktion namens benutzerdefinierte Parser. Diese wurde in v3.0.0 entfernt, da ihre Funktionalität eine Teilmenge der Plugin-API darstellte. Wenn Sie sie verwendet haben, sehen Sie sich das folgende Beispiel zur Migration an.

❌ Benutzerdefinierte Parser-API (entfernt):

import { format } from "prettier";

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

✔️ Plugin-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"
Hinweis

Generell werden Codemods auf diese Weise nicht empfohlen. Prettier verwendet Positionsdaten von AST-Knoten für viele Dinge wie das Beibehalten von Leerzeilen und das Anhängen von Kommentaren. Wenn der AST nach dem Parsen modifiziert wird, geraten die Positionsdaten oft außer Sync, was zu unvorhersehbaren Ergebnissen führen kann. Ziehen Sie die Verwendung von jscodeshift in Betracht, wenn Sie Codemods benötigen.

Im Rahmen der entfernten benutzerdefinierten Parser-API war es zuvor möglich, einen Pfad zu einem Modul, das eine parse-Funktion exportiert, über die --parser-Option zu übergeben. Verwenden Sie stattdessen die --plugin-CLI-Option oder die plugins-API-Option, um Plugins zu laden.