34. 電腦程式碼標記 (Marking Up Computer Code)

By /

HTML 提供元素，用來識別程式碼、使用者輸入、程式輸出及變數。

這些元素描述內容的意思，而不只是控制外觀。

元素意思
<code>電腦程式碼片段
<pre>空白字元具有意義的預先格式化文字
<kbd>使用者輸入
<samp>程式或電腦系統的範例輸出
<var>變數或佔位值

例如：

<p>
  執行 <code>npm test</code>。
  如果成功，終端機會顯示 <samp>All tests passed.</samp>
</p>

使用具有語意的元素區分程式碼、輸入及輸出，再另外透過 CSS 控制外觀。

34.1 使用 <code> 標示行內程式碼

使用 <code> 標示一般文字中的程式碼片段：

<p>
  使用 <code>document.querySelector()</code> 選取元素。
</p>

適合的例子包括：

  • 函式名稱。
  • HTML 元素名稱。
  • CSS 宣告。
  • 程式運算式。
  • 檔案名稱。
  • 其他電腦可讀取的片段。
<p>
  將網頁儲存為 <code>index.html</code>。
</p>

<p>
  CSS 宣告 <code>display: grid;</code> 會建立網格容器。
</p>

瀏覽器通常使用等寬字型顯示程式碼，但預設外觀不是這個元素的主要用途。

不要只為讓一般文章使用等寬字型而加入 <code>。

34.2 使用 <pre><code> 建立程式碼區塊

多行程式碼範例應結合 <pre> 及 <code>：

<pre><code>const greeting = "Hello";
console.log(greeting);</code></pre>

兩個元素具有不同作用：

  • <pre> 保留空白字元及換行。
  • <code> 識別內容為電腦程式碼。

單用 <code> 不會保留原始格式：

<code>const greeting = "Hello";
console.log(greeting);</code>

在一般空白處理規則下，換行會被折疊，而不是顯示為另一行。

<pre> 也可以包含非程式碼內容，例如純文字示意圖或已格式化的程式輸出。它不會自動表示「程式碼區塊」。

34.3 <pre> 中的空白字元

<pre> 內的空白字元通常會影響顯示內容：

<pre><code>if (ready) {
  start();
}</code></pre>

縮排 HTML 原始碼時應小心：

<pre><code>
    if (ready) {
      start();
    }
</code></pre>

這會在 <code> 內加入額外空格及開頭換行。

HTML 剖析會忽略緊接 <pre> 開始標籤後的一個換行字元，但這項規則不適用於巢狀 <code> 開始標籤後的換行。

為了得到可預測的格式，應在 <code> 後立即開始程式碼，並將 </code> 放在最後一個字元之後。

CSS 可以改變空白處理方式，因此應檢查程式碼區塊的樣式。

34.4 轉義程式碼範例中的 HTML

將標記放在 <code> 內，不會阻止瀏覽器將它當成 HTML 剖析。

以下寫法不會按字面顯示段落元素的原始碼：

<!-- 如果要按字面顯示 HTML 原始碼，這種寫法並不正確。 -->
<code><p>Hello</p></code>

應將標記字元轉義：

<code><p>Hello</p></code>

完整範例：

<pre><code><button type="button">
  儲存
</button></code></pre>

常用字元參照包括：

要顯示的字元HTML 原始碼
<&lt;
>&gt;
&&amp;
"&quot;

元素文字中的引號通常不需要轉義，但在屬性值內可能需要。

如果要顯示字面文字 &lt;，應轉義它的 &：

<code><</code>

程式碼標記不是安全容納未轉義 HTML 的容器。

34.5 使用 <kbd> 標示使用者輸入

使用 <kbd> 標示使用者提供的輸入：

<p>
  按 <kbd>Enter</kbd> 提交指令。
</p>

鍵盤快捷鍵可以分別標示每個按鍵：

<p>
  按 <kbd><kbd>Ctrl</kbd> + <kbd>S</kbd></kbd> 儲存。
</p>

外層 <kbd> 表示完整輸入組合，內層元素表示個別按鍵。

<kbd> 不限於實體鍵盤輸入，也可以描述其他使用者輸入，例如語音指令：

<p>
  說出 <kbd>開始錄音</kbd> 即可開始。
</p>

應選擇符合實際應用程式及平台的說明和例子。不同作業系統的快捷鍵可能不同。

34.6 使用 <samp> 標示程式輸出

使用 <samp> 標示程式或電腦系統的輸出：

<p>
  終端機顯示 <samp>Build completed successfully.</samp>
</p>

多行輸出可以配合 <pre>：

