如何新增影像、媒體和資產

使用共享資產儲存和使用媒體

在新增任何影像或媒體（特別是當演示一種媒體內容是次要的技術時）之前，請檢查 mdn/shared-assets 儲存庫中是否已經存在可以使用的內容。將此儲存庫視為一個媒體庫，您可以瀏覽它來為示例選擇合適的資源，而無需擔心儲存、部署或許可。

該儲存庫包含音訊、影片、字型、照片、圖表和圖示等影像，以及 PDF、字幕檔案、顏色配置檔案等各種檔案。如果儲存庫中沒有合適的內容，您可以新增自己的資源以及您要包含的媒體的任何原始檔。您可以在 shared-assets 儲存庫的 HTTP 目錄中找到示例。

要在 MDN 頁面中使用 shared-assets 儲存庫中的任何內容，請參閱專案 README 的在文件中使用共享資產部分。

使用向量格式

通常，如果您要新增影像，尤其是圖表，請考慮使用 SVG 等向量格式，原因如下：

• 作者可以使用任何 IDE 或線上工具直接編輯 SVG。編輯 .png 通常涉及從頭開始重新建立資產或使用影像編輯軟體，這容易出錯並可能引入視覺或壓縮偽影。
• SVG 可以被 Git 差異化。相比之下，.png 檔案在修改時，整個檔案會被作為二進位制檔案更改進行差異化，因此一個 1MB 的 .png 檔案在每次合併提交時（如果被修改）都會使儲存庫大小增加 1MB。
• 靈活的使用者體驗。SVG 是向量格式，因此在任何縮放比例下都不會模糊。

將影像提交到內容儲存庫

如果共享資產儲存庫不適合您的用例，您可以將影像新增到內容（en-US 或 translated-content）儲存庫。要將影像新增到文件中，請將影像檔案新增到文件資料夾中，然後使用Markdown 影像語法或等效的 HTML <img> 元素從文件的 index.md 檔案中引用影像。

我們來看一個例子。

1. 從 mdn 遠端的 main 分支獲取最新內容，開始一個新的工作分支。

   bash

   cd ~/path/to/mdn/content
   git checkout main
   git pull mdn main
   # Run "yarn" to make sure dependencies are up-to-date
   yarn
   git checkout -b my-images
   

2. 將影像新增到文件資料夾。例如，我們假設我們要將新影像新增到 files/en-us/web/css 文件中。

   bash

   cd ~/path/to/mdn/content
   cp ../some/path/my-cool-image.png files/en-us/web/css/
   

3. 對每個影像執行 filecheck，如果出現問題可能會報錯。有關更多詳細資訊，請參閱壓縮影像部分。

   bash

   yarn filecheck files/en-us/web/css/my-cool-image.png
   

4. 使用 Markdown 影像語法在文件中引用您的影像，在方括號之間提供alt 屬性的描述性文字，或者在 files/en-us/web/css/index.md 中包含一個帶 alt 屬性的 <img> 元素。

   md

   ![My cool image](my-cool-image.png)
   <img src="my-cool-image.png" alt="My cool image" />
   

5. 新增並提交所有已刪除、已建立和已修改的檔案，並將您的分支推送到您的 fork。

   bash

   git add files/en-us/web/css/my-cool-image.png files/en-us/web/css/index.html
   git commit
   git push -u origin my-images
   

6. 現在您可以建立拉取請求了。

為影像新增替代文字

每個影像，無論是 ![] 還是 <img>，都必須包含 alt 文字。Alt 屬性應簡短，提供影像傳達的所有相關資訊。在編寫影像描述時，請考慮影像的有價值資訊，以及如何將這些資訊傳達給能夠閱讀頁面內容但無法載入影像的人。

確保影像的替代文字基於其上下文。如果小狗 Fluffy 的照片是 Yuckymeat 狗糧評論旁邊的頭像，那麼 alt="Fluffy" 是合適的。如果同一張照片是 Fluffy 動物救援領養頁面的一部分，則影像中傳達的資訊與潛在狗父母相關，例如 alt="Fluffy，一隻短毛三色梗，嘴裡叼著一個網球。"。周圍的文字可能包含 Fluffy 的大小和品種，因此包含它將是多餘的。避免過於詳細地描述影像：潛在的父母不需要知道狗是在室內還是室外，或者戴著紅色項圈和藍色牽引繩。

