@babel/helper-compilation-targets

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

@babel/helper-compilation-targets est un package utilitaire qui gère les cibles de compilation (navigateurs ou autres environnements comme Node.js) et les tables de compatibilité (connaissant la version supportant une syntaxe spécifique). Il est utilisé par @babel/preset-env pour déterminer quel plugin activer selon l'option targets.

JavaScript

import {
  filterItems,
  default as getTargets,
  isRequired,
} from "@babel/helper-compilation-targets";

filterItems

function filterItems(
  list: { [feature: string]: Targets },

  // A set of plugins that should always be included
  includes: Set<string>,

  // A set of plugins that should always be excluded
  excludes: Set<string>,
  targets: Targets,

  // A set of plugins that should always be included if `includes` is empty
  defaultIncludes: Array<string> | null,

  // A set of plugins that should always be excluded if `excludes` is empty
  defaultExcludes?: Array<string> | null,

  // A map from transform plugin to syntax plugin for backward compatibility with older `@babel/parser` versions
  pluginSyntaxMap?: Map<string, string | null>
): Set<string>; // A set of enabled plugins

Étant donné une table de données de compatibilité list (ex: @babel/compat-data) et des cibles navigateurs targets, renvoie un ensemble de plugins requis.

Exemple

JavaScript

const compatData = {
  "transform-feature-1": {
    chrome: "1",
    firefox: "1",
  },
  "transform-feature-2": {
    chrome: "2",
    firefox: "2",
  },
  "transform-feature-3": {
    chrome: "3",
    firefox: "3",
  },
  "transform-feature-4": {
    chrome: "4",
    firefox: "4",
  },
};

// filter a set of plugins required when compiled to chrome 2
// returns new Set(["transform-feature-3", "transform-feature-4"])
filterItems(compatData, new Set(), new Set(), {
  chrome: 2,
});

// filter a set of plugins required when compiled to chrome 2 and firefox 1
// returns new Set(["transform-feature-2", "transform-feature-3", "transform-feature-4"])
filterItems(compatData, new Set(), new Set(), {
  chrome: 2,
  firefox: 1,
});

// always include "transform-feature-2" and exclude "transform-feature-4"
// returns new Set(["transform-feature-2", "transform-feature-3"])
filterItems(
  compatData,
  new Set(["transform-feature-2"]),
  new Set(["transform-feature-4"]),
  {
    chrome: 2,
  }
);

// syntax-feature-2 is required to allow older @babel/parser to parse
// the feature-2 syntax supported in chrome 2

// returns new Set(["syntax-feature-2", "transform-feature-3", "transform-feature-4"])
filterItems(
  compatData,
  new Set(),
  new Set(),
  {
    chrome: 2,
  },
  null,
  null,
  new Map([["transform-feature-2", "syntax-feature-2"]])
);

note

Quand une nouvelle fonctionnalité ECMAScript atteint le stage-4, elle est intégrée dans @babel/parser, ce qui signifie qu'elle sera toujours analysée indépendamment du plugin. Cependant, nous avons besoin du plugin syntaxique pour les anciennes versions de @babel/parser.

getTargets

type GetTargetsOption = {
  // This is not the path of the config file, but the path where start searching it from
  configPath?: string;

  // The path of the config file
  configFile?: string;

  // The env to pass to browserslist
  browserslistEnv?: string;

  // true to disable config loading
  ignoreBrowserslistConfig?: boolean;
};

type InputTargets = {
  ...Targets,

  browsers?: Browsers,

  // When `true`, this completely replaces the `browsers` option.
  // When `intersect`, this is intersected with the `browsers`
  // option (giving the higher browsers as the result).
  esmodules?: boolean | "intersect",
};

function getTargets(
  inputTargets: InputTargets = {},
  options: GetTargetsOption = {}
): Targets;

Normalise les targets spécifiés par l'utilisateur en une liste de cibles prises en charge. Voir également (@babel/preset-env)[preset-env.md#options] pour GetTargetsOption.

Exemple

JavaScript

// Return the default compilation targets
// returns {}
getTargets();

Une cible de compilation vide équivaut à forcer toutes les transformations. Les cibles de compilation par défaut seront modifiées pour utiliser la requête Browserlists defaults, not IE 11 dans Babel 8.

On peut également interroger les cibles de compilation avec support des modules ES, comme l'a fait @vue/babel-preset-app pour fournir un ensemble de cibles modernes.

JavaScript

/* returns {
  "android": "61.0.0",
  "chrome": "61.0.0",
  "edge": "16.0.0",
  "firefox": "60.0.0",
  "ios": "10.3.0",
  "node": "13.2.0",
  "opera": "48.0.0",
  "safari": "10.1.0",
  "samsung": "8.2.0",
} */
getTargets({
  esmodules: true,
});

Note : Les données de compatibilité des modules ES sont générées depuis MDN.

isRequired

function isRequired(
  name: string,
  targets: Targets,
  {
    compatData = pluginsCompatData,
    includes,
    excludes,
  }: {
    compatData?: { [feature: string]: Targets };
    includes?: Set<string>;
    excludes?: Set<string>;
  } = {}
): boolean;

Étant donné des cibles navigateurs targets, vérifie dans compatData si le plugin name est requis pour la compilation. Quand compatData n'est pas spécifié, la source de données par défaut est @babel/compat-data.

Exemple

babel.config.js

module.exports = api => {
  const targets = api.targets();
  // The targets have native optional chaining support
  // if `transform-optional-chaining` is _not_ required
  const optionalChainingSupported = !isRequired(
    "transform-optional-chaining",
    targets
  );
};

Les auteurs de plugins peuvent utiliser isRequired pour optimiser la sortie du plugin selon différentes targets :

example-babel-plugin.js

// a naive plugin replace `a.b` to `a != null && a.b`
module.exports = api => {
  const targets = api.targets();
  // The targets have native optional chaining support
  // if `transform-optional-chaining` is _not_ required
  const optionalChainingSupported = !isRequired(
    "transform-optional-chaining",
    targets
  );
  const visited = new WeakSet();
  return {
    visitor: {
      MemberExpression(path) {
        if (path.matchesPattern("a.b")) {
          if (visited.has(path.node)) return;
          visited.add(path.node);
          if (optionalChainingSupported) {
            // When optional chaining is supported,
            // output `a?.b` instead of `a != null && a.b`
            path.replaceWith(api.templates`a?.b`);
          } else {
            path.replaceWith(api.templates`a != null && ${path.node}`);
          }
        }
      },
    },
  };
};

@babel/plugin-transform-object-rest-spread utilise isRequired pour déterminer si les cibles supportent nativement Object.assign.