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>My Parcel app</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>My Parcel app</h1>
  </body>
</html>

app.ts

console.log('Hello world!')

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="An image">

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">Other page</a>

<iframe> 元素可用於在另一個 HTML 頁面中嵌入 HTML 頁面。

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

雖然從 HTML 檔案參照的其他資產在預設情況下會在其編譯檔名中包含內容雜湊，但由 <a> 或 <iframe> 元素參照的檔案不會包含。這是因為這些 URL 通常是人類可讀的，並且需要隨著時間推移而具有穩定的名稱。可以透過 Namer 外掛程式來覆寫套件命名。

影片、音訊和其他資產

支援 <video>、<audio>、<track>、<embed> 和 <object> 元素。Parcel 會處理所引用的網址，並改寫為包含內容雜湊。

Open Graph 和 Schema.org 元資料

Parcel 支援使用 <meta> 標籤定義的 Open Graph、Twitter 卡片、VK、Schema.org 和 Microsoft 固定網站元資料。Parcel 會處理這些元素中所引用的圖片和其他網址，並改寫為包含內容雜湊。

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

JSON-LD

Parcel 支援透過 <script> 標籤嵌入 HTML 中的 JSON-LD 元資料。Parcel 會處理 JSON-LD 中所引用的圖片和其他網址，並改寫為包含內容雜湊。這項功能由 @parcel/transformer-jsonld 外掛程式處理，需要時會自動安裝到您的專案中。

在此範例中，Parcel 會處理從 logo 物件引用的圖片。

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

網路應用程式清單

支援 <link rel="manifest"> 元素，用於參照網路應用程式清單。這是一個 JSON 檔案，其中包含有關應用程式的各種元資料，並允許將其安裝到使用者的主畫面或桌面。Parcel 會處理此檔案中 icons 和 screenshots 鍵所引用的網址。網路應用程式清單可以寫成 .json 或 .webmanifest 檔案。

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

內嵌指令碼和樣式

<script> 和 <style> 標籤與文字內容也像獨立檔案一樣處理，產生的套件會插入回 HTML 檔案中。script 標籤上的 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>

注意：謹慎使用，因為大型內嵌腳本/樣式可能會損害（感知的）載入速度。

內嵌 `style` 屬性

style 屬性可用於任何 HTML 元素來定義 CSS 樣式。Parcel 會處理內嵌 CSS，並將結果插入回 style 屬性中。這包括遵循引用的 URL，例如背景圖片，以及為您的目標瀏覽器轉換現代 CSS。

<div style="background: url(background.jpg)">Hello!</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;
}

編譯的 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> 標籤，以平行載入這個「共用套件」。有關更多詳細資訊，請參閱程式碼分割。

PostHTML

PostHTML 是一個使用外掛程式轉換 HTML 的工具。你可以使用下列其中一個名稱建立設定檔來設定 PostHTML：.posthtmlrc（JSON，強烈建議）、.posthtmlrc.js、.posthtmlrc.mjs、.posthtmlrc.cjs、posthtml.config.js、posthtml.config.mjs 或 posthtml.config.cjs。

在你的應用程式中安裝外掛程式

yarn add posthtml-doctype --dev

然後，建立一個設定檔

.posthtmlrc

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

外掛程式在 plugins 物件中指定為金鑰，而選項則使用物件值定義。如果外掛程式沒有任何選項，請將其設定為一個空物件即可。

這個範例使用 posthtml-include 將另一個 HTML 檔案內嵌。

.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。

注意：如果可能，應避免使用 JavaScript 設定檔。這些會導致 Parcel 的快取效果較差，這表示每次重新啟動 Parcel 時，你的所有 HTML 檔案都會重新編譯。為避免這種情況，請改用基於 JSON 的設定格式（例如 .posthtmlrc）。

這個範例使用 posthtml-shorten 使用自訂縮短函式來縮短網址。

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>

生產

在生產模式中，Parcel 包含最佳化功能，以減少程式碼檔案大小。請參閱生產，以取得此功能運作方式的更多詳細資訊。

縮小

在生產模式中，Parcel 會自動縮小您的程式碼，以減少套件檔案大小。預設情況下，Parcel 使用 htmlnano 來執行 HTML 縮小。若要設定 htmlnano，您可以在專案根目錄中建立一個 .htmlnanorc 或 .htmlnanorc.json 檔案。

例如，保留 HTML 註解

.htmlnanorc

{
  "removeComments": false
}

或不縮小 SVG 元素。

.htmlnanorc

{
  "minifySvg": false
}

注意：.htmlnanorc.js、.htmlnanorc.mjs、.htmlnanorc.cjs、htmlnano.config.js、htmlnano.config.mjs 和 htmlnano.config.cjs 也支援基於 JavaScript 的設定，但應盡可能避免使用，因為它會降低 Parcel 快取的效能。請改用基於 JSON 的設定格式。

相依性

樣式表

指令碼

影像

連結和 iframe

影片、音訊和其他資產

Open Graph 和 Schema.org 元資料

JSON-LD

網路應用程式清單

內嵌指令碼和樣式

內嵌 style 屬性

內嵌 SVG

並行腳本和樣式

PostHTML

posthtml.config.js

生產

縮小

內嵌 `style` 屬性