對於螢幕截圖，請寫下您從影像中學到的東西，不要詳細描述螢幕截圖的內容，並省略讀者不需要或已經知道的資訊。例如，如果您正在檢視一個關於更改必應設定的頁面，如果您有一個必應搜尋結果的螢幕截圖，請不要包含搜尋詞或結果數量等，因為這些不是影像的重點。將 alt 限制在當前主題：如何更改必應設定。alt 可能是 alt="設定圖示在搜尋欄位下方的導航欄中。"。不要包含“螢幕截圖”或“必應”，因為使用者不需要知道它是螢幕截圖，並且他們已經在解釋更改必應設定的頁面上，所以已經知道它是必應。

Markdown 和 HTML 中的語法

![<alt-text>](<url-of-image>)
<img alt="<alt-text>" src="<url-of-image>">

示例

![OpenWebDocs Logo: Carle the book worm](carle.png)
<img alt="OpenWebDocs Logo: Carle the book worm" src="carle.png" />

雖然純粹裝飾性的影像應該有一個空的 alt 屬性，但新增到 MDN 文件中的影像應該有一個目的，因此需要一個非空字串描述。有關 alt 文字的提示，請參閱alt 決策樹，瞭解如何在各種情況下為影像使用 alt 屬性。

壓縮影像

當您向 MDN Web Docs 頁面新增影像時，您應該確保它們儘可能地壓縮（在不降低質量的情況下），以節省我們讀者的下載大小。事實上，如果您不這樣做，我們的 CI 過程將失敗，並且構建結果將警告您某些影像過大。

壓縮影像的最佳方法是使用內建的壓縮工具。您可以使用 filecheck 命令和 --save-compression 選項適當地壓縮影像。此選項會盡可能地壓縮影像，並用壓縮版本替換原始影像。例如：

yarn filecheck files/en-us/web/css/my-cool-image.png --save-compression

將影片新增到 MDN 頁面

MDN Web Docs 不是一個影片內容很重的網站，但在某些情況下，影片內容作為文章的一部分使用是有意義的。本文討論了何時在文章中包含影片是合適的，並提供了關於如何以低成本建立簡單但有效的影片的技巧。

有幾個反對在技術文件中使用影片內容的論點，特別是對於參考資料和高階指南。其中一些列舉如下：

• 影片是線性的。人們線上性閱讀線上文件時，不習慣從頭到尾閱讀。他們是瀏覽。影片很難瀏覽——它強迫使用者從頭到尾地消費內容。
• 影片的資訊密度低於文字。觀看影片解釋某事所需的時間比閱讀等效說明所需的時間長。
• 影片檔案尺寸大，因此比文字更昂貴，效能也更差。
• 影片存在可訪問性問題：它的製作成本通常高於文字，特別是本地化，或使其可供螢幕閱讀器使用者使用。
• 接著上一點，影片比文字內容更難編輯/更新/維護。

有許多流行的影片網站提供大量的影片教程。MDN Web Docs 不是一個影片驅動的網站，但影片在 MDN Web Docs 中在某些特定上下文中確實有其一席之地。

我們通常在描述某種指令序列或多步驟工作流程時最常用影片，這些工作流程很難用文字簡潔地描述：“執行此操作，然後執行彼操作，然後會發生此情況”。當嘗試描述跨多個應用程式或視窗幷包含可能不容易描述的 GUI 互動的過程時，它特別有用：“現在點選左上角附近看起來有點像鴨子的按鈕”。

在這種情況下，通常更有效的方法是直接展示您的意思。

影片內容指南

MDN Web Docs 的影片內容應：

• 簡短：嘗試將影片時長控制在 30 秒以內，理想情況下是 20 秒以內。這對於讀者的注意力而言足夠短。
• 簡單：儘量使工作流程簡單，2-4 個不同的部分。這使得它們更容易理解。
• 無聲：音訊使影片更具吸引力，但製作起來要耗費更多時間。此外，不得不解釋您正在做什麼會使影片更長，並增加本地化的成本（財務和時間方面）。

要解釋更復雜的內容，您可以使用短影片和螢幕截圖的組合，並穿插文字。文字可以幫助強化影片中提出的觀點，使用者可以根據自己的選擇依賴文字或影片。有關一個很好的示例，請參閱使用動畫檢查器。

此外，您還應該考慮以下提示：