<pre><samp>Checking files...
No errors found.
Build complete.</samp></pre>

應區分操作指示與結果：

<p>
  輸入 <kbd>python --version</kbd>。
  輸出可能是 <samp>Python 3.x.x</samp>。
</p>

在這個例子中：

  • <kbd> 識別使用者輸入的內容。
  • <samp> 識別系統返回的內容。

討論同一指令的語法，而不是要求使用者輸入時，可以改用 <code>。

34.7 使用 <var> 標示變數

使用 <var> 標示程式設計、數學或說明文字中的變數：

<p>
  函式返回 <var>result</var>。
</p>

它也可以識別讀者必須替換的佔位值：

<p>
  開啟 <code>/users/<var>user-id</var>/profile</code>，
  並將 <var>user-id</var> 替換為使用者識別碼。
</p>

瀏覽器通常以斜體顯示 <var>，但它不是通用斜體元素。

完整原始碼通常不需要為每個變數加入 <var>。應使用 <code> 標示程式碼範例，並在識別變數或佔位值有助說明時才使用 <var>。

34.8 識別程式語言

HTML 沒有為 <code> 提供專用的程式語言屬性。

常見慣例是使用類別：

<pre><code class="language-javascript">const total = 12;
console.log(total);</code></pre>

語法高亮工具可能識別以下類別：

  • language-html
  • language-css
  • language-javascript
  • language-python

這些類別名稱本身不會產生語法高亮。

不要使用 lang 識別程式語言：

<!-- lang 的錯誤用法。 -->
<code lang="javascript">const total = 12;</code>

lang 識別的是英文或日文等自然語言，不是程式語言。

34.9 語法高亮與可讀性

語法高亮是可選功能。可閱讀的程式碼區塊不一定需要它。

實用樣式包括：

pre {
  max-width: 100%;
  overflow-x: auto;
  padding: 1rem;
  border: 1px solid #767676;
  border-radius: 0.5rem;
  background: #f5f7fa;
  white-space: pre;
  tab-size: 2;
}

code,
kbd,
samp {
  font-family: ui-monospace, monospace;
}

應考慮：

  • 提供足夠的文字對比度。
  • 不要只用顏色傳達重要意思。
  • 在有需要時保留縮排。
  • 避免讓可見行號混入複製的程式碼。
  • 在狹窄螢幕上測試較長範例。

可以接受自動換行的範例：

pre.wrap {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}

自動換行可以改善內容的顯示適配，但也可能令原始碼結構較難理解。應根據範例選擇處理方式。

34.10 無障礙功能與動態程式碼內容

具有語意的程式碼元素有助描述內容，但不保證輔助技術能清晰讀出程式語法。

支援情況各有不同，標點符號的讀法也可能取決於使用者設定。

應在範例旁提供說明：

<p>
  這個例子選取第一個按鈕，並將它停用。
</p>

<pre><code>const button = document.querySelector("button");
button.disabled = true;</code></pre>

水平捲動區塊應讓鍵盤使用者在有需要時能夠進入及捲動。可取得焦點並具有有意義標籤的 <pre> 是其中一種方式：

<pre tabindex="0" role="region" aria-label="JavaScript 範例"><code>console.log("Hello");</code></pre>

應按需要使用，而不是為每個簡短範例加入不必要的 Tab 停留點。

透過 JavaScript 插入程式碼時，應使用 textContent 提供字面文字：

const example = document.getElementById("code-example");

example.textContent = '<button type="button">儲存</button>';

不要使用 innerHTML 插入不可信的程式碼字串：

// 如果 sourceCode 包含不可信標記，這種寫法不安全。
example.innerHTML = sourceCode;

<code> 不會清理內容。語法高亮工具也必須安全處理輸入。

34.11 完整範例：程式碼、輸入與輸出

以下獨立網頁示範 HTML 程式碼區塊、鍵盤指令、範例輸出及變數佔位值。

範例只作為文字顯示，不會執行。

