Transformer

Transformer 外掛會轉換單一資源，以編譯它、找出相依性，或將它轉換成不同的格式。許多 transformer 是包裝在其他工具（例如編譯器和預處理器）周圍，並負責將它們整合到 Parcel 中。

轉換資源

有一個必要的函式必須傳遞給 Transformer 建構函式：transform。此函式會接收一個 MutableAsset 物件，它代表一個檔案。可以擷取資源的原始碼或內容，以及任何關聯的原始碼地圖（請見下方）。然後，transformer 可以用某種方式轉換此內容，並將編譯結果設定回資源。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    // Retrieve the asset's source code and source map.
    let source = await asset.getCode();
    let sourceMap = await asset.getMap();

    // Run it through some compiler, and set the results 
    // on the asset.
    let {code, map} = compile(source, sourceMap);
    asset.setCode(code);
    asset.setMap(map);

    // Return the asset
    return [asset];
  }
});

載入設定

應該在 Transformer 外掛的 loadConfig 方法中載入使用者的專案設定。請參閱 載入設定，以取得如何執行此操作的詳細資訊。

變更資源類型

變壓器可以將資產從一種格式轉換為另一種格式，例如從 TypeScript 轉換為 JavaScript。若要執行此操作，請將資產的 type 屬性設定為新的檔案類型 (例如 js)。然後，資產將由與新類型相符的管道處理。請參閱 Parcel 組態文件中的 變壓器 以取得詳細資訊。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();

    let result = compile(code);
    asset.type = 'js';
    asset.setCode(result);

    return [asset];
  }
});

環境

資產與 Environment 關聯，其中說明應如何編譯資產。相同的資產可以用不同的環境處理多次，例如，在為現代和舊有目標建置時。如果可能，變壓器外掛程式在編譯程式碼時應考慮環境，以確保結果在目標中運作並針對目標進行最佳化。請參閱 目標 以取得詳細資訊。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();

    let result = asset.env.isBrowser()
      ? compileForBrowser(code, asset.engines.browser)
      : compileForNode(code, asset.engines.node);

    asset.setCode(result);
    return [asset];
  }
});

請參閱 Environment API 文件以取得可用屬性的詳細資訊。

新增相依性

除了轉換資產的內容外，變壓器外掛程式還負責找出程式碼中的相依性，以便 Parcel 也能處理這些相依性。有些變壓器不需要擔心這一點，因為其他變壓器會在之後執行並執行此操作 (例如預設的 JavaScript 變壓器)。如果您要新增對 Parcel 支援的現有語言之一未編譯的新語言的支援，或以其他方式在編譯的程式碼之外引入相依性，您需要將它們新增到資產中。

可以使用 addDependency 方法將相依性新增到資產，傳遞 DependencyOptions 物件。有兩個必要的參數：specifier，它是描述相依性位置的字串，以及 specifierType，它描述應如何詮釋 specifier。請參閱 相依性解析 以取得詳細資訊。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();
    let deps = code.matchAll(/import "(.*?)"/g);
    
    for (let dep of deps) {
      asset.addDependency({
        specifier: dep,
        specifierType: 'esm'
      });
    }

    return [asset];
  }
});

影響組合

指定依賴項的方式會影響其打包方式。預設情況下，依賴項會打包在一起，成為同一個輸出檔案。依賴項的 priority 屬性可以指定是延遲載入，還是與依賴於它的資產並行載入。例如，JavaScript 中的動態 import() 會以 lazy 優先順序載入依賴項。請參閱 程式碼分割。

bundleBehavior 屬性進一步控制依賴項的打包方式。例如，可以將依賴項分隔到新的套件中，但透過將 bundleBehavior 設為 inline，將其內嵌到父項中。請參閱 套件內嵌。

請參閱 DependencyOptions，進一步了解每個可用選項的詳細資訊。

URL 依賴項

在某些語言中，依賴項會透過 URL 參照其他檔案。在編譯後的程式碼中，這些 URL 參照需要更新，才能指向最終的套件名稱。然而，當資產正在轉換時，套件名稱尚未得知。

