HTML

Parcel 包括对 HTML 的一流支持。HTML 文件通常是你提供给 Parcel 的入口文件，所有依赖（包括 JavaScript、CSS、图片和其他页面的链接）都将从那里开始构建整个应用。

¥Parcel includes first-class support for HTML out of the box. HTML files are often the entry file that you provide to Parcel, and all dependencies including JavaScript, CSS, images, and links to other pages are followed from there to build your entire app.

依赖

¥Dependencies

Parcel 会检测 HTML 中对其他文件（例如 <script>、<img>、<video> 或 <meta property="og:image">）的大多数引用并对其进行处理。这些引用被重写，以便它们链接到正确的输出文件。

¥Parcel detects most references in HTML to other files (such as <script>, <img>, <video> or <meta property="og:image">) and processes them as well. These references are rewritten so that they link to the correct output files.

文件名相对于当前 HTML 文件进行解析，但你也可以使用 absolute 和 tilde 说明符。详情请参见依赖解析。

¥File names are resolved relative to the current HTML file, but you can also use absolute and tilde specifiers. See Dependency resolution for details.

样式表

¥Stylesheets

<link rel="stylesheet"> 元素可用于引用 HTML 中的样式表。你可以引用 CSS 文件或编译为 CSS 的任何其他文件，例如 SASS、Less 或 Stylus。

¥The <link rel="stylesheet"> element can be used to reference stylesheets from HTML. You can reference a CSS file, or any other file that compiles to CSS such as SASS, Less, or Stylus.

index.html:

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="./style.less" />
  </head>
  <body>
    <h1>My Parcel app</h1>
  </body>
</html>

style.less:

h1 {
  color: darkslategray;
}

有关 Parcel 如何处理 CSS 的详细信息，请参阅 CSS 文档。

¥See the CSS docs for details on how CSS is processed by Parcel.

脚本

¥Scripts

<script> 元素可用于引用 HTML 中的脚本文件。你可以引用 JavaScript 文件，或编译为 JavaScript 的任何其他文件，例如 TypeScript、JSX 或 CoffeeScript。

¥The <script> element can be used to reference a script file from HTML. You can reference a JavaScript file, or any other file that compiles to JavaScript such as TypeScript, JSX, or CoffeeScript.

index.html:

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="app.ts" />
  </head>
  <body>
    <h1>My Parcel app</h1>
  </body>
</html>

app.ts:

console.log('Hello world!')

type="module" 属性应用于指示文件是 ES 模块或 CommonJS 文件。如果省略，则引用的文件将被视为经典脚本。有关此内容的更多信息，请参阅经典脚本。

¥The type="module" attribute should be used to indicate that a file is an ES module or CommonJS file. If it is omitted, then the referenced file is treated as a classic script. See Classic scripts for more information about this.

当使用 <script type="module"> 时，如果你的某些浏览器目标不支持 ES 模块，Parcel 也会自动生成 <script nomodule> 版本。详细信息请参见差异化打包。

¥When a <script type="module"> is used, Parcel will automatically generate a <script nomodule> version as well if some of your browser targets do not support ES modules. See Differential bundling for more details.

Parcel 还支持 <script> 元素的 async 和 defer 属性。当脚本为 async 时，它可以在运行时以任意顺序加载。因此，Parcel 将异步脚本视为“隔离的”。这意味着异步脚本无法与页面上的其他脚本共享任何依赖，这可能会导致模块重复。因此，除特殊情况外，最好避免使用 async 脚本。

¥Parcel also supports the async and defer attributes of the <script> element. When a script is async, it may load in an arbitrary order at runtime. Therefore, Parcel treats async scripts as "isolated”. This means that async scripts cannot share any dependencies with other scripts on the page, which may result in duplication of modules. For this reason, it's better to avoid async scripts except in specific circumstances.

defer 属性与 async（非渲染阻塞）具有类似的效果，但保证脚本按照 HTML 文件中定义的顺序执行。当使用 <script type="module"> 时，defer 自动启用，不需要声明。

¥The defer attribute has a similar effect as async (non render-blocking), but guarentees that scripts are executed in the order they are defined in the HTML file. When using <script type="module">, defer is automatically enabled and does not need to be declared.

有关详细信息，请参阅 MDN 文档中的 <script> 元素；有关 Parcel 如何处理 JavaScript 的详细信息，请参阅 JavaScript 文档。

¥See the MDN docs for the <script> element for more info, and the JavaScript docs for details on how Parcel processes JavaScript.

图片

¥Images

Parcel 支持通过 <img> 元素引用的图片。src 属性可用于引用图片文件。

¥Parcel supports images referenced via the <img> element. The src attribute can be used to reference an image file.

<img src="image.jpg" alt="An image">

