转换器

转换器插件转换单个资产以编译它，发现依赖项或将其转换为不同的格式。许多转换器是围绕其他工具（如编译器和预处理器）的包装器，负责将它们与 Parcel 集成。

转换资产

必须传递给 Transformer 构造函数的一个必需函数是：transform。此函数接收一个 MutableAsset 对象，该对象表示一个文件。可以检索资产的源代码或内容，以及任何关联的源映射（参见下文）。然后，转换器可以以某种方式转换此内容，并将编译后的结果设置回资产。

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 相关联，该环境描述了如何编译资产。同一个资产可能会使用不同的环境进行多次处理，例如，在为现代和传统目标构建时。如果可能，Transformer 插件在编译代码时应考虑环境，以确保结果在目标中有效并针对目标进行了优化。有关详细信息，请参见 目标。

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 文档。

添加依赖项

除了转换资产的内容外，Transformer 插件还负责发现代码中的依赖项，以便 Parcel 也能处理它们。一些转换器不需要担心这个问题，因为另一个转换器将在之后运行并执行它（例如，默认的 JavaScript 转换器）。如果您正在添加对 Parcel 不支持的现有语言的新语言的支持，或者以其他方式引入了编译代码之外的依赖项，则需要将它们添加到资产中。

可以使用 addDependency 方法将依赖项添加到资产中，传递一个 DependencyOptions 对象。有两个必需的参数：specifier，它是一个描述依赖项位置的字符串，以及 specifierType，它描述了如何解释说明符。有关详细信息，请参见 依赖关系解析。

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 已知，它将被打包器替换。

作为一种快捷方式，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 的 type 和 version 以确定是否可以重用它。如果它返回 true，则不会调用 parse 方法，并且 AST 会被重用。如果它返回 false，则调用上一个 Transformer 的 generate 函数，并且下一个 Transformer 的 parse 函数将使用结果进行调用。
• parse – 如果 AST 不可用，或者 canReuseAST 返回 false，则调用 Transformer 的 parse 函数。它应该返回一个 AST 对象，该对象描述 AST 的类型、版本和内容。
• generate – 如果下一个 Transformer 不能重用 AST，或者这是管道中的最后一个 Transformer，则将使用 AST 对象调用 generate。应该返回一个包含生成的 content 和 source map 的结果对象。

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>,

|}