addDependency 會傳回唯一的依賴項 ID。這可以作為最終套件 URL 的佔位符，置於已轉換的資產內容中，而當 URL 得知時，稍後會由 Packager 取代。

作為捷徑，addURLDependency 方法會建立一個依賴項，其中 specifierType 設為 url，而 priority 設為 lazy（以建立獨立的套件）。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();
    let result = code.replace(/import "(.*?)"/g, (m, dep) => {
      // Replace the original specifier with a dependency id 
      // as a placeholder. This will be replaced later with 
      // the final bundle URL.
      let depId = asset.addURLDependency(dep);
      return `import "${depId}"`;
    });

    asset.setCode(result);
    return [asset];
  }
});

重複使用 AST

如果多個 Transformer 外掛程式在資產上依序執行，如果它們可以重複使用相同的已剖析 AST，那麼剖析、轉換和產生程式碼會很浪費。Parcel 透過將 transform 函式分割成多個部分，來促進 AST 共享

• canReuseAST – 如果前一個 Transformer 外掛程式有提供 AST，則會在下一位 Transformer 中將 AST 傳遞給這個方法（如果可用）。它應該檢查 AST 的 type 和 version，以確定是否可以重複使用。如果傳回 true，則不會呼叫 parse 方法，且會重複使用 AST。如果傳回 false，則會呼叫前一個 Transformer 的 generate 函式，且會使用結果呼叫下一個 Transformer 的 parse 函式。
• parse – 如果沒有提供 AST，或 canReuseAST 傳回 false，則會呼叫 Transformer 的 parse 函式。它應該傳回一個 AST 物件，用以描述 AST 的類型、版本和內容。
• generate – 如果下一個 Transformer 無法重複使用 AST，或這是管線中的最後一個 Transformer，則會使用 AST 物件呼叫 generate。應該傳回一個包含已產生內容和原始碼對應表的結果物件。

import {Transformer} from '@parcel/plugin';
import semver from 'semver';

export default new Transformer({
  async canReuseAST({ast}) {
    return ast.type === 'my-compiler' 
      && semver.satisfies(ast.version, '^1.0.0');
  },
  async parse({asset}) {
    return {
      type: 'my-compiler',
      version: '1.0.0',
      program: parse(await asset.getCode())
    };
  },
  async transform({asset}) {
    let ast = await asset.getAST();

    let compiledAST = compile(ast.program);
    asset.setAST({
      type: 'my-compiler',
      version: '1.0.0',
      program: compiledAST
    });

    return [asset];
  },
  async generate({ast}) {
    let {content, map} = generate(ast.program);
    return {
      content,
      map
    };
  }
});

原始碼對應表

原始碼對應表可協助開發人員在瀏覽器中偵錯已編譯和已套件化的程式碼，方法是將已編譯程式碼中的位置對應回原始程式碼。如果可能，Transformer 外掛程式應該在轉換其內容時將原始碼對應表新增到資產中。由於資產可能由多個 Transformer 處理，因此除了其內容之外，您還應該轉換資產中包含的現有原始碼對應表。

Parcel 使用 @parcel/source-map 函式庫來處理原始碼對應表。請參閱 原始碼對應表，以取得有關如何使用它的更多詳細資訊。您可能需要將傳遞給其他工具的原始碼對應表轉換成其他工具的格式。

import {Transformer} from '@parcel/plugin';
import SourceMap from '@parcel/source-map';

export default new Transformer({
  async transform({asset, options}) {
    let source = await asset.getCode();
    let sourceMap = await asset.getMap();

    // Convert the input source map to JSON.
    let result = compile(source, sourceMap.toVLQ());
    asset.setCode(result.code);

    // Convert returned JSON source map to a Parcel SourceMap.
    let map = new SourceMap(options.projectRoot);
    map.addVLQMap(result.map);
    asset.setMap(map);

    return [asset];
  }
});

二進位資料