Parcel 还支持 srcset 属性，该属性允许引用不同尺寸或分辨率的图片的多个版本。

¥Parcel also supports the srcset attribute, which allows referencing multiple versions of an image for different sizes or resolutions.

<img src="logo@1x.png" srcset="logo@2x.png 2x" alt="logo">

此外，Parcel 支持 <picture> 元素，这使得通过 <source> 元素提供多个替代图片变得更加灵活。

¥In addition, Parcel supports the <picture> element, which allows even more flexibility for providing multiple alternative images via the <source> element.

Parcel 的图片转换器还可用于从单个源文件生成图片的多个版本。这是通过使用查询参数提供宽度、高度和格式来转换和调整源图片大小来完成的。

¥Parcel’s image transformer can also be used to generate multiple versions of an image from a single source file. This is done using query parameters to provide the width, height, and format to convert and resize the source image.

<picture>
  <source type="image/webp" srcset="image.jpg?as=webp&width=400, image.jpg?as=webp&width=800 2x">
  <source type="image/jpeg" srcset="image.jpg?width=400, image.jpg?width=800 2x">
  <img src="image.jpg?width=400" width="400">
</picture>

链接和 iframe

¥Links and iframes

Parcel 支持 <a> 元素从 HTML 文件链接到另一个页面。

¥Parcel supports the <a> element to link to another page from an HTML file.

<a href="other.html">Other page</a>

<iframe> 元素可用于将 HTML 页面嵌入到另一个页面中。

¥The <iframe> element can be used to embed an HTML page inside another.

<iframe src="iframe.html"></iframe>

默认情况下，从 HTML 文件引用的其他资源将在其编译文件名中包含内容哈希，但 <a> 或 <iframe> 元素引用的文件则不会。这是因为这些 URL 通常是人类可读的，并且随着时间的推移需要有一个稳定的名称。打包包命名可以被命名插件覆盖。

¥While other assets referenced from an HTML file will include a content hash in their compiled filename by default, files referenced by an <a> or <iframe> element will not. That's because these URLs are typically human readable, and need to have a stable name over time. Bundle naming can be overridden by Namer plugins.

视频、音频和其他资源

¥Video, audio, and other assets

支持 <video>、<audio>、<track>、<embed> 和 <object> 元素。引用的 URL 由 Parcel 处理并重写以包含内容哈希。

¥The <video>, <audio>, <track>, <embed>, and <object> elements are supported. The referenced URLs are processed by Parcel and rewritten to include a content hash.

开放图谱和 Schema.org 元数据

¥Open Graph and Schema.org metadata

Parcel 支持使用 <meta> 标签定义的打开图、推特卡片、VK、Schema.org 和微软固定网站元数据。这些元素中引用的图片和其他 URL 由 Parcel 处理并重写以包含内容哈希。

¥Parcel supports Open Graph, Twitter Cards, VK, Schema.org, and Microsoft pinned site metadata defined using the <meta> tag. Images and other URLs referenced in these elements are processed by Parcel and rewritten to include a content hash.

<meta property="og:image" content="100x100.png" />

JSON-LD

Parcel 支持通过 <script> 标签嵌入 HTML 中的 JSON-LD 元数据。JSON-LD 中引用的图片和其他 URL 由 Parcel 处理并重写以包含内容哈希。这是由 @parcel/transformer-jsonld 插件处理的，该插件会在需要时自动安装到你的项目中。

¥Parcel supports JSON-LD metadata embedded in HTML via <script> tags. Images and other URLs referenced in JSON-LD are processed by Parcel and rewritten to include a content hash. This is handled by the @parcel/transformer-jsonld plugin, which will automatically be installed into your project when needed.

在此示例中，从 logo 对象引用的图片将由 Parcel 处理。

¥In this example, the image referenced from the logo object will be processed by Parcel.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "LocalBusiness",
  "name": "Joe's Pizza",
  "description": "Delicious pizza for over 30 years.",
  "telephone": "555-111-2345",
  "openingHours": "Mo,Tu,We,Th,Fr 09:00-17:00",
  "logo": {
    "@type": "ImageObject",
    "url": "images/logo.png",
    "width": 180,
    "height": 120
  }
}
</script>

Web 清单

¥Web manifests

支持 <link rel="manifest"> 元素引用网络清单。这是一个 JSON 文件，其中包含有关应用的各种元数据，并允许将其安装到用户的主屏幕或桌面。Parcel 处理此文件中 icons 和 screenshots 键中引用的 URL。Web 清单可以写入 .json 或 .webmanifest 文件中。

¥The <link rel="manifest"> element is supported to reference a Web manifest. This is a JSON file that includes various metadata about the app, and allows it to be installed to the user's home screen or desktop. Parcel processes the URLs referenced in the icons and screenshots keys in this file. Web manifests may be written in either a .json or .webmanifest file.