id: hong-kong-html-computer-code
name: 電腦程式碼標記 — 範例
type: html
content: |-
  <!doctype html>
  <html lang="zh-Hant-HK">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta
      name="description"
      content="示範如何使用 HTML 標示程式碼、使用者輸入、程式輸出及變數。"
    >
    <title>電腦程式碼標記 | HTML 範例</title>
    <style>
      *,
      *::before,
      *::after {
        box-sizing: border-box;
      }

      body {
        margin: 0;
        color: #222;
        background: #f5f7fa;
        font-family: system-ui, sans-serif;
        line-height: 1.8;
      }

      main {
        max-width: 46rem;
        margin-inline: auto;
        padding: 2rem 1rem;
      }

      h1,
      h2 {
        color: #005ea8;
        line-height: 1.4;
      }

      section {
        min-width: 0;
        margin-block: 1.5rem;
        padding: 1.25rem;
        border: 1px solid #767676;
        border-radius: 0.5rem;
        background: white;
      }

      section > h2 {
        margin-block-start: 0;
      }

      code,
      kbd,
      samp {
        font-family: ui-monospace, monospace;
      }

      p code {
        padding: 0.1em 0.25em;
        border-radius: 0.2rem;
        background: #eaf2f8;
      }

      pre {
        max-width: 100%;
        overflow-x: auto;
        padding: 1rem;
        border: 1px solid #767676;
        border-radius: 0.4rem;
        background: #f5f7fa;
        font-size: 1rem;
        line-height: 1.6;
        white-space: pre;
        tab-size: 2;
      }

      kbd {
        padding: 0.1em 0.35em;
        border: 1px solid #767676;
        border-radius: 0.2rem;
        background: #f5f7fa;
      }

      :focus-visible {
        outline: 3px solid #005ea8;
        outline-offset: 3px;
      }
    </style>
  </head>
  <body>
    <main>
      <h1>電腦程式碼標記</h1>

      <p>
        以下例子區分程式碼、使用者輸入、
        程式輸出及可替換的值。
      </p>

      <section aria-labelledby="html-heading">
        <h2 id="html-heading">HTML 原始碼</h2>

        <p>
          這個例子建立一個可見標籤為「儲存」的按鈕。
          下方標記只作為文字顯示，不會呈現為按鈕。
        </p>

        <pre
          tabindex="0"
          role="region"
          aria-label="HTML 按鈕原始碼"
        ><code class="language-html" translate="no"><button type="button">
  儲存
</button></code></pre>

        <p>
          <code>type="button"</code> 屬性識別
          預設不會提交表單的按鈕。
        </p>
      </section>

      <section aria-labelledby="input-heading">
        <h2 id="input-heading">使用者輸入</h2>

        <p>
          如果已安裝 Python，而且可以透過
          <code>python</code> 執行，
          請在終端機輸入
          <kbd translate="no">python --version</kbd>，
          然後按 <kbd translate="no">Enter</kbd>。
        </p>
      </section>

      <section aria-labelledby="output-heading">
        <h2 id="output-heading">範例輸出</h2>

        <p>
          終端機會顯示已安裝的版本。
          以下只是示範用的佔位文字：
        </p>

        <pre><samp translate="no">Python 3.x.x</samp></pre>
      </section>

      <section aria-labelledby="variable-heading">
        <h2 id="variable-heading">可替換的值</h2>

        <p>
          在 <code translate="no">/users/<var>user-id</var>/profile</code> 中，
          將 <var translate="no">user-id</var>
          替換為相關使用者的識別碼。
        </p>
      </section>
    </main>
  </body>
  </html>

在這個範例中：

  • <pre><code> 保留並識別多行原始碼。
  • HTML 字元經過轉義，讓範例按字面顯示。
  • <kbd> 識別指令及按鍵操作。
  • <samp> 識別示範用的程式輸出。
  • <var> 識別可替換的值。
  • translate="no" 要求翻譯工具保留電腦可讀取的文字。
  • 程式碼區塊具有焦點提示，並可以水平捲動。
  • 不需要 JavaScript 或語法高亮函式庫。

34.12 常見錯誤

錯誤較好的做法
只使用等寬字型，沒有語意標記按需要選擇 <code>、<kbd> 或 <samp>
以為 <code> 會保留換行配合 <pre> 使用
將原始 HTML 直接貼入程式碼範例轉義標記字元
以為 <pre> 會阻止 HTML 剖析在其中也應轉義標記
意外在程式碼周圍加入縮排控制區塊內的空白字元
使用 lang 識別程式語言使用適當的類別慣例
將 <var> 當成通用斜體元素只用於變數及佔位值
只用顏色提供說明加入清晰文字及語意結構
長程式碼在小螢幕上無法存取提供適當捲動或自動換行
透過 innerHTML 插入不可信字串使用 textContent 顯示字面程式碼
以為程式碼標記會令範例執行另外安全地實作執行功能

本章總結： 使用 <code> 標示電腦程式碼、<pre> 保留有意義的空白字元、<kbd> 標示使用者輸入、<samp> 標示系統輸出，以及 <var> 標示變數或佔位值。應轉義要顯示的標記，保持範例可讀，並且不要將程式碼元素視為不可信內容的安全邊界。

相關文章

Scroll to Top