除了文字原始碼之外，Transformer 也可以處理二進位內容。這可以使用 Buffer 或 串流 來完成。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    let buffer = await asset.getBuffer();

    let result = transform(buffer);
    asset.setBuffer(result);

    return [asset];
  }
});

查詢參數

資產可能會被具有 查詢參數 的依賴項所參照。這些參數會指定轉換器在編譯或轉換資產時要使用的選項。例如，Parcel 影像轉換器 會使用查詢參數來讓使用者指定要將影像轉換成的寬度、高度和格式。相同的資產可能會使用不同的查詢參數編譯多次。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    let buffer = await asset.getBuffer();

    let result = resize(
      buffer,
      asset.query.width,
      asset.query.height
    );

    asset.setBuffer(result);
    return [asset];
  }
});

傳回多個資產

到目前為止，所有範例都顯示如何轉換單一資產。然而，有時一個檔案可能包含多個不同的資產。例如，在 HTML 中有內嵌的 <script> 和 <style> 元素，應該透過它們自己的獨立 Parcel 管線來處理。針對此情況，Parcel 允許從轉換器傳回多個資產。

若要建立新的資產，請傳回 TransformerResult 物件的陣列。這些物件必須有 type 和 content，但也可以有自己的依賴項，以及許多與 Asset 物件相同的選項。

通常，原始資產應與它可能有的任何子資產一起傳回。父項可以透過指定 uniqueKey 屬性並將其參照為依賴項的 specifier 來建立對子項的依賴項。這允許建立實際上不存在於檔案系統中的「虛擬」資產，但可以像它們存在一樣被參照。

import {Transformer} from '@parcel/plugin';

export default new Transformer({
  async transform({asset}) {
    let code = await asset.getCode();

    // Extract inline assets to return in addition to this asset.
    let assets = [asset];

    let uniqueKey = `${asset.id}-style`;
    assets.push({
      type: 'css',
      content: '...',
      uniqueKey,
      bundleBehavior: 'inline'
    });

    // Add a dependency, using the uniqueKey as a specifier.
    asset.addDependency({
      specifier: uniqueKey,
      specifierType: 'esm'
    });

    return assets;
  }
});

相關 API

type DependencyOptions = {|

  +specifier: DependencySpecifier,

  +specifierType: SpecifierType,

  +priority?: DependencyPriority,

  +bundleBehavior?: BundleBehavior,

  +needsStableName?: boolean,

  +isOptional?: boolean,

  +loc?: SourceLocation,

  +env?: EnvironmentOptions,

  +packageConditions?: Array<string>,

  +meta?: Meta,

  +pipeline?: string,

  +resolveFrom?: FilePath,

  +range?: SemverRange,

  +symbols?: $ReadOnlyMap<Symbol, {|
    local: Symbol,
    loc: ?SourceLocation,
    isWeak: boolean,
    meta?: Meta,
  |}>,

|}

interface Dependency {

  +id: string,

  +specifier: DependencySpecifier,

  +specifierType: SpecifierType,

  +priority: DependencyPriority,

  +bundleBehavior: ?BundleBehavior,

  +needsStableName: boolean,

  +isOptional: boolean,

  +isEntry: boolean,

  +loc: ?SourceLocation,

  +env: Environment,

  +packageConditions: ?Array<string>,

  +meta: Meta,

  +target: ?Target,

  +sourceAssetId: ?string,

  +sourcePath: ?FilePath,

  +sourceAssetType: ?string,

  +resolveFrom: ?FilePath,

  +range: ?SemverRange,

  +pipeline: ?string,

  +symbols: MutableDependencySymbols,

}

type ASTGenerator = {|

  type: string,

  version: Semver,

|}

interface BaseAsset {

  +id: string,

  +fs: FileSystem,

  +filePath: FilePath,

  +type: string,

  +query: URLSearchParams,

  +env: Environment,

  +isSource: boolean,

  +meta: Meta,

  +bundleBehavior: ?BundleBehavior,