<link rel="manifest" href="manifest.json">

内联脚本和样式

¥Inline scripts and styles

带有文本内容的 <script> 和 <style> 标签也像独立文件一样进行处理，并将生成的包插入回 HTML 文件中。脚本标记上的 type="module" 属性的工作方式与上面针对外部脚本所述的相同。但是，如果你的某些浏览器目标本身不支持 ES 模块，Parcel 只会将内联脚本编译为非模块脚本，并且不会输出 <script type="module">，以保持生成的 HTML 小。

¥<script> and <style> tags with text content are also processed just like standalone files, and the generated bundles are inserted back into the HTML file. The type="module" attribute on script tags works just as described above for external scripts. However, if some of your browser targets don't support ES modules natively, Parcel will only compile inline scripts to a non-module script and will not output a <script type="module"> in order to keep the generated HTML small.

index.html:

<!DOCTYPE html>
<html>
  <body>
    <style>
      @import "./style.scss";
    </style>
    <script type="module">
      import value from "./other.ts";
      console.log(value);
    </script>
  </body>
</html>

注意：请谨慎使用此选项，因为大型内联脚本/样式可能会损害（感知的）加载速度。

¥Note: Use this sparingly, as big inline scripts/styles can be detrimental to the (perceived) load speed.

内联 `style` 属性

¥Inline style attribute

style 属性可用于任何 HTML 元素来定义 CSS 样式。Parcel 将处理内联 CSS，并将结果插入回 style 属性中。这包括以下引用的 URL（例如背景图片）以及为目标浏览器转换现代 CSS。

¥The style attribute can be used on any HTML element to define CSS styles. Parcel will process the inline CSS, and insert the result back into the style attribute. This includes following referenced URLs such as background images, as well as transforming modern CSS for your target browsers.

<div style="background: url(background.jpg)">Hello!</div>

内联 SVG

¥Inline SVG

Parcel 支持 HTML 中的内联 SVG。支持通过 <image> 元素引用的图片和通过 <use> 元素引用的依赖，并且还如上所述处理 SVG 内的内联脚本和样式。

¥Parcel supports inline SVG in HTML. Images referenced via the <image> element and dependencies referenced via the <use> element are supported, and inline scripts and styles within the SVG are also processed as described above.

<!DOCTYPE html>
<html>
  <body>
    <svg xmlns:xlink="http://www.w3.org/1999/xlink">
      <rect x="10" y="10" width="50" height="50" fill="red" />
      <use xlink:href="icon.svg"/>
    </svg>
  </body>
</html>

并行脚本和样式

¥Parallel scripts and styles

当引用脚本或样式时，有时 Parcel 需要将另一个依赖文件插入到编译后的 HTML 文件中。例如，当引用导入 CSS 文件的 JavaScript 文件时，Parcel 会将 <link> 元素插入到 <head> 中，以与 JavaScript 并行加载此样式表。

¥When referencing a script or style, sometimes Parcel will need to insert another dependent file into the compiled HTML file. For example, when referencing a JavaScript file which imports a CSS file, Parcel will insert a <link> element into the <head> to load this stylesheet in parallel with the JavaScript.

index.html:

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="app.js"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

app.js:

import './app.css';

let app = document.createElement('div');
app.className = 'app';
app.textContent = 'My Parcel app!';
root.appendChild(app);

app.css:

.app {
  background: red;
}

编译后的 HTML：

¥Compiled HTML:

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" src="app.f8e9c6.css">
    <script type="module" src="app.26fce9.js"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

脚本也可能发生这种情况。例如，如果两个页面依赖于同一个 JavaScript 库（例如 React 或 Lodash），则它可能会被拆分成自己的包并单独加载。Parcel 会在编译后的 HTML 中插入一个 <script> 标签来并行加载这个 "共享包"。详细信息请参见代码分割。

¥This may also occur with scripts. For example, if two pages depend on the same JavaScript library (e.g. React or Lodash), it may be split out into its own bundle and loaded separately. Parcel will insert a <script> tag into the compiled HTML to load this "shared bundle" in parallel. See Code Splitting for more details.

PostHTML

PostHTML 是一个通过插件转换 HTML 的工具。你可以通过使用以下名称之一创建配置文件来配置 PostHTML：.posthtmlrc（JSON，强烈推荐）、.posthtmlrc.js、.posthtmlrc.mjs、.posthtmlrc.cjs、posthtml.config.js、posthtml.config.mjs 或 posthtml.config.cjs。

¥PostHTML is a tool for transforming HTML with plugins. You can configure PostHTML by creating a configuration file using one of these names: .posthtmlrc (JSON, strongly recommended), .posthtmlrc.js, .posthtmlrc.mjs, .posthtmlrc.cjs, posthtml.config.js, posthtml.config.mjs, or posthtml.config.cjs.

