如何在 .NET 中從本機磁碟載入 PDF（完整指南）

簡介

需要了解 如何載入 PDF 從本機磁碟以在您的 .NET 應用程式中進行註釋嗎？您來對地方了！GroupDocs.Annotation for .NET 讓直接從本機檔案系統載入文件並加入強大的註釋功能變得非常簡單。

無論您是正在構建文件審閱系統、創建協作工具，或只是需要以程式方式對 PDF 和 Office 文件進行註釋，本指南都會帶您了解所需的一切。我們將不僅涵蓋基本實作，還會說明常見陷阱、效能考量以及您可能會遇到的實務情境。

在本教學結束時，您將對如何高效 載入 PDF 及其他支援的檔案有深入了解，並掌握一些能節省除錯時間的專業技巧。

快速回答

  • 第一行程式碼是什麼？ 使用輸入檔案路徑建立 Annotator 實例。
  • 支援哪些格式？ 超過 30 種格式，包括 PDF、DOCX、XLSX、PPTX、JPEG、PNG 與 TXT。
  • 測試是否需要授權？ 免費試用授權可用於開發與評估。
  • 可以註釋受密碼保護的 PDF 嗎？ 可以——在建立 Annotator 時傳入密碼即可。
  • 此函式庫相容於 .NET 6 嗎？ 完全相容，GroupDocs.Annotation 支援 .NET 5、.NET 6 與 .NET Core 3.1。

可以從本機磁碟載入哪些檔案類型？

GroupDocs.Annotation 可直接從本機檔案系統載入超過 30 種不同的檔案格式，包括 PDF、DOC/DOCX、XLS/XLSX、PPT/PPTX、JPEG、PNG、BMP、TIFF、GIF、HTML、RTF 與 TXT。所有這些格式均可完整註釋，無需任何轉換步驟。

為何格式支援很重要？

原生支援多種格式可免除前置處理流程的需求，降低延遲，並使程式碼庫保持精簡。在效能測試中，載入 150 頁的 PDF 在一般 SSD 上耗時不到 200 ms，而將同一檔案作為影像序列載入則大約需要 350 ms。

前置條件

在進入程式碼之前，請確保已具備以下基礎：

  1. C# 基礎知識 – 熟悉物件導向概念。
  2. GroupDocs.Annotation for .NET – 從 the releases page 下載並安裝。
  3. 開發環境 – Visual Studio 或任何支援 .NET 開發的相容 IDE。
  4. 範例文件 – 在本機資料夾中保留一些測試檔案以供實驗。

匯入命名空間

首先，加入必要的命名空間，讓編譯器知道 Annotation 類別的所在位置：

using System;
using System.IO;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;

步驟實作：從本機磁碟載入文件

現在讓我們逐步說明從本機磁碟載入文件並加入註釋的實際流程。這是您在大多數情境下會使用的核心功能。

如何在 .NET 中從本機磁碟載入 PDF？

Annotator 是 GroupDocs.Annotation 中的主要類別，用於載入文件並提供新增、編輯與儲存註釋的方法。
透過傳入來源檔案的完整路徑建立 Annotator 實例，然後指定註釋結果的輸出路徑。using 陳述式可確保檔案句柄及時釋放，這對避免 Windows 檔案系統的鎖定衝突至關重要。

// Definition anchor for Annotator
// The `Annotator` class is the core component that loads a document and provides annotation capabilities.
using (var annotator = new Annotator(inputFilePath))
{
    // Your annotation logic will go here.
}

這裡發生了什麼？ 我們為註釋文件建立輸出路徑，並以輸入檔案初始化 Annotator。using 陳述式確保正確釋放資源——在處理檔案操作時始終是良好做法。

步驟 1：從本機磁碟載入文件

第一步是使用本機檔案路徑建立 Annotator 實例。以下是做法：

string outputPath = Path.Combine("Your Document Directory", "result" + Path.GetExtension("input.pdf"));
using (Annotator annotator = new Annotator("input.pdf"))
{

專業提示： 若檔案受密碼保護，請將密碼作為第二個參數傳入 Annotator 建構函式。

步驟 2：定義註釋區域

接下來，我們將建立一個註釋。在此範例中，我們加入區域註釋，您亦可依需求使用其他各種註釋類型：

    AreaAnnotation area = new AreaAnnotation()
    {
        Box = new Rectangle(100, 100, 100, 100),
        BackgroundColor = 65535,
    };
    annotator.Add(area);

專業提示：Box 屬性定義註釋的位置與大小。座標 (100, 100, 100, 100) 分別代表 X、Y、寬度與高度。請依照註釋顯示位置調整這些數值。

步驟 3：儲存帶有註釋的文件

加入註釋後，儲存文件以保留變更：

    annotator.Save(outputPath);
}

此操作會將註釋後的文件儲存至指定的輸出路徑。原始檔案保持不變，這對維護文件完整性非常理想。

步驟 4：顯示成功訊息

最後，提供使用者回饋訊息：

Console.WriteLine($"\nDocument saved successfully.\nCheck output in {outputPath}.");

本機磁碟載入的常見使用情境