• 影片最終會上傳到 YouTube，然後進行嵌入。我們建議為此用途選擇 16:9 的寬高比，這樣它會填滿整個觀看幀，並且影片的頂部和底部（或左側和右側）不會出現難看的黑邊。因此，例如，您可以選擇 1024×576、1152×648 或 1280×720 的解析度。
• 以高畫質錄製影片，以便上傳後效果更好。
• 對於開發者工具影片，通常最好選擇與頁面內容對比鮮明的主題。例如，如果示例網頁是淺色主題，則選擇深色主題。這樣更容易看清發生了什麼以及開發者工具從何處開始，頁面從何處結束。
• 對於開發者工具影片，儘可能地放大開發者工具，同時仍能顯示所有要顯示的內容並使其看起來正常。
• 確保您要演示的內容沒有被滑鼠游標遮擋。
• 考慮配置螢幕錄製工具以新增滑鼠點選的視覺指示器是否會很有用。

影片工具和軟體

您需要一個錄製影片的工具。這些工具從免費到昂貴，從簡單到複雜不等。如果您已經有建立影片內容的經驗，那太好了。如果沒有，我們建議您從一個簡單的工具開始，如果您開始喜歡建立影片內容並希望建立更有趣的作品，那麼再逐步使用更復雜的工具。

下表提供了一些推薦的優秀入門工具：

QuickTime Player 提示

如果您使用的是 macOS，您應該可以使用 QuickTime Player。使用此工具的錄製步驟非常簡單：

1. 從主選單中選擇檔案 > 新建螢幕錄製。
2. 在螢幕錄製框中，點選錄製按鈕（紅色圓形按鈕）。
3. 拖動一個矩形框住您要錄製的螢幕區域。
4. 按下開始錄製按鈕。
5. 執行您要錄製的任何操作。
6. 按下停止按鈕。
7. 從主選單中選擇檔案 > 匯出為... > 1080p 以高畫質儲存。

其他資源

• 如何在 ScreenFlow 中向螢幕錄製影片新增自定義標註

建立影片的工作流程

以下部分描述了建立影片並將其新增到 MDN Web Docs 文章的一般步驟。

首先，規劃您要捕捉的流程：考慮最佳的起始點和結束點。確保桌面背景和您的瀏覽器配置檔案乾淨整潔。規劃瀏覽器視窗的大小和位置，特別是當您將使用多個視窗時。

仔細規劃您實際要錄製的內容，並在錄製前練習幾次這些步驟。

• 不要在一個過程的中間開始影片——考慮觀看者是否有足夠的上下文來理解您的操作。例如，在一個簡短的 DevTools 影片中，最好從開啟 DevTools 開始，讓觀看者熟悉環境。

• 考慮您的動作是什麼，放慢速度，使其明顯。每當您需要執行一個動作（例如，點選一個圖示）時，請放慢速度，使其明顯。例如：

  • 將滑鼠移到圖示上。
  • 突出顯示或放大（並非總是，取決於是否需要）。
  • 暫停片刻。
  • 點選圖示。

• 規劃要顯示的 UI 部分的縮放級別。並非所有人都能夠以高畫質觀看您的影片。您可以在後期製作中放大特定部分，但最好事先也放大應用程式。

錄製

錄製要展示的工作流程時，請流暢、穩定地執行流程。在關鍵時刻暫停一到兩秒——例如，當您即將點選一個按鈕時。確保滑鼠指標不會遮擋對您要演示的內容重要的任何圖示或文字。

請記住在結束時暫停一到兩秒，以展示流程的結果。

後期處理

您可以在後期製作中突出顯示關鍵時刻。亮點可以包含幾個通常組合在一起的內容，例如：

• 放大螢幕的某些部分。
• 淡化背景。

突出顯示工作流程的關鍵時刻，特別是細節難以看清的地方：例如，點選某個圖示或輸入某個 URL。目標是讓突出顯示持續 1-2 秒。最好在突出顯示的開始和結束時新增一個短暫的過渡（200-300 毫秒）。

這裡要有所剋制：不要讓影片不斷地放大和縮小，否則觀看者會感到暈眩。如果需要，將影片裁剪為所需的寬高比。

上傳和嵌入影片

影片目前必須上傳到 YouTube 才能在 MDN Web Docs 上顯示，例如上傳到 mozhacks 頻道。如果您沒有合適的地方放置影片，請聯絡 MDN Web Docs 團隊成員上傳影片。

嵌入

上傳後，您可以使用 EmbedYouTube 宏將影片嵌入頁面。方法是將其插入到頁面中您希望影片出現的位置：

{{EmbedYouTube("you-tube-url-slug")}}

宏呼叫所需的唯一屬性是影片 URL 末尾的字串，而不是整個 URL。例如，如果影片 URL 是 https://www.youtube.com/watch?v=ELS2OOUvxIw，則所需的宏呼叫將是：

{{EmbedYouTube("ELS2OOUvxIw")}}

另見

• 使用 SVG 格式代替 .png 影像 MDN GitHub 討論