在你的应用中安装插件：

¥Install plugins in your app:

yarn add posthtml-doctype --dev

然后，创建一个配置文件：

¥Then, create a config file:

.posthtmlrc:

{
  "plugins": {
    "posthtml-doctype": { "doctype": "HTML 5" }
  }
}

插件在插件对象中指定为键，选项使用对象值定义。如果插件没有选项，只需将其设置为空对象即可。

¥Plugins are specified in the plugins object as keys, and options are defined using object values. If there are no options for a plugin, just set it to an empty object instead.

此示例使用 posthtml-include 内联另一个 HTML 文件。

¥This example uses posthtml-include to inline another HTML file.

.posthtmlrc:

{
  "plugins": {
    "posthtml-include": {}
  }
}

index.html:

<html>
  <head>
    <title>Home</title>
  </head>
  <body>
    <include src="header.html"></include>
    <main>My content</main>
  </body>
</html>

header.html:

<header>This is my header</header>

posthtml.config.js

对于某些需要传递函数作为配置选项的插件，或者要设置基于 process.env.NODE_ENV 的插件，你需要使用 posthtml.config.js 文件而不是 .posthtmlrc 进行配置。

¥For some plugins that require passing a function as a configuration option, or to set up plugins based on process.env.NODE_ENV, you need to use a posthtml.config.js file for configuration instead of .posthtmlrc.

注意：如果可能，应避免使用 JavaScript 配置文件。这些会导致 Parcel 的缓存效率降低，这意味着每次重新启动 Parcel 时，所有 HTML 文件都将被重新编译。为了避免这种情况，请改用基于 JSON 的配置格式（例如 .posthtmlrc）。

¥Note: Using a JavaScript config file should be avoided if possible. These cause Parcel’s caching to be less effective, which means all of your HTML files will be recompiled each time you restart Parcel. To avoid this, use a JSON-based config format instead (e.g. .posthtmlrc).

此示例使用 posthtml-shorten 使用自定义缩短函数来缩短 URL。

¥This example uses posthtml-shorten to shorten URLs using a custom shortening function.

yarn add posthtml-shorten --dev

posthtml.config.js:

module.exports = {
  plugins: {
    "posthtml-shorten": {
      shortener: {
        process: function (url) {
          return new Promise((resolve, reject) => {
            resolve(url.replace(".html", ""));
          });
        },
      },
      tag: ["a"], // Allowed tags for URL shortening
      attribute: ["href"], // Attributes to replace on the elements
    },
  },
};

index.html:

<html>
  <head>
    <title>Home</title>
  </head>
  <body>
    <a href="http://example.com/test.html">Example</a>
  </body>
</html>

生产

¥Production

在生产模式下，Parcel 包括优化以减少代码的文件大小。有关其工作原理的更多详细信息，请参阅生产。

¥In production mode, Parcel includes optimizations to reduce the file size of your code. See Production for more details about how this works.

缩小化

¥Minification

在生产模式下，Parcel 会自动缩小代码以减小打包包的文件大小。默认情况下，Parcel 使用 htmlnano 执行 HTML 缩小。要配置 htmlnano，你可以在项目根目录中创建 .htmlnanorc 或 .htmlnanorc.json 文件。

¥In production mode, Parcel automatically minifies your code to reduce the file sizes of your bundles. By default, Parcel uses htmlnano to perform HTML minification. To configure htmlnano, you can create a .htmlnanorc or .htmlnanorc.json file in your project root directory.

例如保留 HTML 注释

¥For example to retain HTML comments

.htmlnanorc:

{
  "removeComments": false
}

或者不缩小 SVG 元素。

¥or to not minify SVG elements.

.htmlnanorc:

{
  "minifySvg": false
}

注意：基于 JavaScript 的配置还支持 .htmlnanorc.js、.htmlnanorc.mjs、.htmlnanorc.cjs、htmlnano.config.js、htmlnano.config.mjs 和 htmlnano.config.cjs，但应尽可能避免，因为它会降低 Parcel 缓存的有效性。请改用基于 JSON 的配置格式。

¥Note: .htmlnanorc.js, .htmlnanorc.mjs, .htmlnanorc.cjs, htmlnano.config.js, htmlnano.config.mjs, and htmlnano.config.cjs are also supported for JavaScript-based configuration, but should be avoided when possible because it reduces the effectiveness of Parcel's caching. Use a JSON based configuration format instead.

依赖

样式表

脚本

图片

链接和 iframe

视频、音频和其他资源

开放图谱和 Schema.org 元数据

JSON-LD

Web 清单

内联脚本和样式

内联 style 属性

内联 SVG

并行脚本和样式

PostHTML

posthtml.config.js

生产

缩小化

内联 `style` 属性