  +isBundleSplittable: boolean,

  +sideEffects: boolean,

  +uniqueKey: ?string,

  +astGenerator: ?ASTGenerator,

  +pipeline: ?string,

  +symbols: AssetSymbols,

  getAST(): Promise<?AST>,

  getCode(): Promise<string>,

  getBuffer(): Promise<Buffer>,

  getStream(): Readable,

  getMap(): Promise<?SourceMap>,

  getMapBuffer(): Promise<?Buffer>,

  getDependencies(): $ReadOnlyArray<Dependency>,

}

interface MutableAsset extends BaseAsset {

  type: string,

  bundleBehavior: ?BundleBehavior,

  isBundleSplittable: boolean,

  sideEffects: boolean,

  +symbols: MutableAssetSymbols,

  addDependency(DependencyOptions): string,

  addURLDependency(url: string, opts: $Shape<DependencyOptions>): string,

  invalidateOnFileChange(FilePath): void,

  invalidateOnFileCreate(FileCreateInvalidation): void,

  invalidateOnEnvChange(string): void,

  setCode(string): void,

  setBuffer(Buffer): void,

  setStream(Readable): void,

  setAST(AST): void,

  isASTDirty(): boolean,

  setMap(?SourceMap): void,

  setEnvironment(opts: EnvironmentOptions): void,

}

interface Asset extends BaseAsset {

  +stats: Stats,

}

interface Config {

  +isSource: boolean,

  +searchPath: FilePath,

  +env: Environment,

  invalidateOnFileChange(FilePath): void,

  invalidateOnFileCreate(FileCreateInvalidation): void,

  invalidateOnEnvChange(string): void,

  invalidateOnStartup(): void,

  invalidateOnBuild(): void,

  addDevDependency(DevDepOptions): void,

  setCacheKey(string): void,

  getConfig<T>(filePaths: Array<FilePath>, options?: {|
    packageKey?: string,
    parse?: boolean,
    exclude?: boolean,
  |}): Promise<?ConfigResultWithFilePath<T>>,

  getConfigFrom<T>(searchPath: FilePath, filePaths: Array<FilePath>, options?: {|
    packageKey?: string,
    parse?: boolean,
    exclude?: boolean,
  |}): Promise<?ConfigResultWithFilePath<T>>,

  getPackage(): Promise<?PackageJSON>,

}

type GenerateOutput = {|

  +content: Blob,

  +map?: ?SourceMap,

|}

type TransformerResult = {|

  +type: string,

  +content?: ?Blob,

  +ast?: ?AST,

  +map?: ?SourceMap,

  +dependencies?: $ReadOnlyArray<DependencyOptions>,

  +env?: EnvironmentOptions | Environment,

  +bundleBehavior?: ?BundleBehavior,

  +isBundleSplittable?: boolean,

  +meta?: Meta,

  +pipeline?: ?string,

  +sideEffects?: boolean,

  +symbols?: $ReadOnlyMap<Symbol, {|
    local: Symbol,
    loc: ?SourceLocation,
  |}>,

  +uniqueKey?: ?string,

|}

type ResolveOptions = {|

  +specifierType?: SpecifierType,

  +packageConditions?: Array<string>,

|}

type ResolveFn = (from: FilePath, to: string, options?: ResolveOptions) => Promise<FilePath>;

type Transformer<ConfigType> = {|

  loadConfig?: ({|
    config: Config,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Promise<ConfigType> | ConfigType,

  canReuseAST?: ({|
    ast: AST,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => boolean,

  parse?: ({|
    asset: Asset,
    config: ConfigType,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<?AST>,

  transform({|
    asset: MutableAsset,
    config: ConfigType,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<Array<TransformerResult | MutableAsset>>,

  postProcess?: ({|
    assets: Array<MutableAsset>,
    config: ConfigType,
    resolve: ResolveFn,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<Array<TransformerResult>>,

  generate?: ({|
    asset: Asset,
    ast: AST,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Async<GenerateOutput>,

|}