HTML

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

依赖

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

文件名相对于当前 HTML 文件解析，但您也可以使用绝对和波浪号指定符。有关详细信息，请参见依赖解析。

样式表

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

index.html:

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="./style.less" />
  </head>
  <body>
    <h1>我的 Parcel 应用</h1>
  </body>
</html>

style.less:

h1 {
  color: darkslategray;
}

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

脚本

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

index.html:

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="app.ts" />
  </head>
  <body>
    <h1>我的 Parcel 应用</h1>
  </body>
</html>

app.ts:

console.log("你好世界！");

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

使用 <script type="module"> 时，如果某些浏览器目标不支持 ES 模块，Parcel 将自动生成 <script nomodule> 版本。有关更多详细信息，请参见差异化捆绑。

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

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

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

图像

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

<img src="image.jpg" alt="一张图片" />

Parcel 还支持 srcset 属性，允许为不同大小或分辨率引用多个版本的图像。

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

此外，Parcel 支持 <picture> 元素，通过 <source> 元素提供更多灵活性来提供多个替代图像。

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

<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

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

<a href="other.html">其他页面</a>

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

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

虽然从 HTML 文件引用的其他资源默认会在其编译后的文件名中包含内容哈希，但 <a> 或 <iframe> 元素引用的文件不会。这是因为这些 URL 通常是人类可读的，并且需要随时间保持稳定的名称。捆绑包命名可以通过 Namer 插件覆盖。

视频、音频和其他资源

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

Open Graph 和 Schema.org 元数据

Parcel 支持使用 <meta> 标签定义的 Open Graph、Twitter 卡片、VK、Schema.org 和 Microsoft 固定站点元数据。这些元素中引用的图像和其他 URL 由 Parcel 处理并重写，以包含内容哈希。

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

JSON-LD

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

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

<script type="application/ld+json">
  {
    "@context": "http://schema.org",
    "@type": "LocalBusiness",
    "name": "乔的披萨店",
    "description": "30多年来的美味披萨。",
    "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 清单

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

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

内联脚本和样式

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

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：请谨慎使用，因为大型内联脚本/样式可能会对（感知到的）加载速度产生负面影响。

内联 `style` 属性

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

<div style="background: url(background.jpg)">你好！</div>

内联 SVG

Parcel 支持 HTML 中的内联 SVG。支持通过 <image> 元素引用的图像和通过 <use> 元素引用的依赖，SVG 中的内联脚本和样式也按上述方式处理。

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

并行脚本和样式

在引用脚本或样式时，Parcel 有时需要将另一个依赖文件插入到编译后的 HTML 文件中。例如，在引用导入 CSS 文件的 JavaScript 文件时，Parcel 将在 <head> 中插入一个 <link> 元素，以并行加载此样式表和 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;
}

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) ，则可以将其拆分为自己的 bundle 并单独加载。Parcel 将在编译后的 HTML 中插入一个<script>标签，以并行加载这个"共享包"。有关更多详细信息，请参阅代码拆分。

PostHTML

Parcel 支持 PostHTML，这是一个用于转换 HTML 的工具。要使用 PostHTML，请在项目根目录的 package.json 中配置插件：

package.json:

{
  "@parcel/transformer-posthtml": {
    "plugins": ["posthtml-img-autosize"]
  }
}

您还可以使用 .posthtmlrc、.posthtmlrc.js、.posthtmlrc.json 或 posthtml.config.js 配置文件。

note：应尽可能避免使用基于 JavaScript 的配置，因为这会降低 Parcel 缓存的有效性。请改用基于 JSON 的配置格式（例如 .posthtmlrc.json）。

预处理器

Parcel 支持多种 HTML 预处理器，如 Pug、Markdown 和 MDX。要使用它们，只需安装相应的依赖并创建带有正确扩展名的文件。

$ npm install -D pug

<link rel="stylesheet" href="index.pug" />

压缩

在生产模式下，Parcel 会自动压缩 HTML 文件。这是通过 @parcel/optimizer-htmlnano 插件完成的，该插件使用 HTMLNano 来最小化 HTML。

您可以在 package.json 中自定义压缩选项：

package.json:

{
  "@parcel/optimizer-htmlnano": {
    "removeComments": false
  }
}

内容哈希

默认情况下，Parcel 会为输出文件添加内容哈希，以实现长期缓存。这意味着只有在文件内容发生变化时，文件名才会改变。这有助于提高应用的性能，因为浏览器可以缓存未更改的文件。

您可以通过在 package.json 中配置 @parcel/packager-html 来自定义此行为：

package.json:

{
  "@parcel/packager-html": {
    "addContentHash": false
  }
}

目标浏览器

Parcel 使用 browserslist 配置来确定应用需要支持的浏览器。这影响 HTML 中的 JavaScript 和 CSS 的转译和前缀。

package.json:

{
  "browserslist": ["> 0.5%", "last 2 versions", "not dead"]
}

性能提示

避免大型内联脚本和样式：内联脚本和样式会增加 HTML 文件的大小，并可能影响页面加载性能。
使用代码拆分：对于大型应用，使用代码拆分可以帮助减少初始加载时间。
优化图像：使用 Parcel 的图像转换器来生成多个图像大小和格式，以优化加载性能。
利用缓存：Parcel 的内容哈希和增量构建可以显著提高后续构建的速度。

常见问题解答

如何引用静态资源？

使用相对路径或 Parcel 支持的特殊路径指定符，如绝对路径和波浪号路径。

我可以在 HTML 中使用预处理器吗？

是的，Parcel 支持 Pug、Markdown 和 MDX 等预处理器。

如何自定义 HTML 压缩？

在 package.json 中配置 @parcel/optimizer-htmlnano 插件的选项。

如何处理跨浏览器兼容性？

使用 browserslist 配置指定目标浏览器，Parcel 将自动处理转译和前缀。

依赖

样式表

脚本

图像

链接和 iframe

视频、音频和其他资源

Open Graph 和 Schema.org 元数据

JSON-LD

Web 清单

内联脚本和样式

内联 style 属性

内联 SVG

并行脚本和样式

PostHTML

预处理器

压缩

内容哈希

目标浏览器

性能提示

常见问题解答

如何引用静态资源？

我可以在 HTML 中使用预处理器吗？

如何自定义 HTML 压缩？

如何处理跨浏览器兼容性？

内联 `style` 属性