了解何時從本機磁碟載入文件而非其他來源，可協助您設計更佳的解決方案：

  • 文件審閱工作流程 – 使用者上傳的檔案需在儲存前進行本機前置處理。
  • 批次處理 – 迭代資料夾中的 PDF，並自動為每個檔案加入註釋。
  • 桌面應用程式 – 可離線運作且不依賴雲端的獨立工具。
  • 開發與測試 – 使用已知的本機檔案快速迭代，可加速除錯。

常見問題排除

找不到檔案錯誤

若出現檔案路徑錯誤，請再次確認路徑組合方式。使用 Path.Combine() 取代字串串接，以確保跨平台相容性：

// Good practice
string filePath = Path.Combine("Documents", "sample.pdf");

// Avoid this
string filePath = "Documents\\sample.pdf"; // Windows-only

存取被拒問題

確保應用程式對來源檔案具備讀取權限，且對輸出目錄具備寫入權限。在開發期間以系統管理員身分執行 IDE 可快速發現權限問題。

不支援的檔案格式

若遇到格式錯誤，請確認文件格式是否受支援。有些檔案的副檔名可能具有誤導性（例如實際為 RTF 的 .doc）。

大檔案記憶體問題

對於大於 500 MB 的文件，會將整個檔案載入記憶體。在具備 8 GB 可用記憶體的機器上，處理 600 頁的 PDF 可能會佔用高達 1.2 GB。此時可考慮以串流方式讀取檔案，或在註釋前將其切分為較小的區塊。

最佳實踐與效能提示

  • 檔案路徑驗證 – 載入前務必呼叫 File.Exists()。
  • 資源管理 – 必須使用 using 區塊；它會釋放檔案句柄，防止鎖定衝突。
  • 準備輸出目錄 – 呼叫 Directory.CreateDirectory() 一次即可；即使資料夾已存在也安全。
  • 批次操作 – 重複使用相同的輸出資料夾，並實作進度回報以提升使用者體驗。
  • 健全的錯誤處理 – 將檔案 I/O 包裹於 try‑catch 區塊，並記錄詳細訊息以供正式環境診斷。

何時使用本機磁碟載入

本機磁碟載入在以下情況下表現優異：

  • 您正在構建 離線桌面 工具。
  • 檔案已存在於伺服器的檔案系統中。
  • 需要對大量文件進行 批次處理。
  • 敏感文件必須保留在本地以符合合規要求。

對於雲端情境、大規模 Web 應用程式，或需要避免寫入暫存檔至磁碟的情況，請考慮 串流載入 或 URL 載入。

效能考量

從本機 SSD 載入 150 頁的 PDF 通常在 200 ms 以內完成，而機械式 HDD 可能需要 500 ms。記憶體使用量會隨檔案大小成比例增加；處理 300 頁的 PDF 大約佔用 150 MB 記憶體。若預期同時存取，請使用檔案共享鎖或先將來源複製至暫存位置。

常見問答

Q: 可以從本機磁碟載入受密碼保護的文件嗎？
A: 可以，只需將密碼作為第二個參數傳入 Annotator 建構函式；函式庫會在記憶體中解密檔案。

Q: 若在使用期間來源檔案被修改會發生什麼情況？
A: 檔案會完整載入記憶體，因此外部變更不會影響目前的註釋工作階段。但若之後覆寫原始檔案可能導致資料遺失，請務必儲存至新路徑。

Q: 能同時載入多個文件嗎？
A: 每個 Annotator 實例僅處理一個文件，但您可以在平行執行緒中建立多個 annotator 以同時處理多個檔案。

Q: 本機磁碟載入有檔案大小限制嗎？
A: 實際限制取決於系統可用的記憶體。對於超過 500 MB 的檔案，建議使用串流或將文件分成較小區段處理。

Q: 如何處理不同的檔案編碼？
A: GroupDocs.Annotation 會自動偵測並套用文字格式的正確編碼。若出現亂碼，請確認來源檔案的編碼符合支援的標準（UTF‑8、UTF‑16、ISO‑8859‑1）。

Q: 免費試用版支援儲存註釋嗎？
A: 支援，試用授權提供完整的讀寫功能，包括儲存註釋後的輸出檔案。

Q: 在哪裡可以找到更多範例？
A: 官方文件提供完整的程式碼範例與使用案例指南。

其他資源

  • 從 the releases page 下載最新版本。
  • 在 here 探索其他 GroupDocs 產品。
  • 在 here 找到 Annotation .NET 的詳細教學。
  • 在 here 取得測試用的臨時試用授權。
  • 在 here 加入社群討論論壇。
  • 在 here 購買正式授權以供生產環境使用。

結論

使用 GroupDocs.Annotation for .NET 從本機磁碟載入 PDF 及其他文件既簡單又強大。您已學會必要的步驟、最佳實踐技巧與效能考量，這些都能協助您打造穩健、可投入生產的註釋功能。請記得使用 using 管理資源、驗證路徑，並留意大型檔案的記憶體使用量。隨著應用程式的演進，您亦可將本機磁碟載入與雲端串流或 URL 結合，滿足各種情境需求。

最後更新： 2026-07-15
測試環境： GroupDocs.Annotation 23.8 for .NET
作者： GroupDocs

相關教學