建立 PDF 註釋 .NET 教程：完整 GroupDocs 指南

介紹

在本教程中，您將學習如何使用 GroupDocs.Annotation 程式庫 建立 PDF 註釋 .NET。無論您是構建合約審閱平台、線上學習系統，或是簡單的桌面工具，以下步驟都能讓您在幾分鐘內從空白專案完成完整的 PDF 註釋。我們將涵蓋安裝、授權、核心 API 使用、常見陷阱、效能技巧以及實務情境，讓您今天就能交付可靠的註釋功能。

快速答覆

  • 可以使用哪個程式庫？ 推薦使用 .NET 版 GroupDocs.Annotation，企業級解決方案。
  • 加入高亮需要多少行程式碼？ 只需兩行：建立 HighlightAnnotation 並呼叫 Add。
  • 需要付費授權嗎？ 免費試用可用於開發；完整授權可移除正式環境的浮水印。
  • 可以註釋大於 100 MB 的 PDF 嗎？ 可以——逐頁處理並使用串流以降低記憶體使用。
  • 是否支援非同步？ API 可包裝於 Task.Run，或在 Web 應用中使用非同步 I/O。

什麼是 create pdf annotations .net？

create pdf annotations .net 指的是在 .NET 應用程式中使用專屬 SDK，程式化地向 PDF 檔案加入視覺註記（如高亮、評論、圖形或印章）的過程。此方式可實現自動化審閱工作流程、協同編輯，以及自訂標記，無需手動使用者介面。

為何選擇 GroupDocs 進行 PDF 註釋？

GroupDocs.Annotation 提供 企業級效能，支援超過 50 種文件格式，且可在不將整個檔案載入記憶體的情況下處理上百頁的 PDF。其簡潔流暢的 API 可較低階 PDF 程式庫縮短開發時間最高達 70 %。此程式庫已在全球數千個正式部署中經受考驗，確保穩定性與安全性。

前置條件與環境設定

開始前需要什麼？

  • IDE： Visual Studio 2019 以上（Community 版亦可）
  • 目標框架： .NET Framework 4.6.2+ 或 .NET Core 2.0+
  • GroupDocs.Annotation： 版本 25.4.0 以上（試用版或正式授權）
  • 基本 C# 知識： 能建立主控台或 Web 專案

安裝 GroupDocs.Annotation for .NET

如何安裝 NuGet 套件？

在套件管理員主控台執行以下指令：

dotnet add package GroupDocs.Annotation --version 25.4.0

如何透過 UI 安裝？

  1. 右鍵點擊專案 → Manage NuGet Packages
  2. 搜尋 GroupDocs.Annotation
  3. 點擊 Install（最新穩定版）

如何使用 .NET CLI 安裝？

在終端機執行此指令：

dotnet add package GroupDocs.Annotation --version 25.4.0

安裝除錯說明： 若遇到相依性衝突，請升級 .NET 版本或使用 dotnet nuget locals all --clear 清除 NuGet 快取。

授權設定（千萬別跳過！）

如何套用授權檔案？

License 類別會載入授權 XML，解鎖全部功能：

using System;
using GroupDocs.Annotation;

class Program
{
    static void Main()
    {
        // Initialize the annotator with your document path
        string inputFilePath = "YOUR_DOCUMENT_DIRECTORY\input.pdf";
        
        using (Annotator annotator = new Annotator(inputFilePath))
        {
            Console.WriteLine("GroupDocs.Annotation for .NET is ready to use.");
        }
    }
}

License 類別是 GroupDocs.Annotation 註冊試用或正式授權的入口，必須在任何其他 SDK 操作之前呼叫。

步驟式實作指南

註釋工作流程如何運作？

註釋工作流程包含四個明確步驟：載入 PDF、建立註釋物件、將物件加入文件，最後儲存修改後的檔案。此線性流程類似一般文字處理編輯循環，讓程式碼易於閱讀與維護，同時確保每個操作以正確順序執行。

步驟 1：載入 PDF 文件

Annotator 類別是存取 PDF 檔案的主要入口。
Annotator 類別代表一個 PDF 文件，提供讀寫與操作註釋的方法。

using (Annotator annotator = new Annotator(inputFilePath))
{
    // Your annotation magic happens here
}

Annotator 類別在記憶體中表示單一 PDF，並公開讀寫與操作註釋的方法。

為何要先驗證路徑？ 因為缺少檔案會拋出 FileNotFoundException，導致工作流程中斷。使用以下防護語句：

if (!File.Exists(inputFilePath))
{
    throw new FileNotFoundException($"PDF file not found: {inputFilePath}");
}

步驟 2：建立第一個註釋

HighlightAnnotation 以半透明顏色標示文字。
HighlightAnnotation 類別定義高亮區域、顏色以及所在頁面。

AreaAnnotation area = new AreaAnnotation()
{
    Box = new Rectangle(100, 100, 100, 100), // x, y coordinates and width & height
    BackgroundColor = 65535, // ARGB color format for transparency
};

HighlightAnnotation 繼承自 AnnotationBase，負責定義高亮區域的視覺外觀。

提示： 先使用較大的座標（例如 200 × 200）驗證位置，再進行微調。

步驟 3：加入註釋

建立註釋物件後，將其加入 Annotator 實例。
Add 方法會將註釋插入當前頁面的註釋集合。

annotator.Add(area);

Add 方法會將註釋插入當前頁面的註釋集合。

步驟 4：儲存已註釋的文件

呼叫 Save 並提供新檔名以持久化變更。
Save 方法將修改後的 PDF 寫入磁碟，亦可指定不同的輸出格式。

string outputPath = "YOUR_OUTPUT_DIRECTORY\result.pdf";
annotator.Save(outputPath);

使用不同檔名儲存可避免意外覆寫，並讓您在比較前後版本時更方便。

完整範例

將所有片段組合即成可執行的主控台應用程式：

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

class Program
{
    static void Main()
    {
        try
        {
            string inputFilePath = @"C:\Documents\input.pdf";
            string outputPath = @"C:\Documents\result.pdf";
            
            // Validate input file exists
            if (!File.Exists(inputFilePath))
            {
                Console.WriteLine("Input PDF file not found!");
                return;
            }
            
            using (Annotator annotator = new Annotator(inputFilePath))
            {
                // Create a highlight annotation
                AreaAnnotation area = new AreaAnnotation()
                {
                    Box = new Rectangle(100, 100, 200, 100),
                    BackgroundColor = 65535, // Yellow highlight
                };
                
                // Add annotation to document
                annotator.Add(area);
                
                // Save the annotated document
                annotator.Save(outputPath);
                
                Console.WriteLine($"Success! Annotated PDF saved to: {outputPath}");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

常見陷阱與避免方式

如何防止生產環境的檔案路徑問題？

使用絕對路徑或結合 Path.Combine 與 AppDomain.BaseDirectory，確保無論當前工作目錄為何，都能正確解析檔案位置。此做法亦能避免不同作業系統的路徑分隔符問題。

string inputFilePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Documents", "input.pdf");

如何避免大型 PDF 記憶體泄漏？

將 Annotator 實例包在 using 區塊中，確保在操作完成後立即釋放非受控資源。此模式可即時釋放檔案句柄與記憶體緩衝，防止長時間服務產生泄漏。

using (Annotator annotator = new Annotator(inputFilePath))
{
    // Work with annotations
} // Automatically disposed here

如何解決座標不對齊？

GroupDocs 使用左上角為原點，而原生 PDF 座標則以左下角為原點。可先測試明顯值（如 50, 50），必要時使用 PageHeight - y 進行調整。了解此差異並套用簡單的轉換公式，即可在所有頁面上正確定位註釋。

如何確保部署後授權仍然有效？

將 GroupDocs.Annotation.lic 檔案與可執行檔一起部署，並在應用程式啟動初期呼叫 License 類別。可透過檢查 License.IsValid（若可用）或捕捉首次 SDK 呼叫時的授權例外來驗證授權狀態。

// Set license before creating Annotator
License license = new License();
license.SetLicense("path/to/your/GroupDocs.Annotation.lic");

進階註釋技巧

如何一次加入多種註釋類型？

GroupDocs.Annotation 支援多種註釋類型，您可以在一次操作中建立文字、箭頭、印章等註釋。只需依序建立每個註釋物件，於儲存前逐一加入，即可有效批次處理複雜的標記情境。

文字（評論）註釋：

TextAnnotation textAnnotation = new TextAnnotation()
{
    Box = new Rectangle(200, 200, 100, 30),
    Message = "This needs review",
    FontColor = 16777215, // White text
    BackgroundColor = 255 // Red background
};

指向箭頭註釋：

ArrowAnnotation arrow = new ArrowAnnotation()
{
    Box = new Rectangle(300, 300, 100, 100),
    Message = "Important section"
};

如何批次處理大量 PDF？

遍歷目錄，為每個檔案實例化 Annotator，套用所需註釋，然後分別儲存。此模式具備良好擴充性，因每個 Annotator 實例相互獨立，避免跨檔案污染，亦可視需求平行處理。

string[] pdfFiles = Directory.GetFiles(@"C:\InputFolder", "*.pdf");

foreach (string pdfFile in pdfFiles)
{
    string outputFile = Path.Combine(@"C:\OutputFolder", 
        Path.GetFileNameWithoutExtension(pdfFile) + "_annotated.pdf");
    
    using (Annotator annotator = new Annotator(pdfFile))
    {
        // Add your annotations
        // Save to output folder
        annotator.Save(outputFile);
    }
}

效能優化建議

如何管理超大型文件的記憶體？

逐頁處理並在完成每頁後釋放對應的 Annotator。將記憶體佔用限制在單一頁面，即使面對數百 MB 的 PDF 也能保持低記憶體使用。

// Good: Dispose immediately after use
using (Annotator annotator = new Annotator(inputFilePath))
{
    // Do your work
    annotator.Save(outputPath);
} // Disposed here

// Bad: Keeping references longer than needed
Annotator annotator = new Annotator(inputFilePath);
// ... lots of other code ...
annotator.Save(outputPath);
annotator.Dispose(); // Too late for efficient memory management

如何在 Web API 中實作非阻塞的註釋呼叫？

將同步呼叫包在 Task.Run 中，或使用非同步串流 I/O，避免阻塞請求執行緒。此技巧可提升 ASP.NET Core 端點在執行 PDF 註釋時的可擴充性。

public async Task<string> AnnotatePdfAsync(string inputPath, string outputPath)
{
    return await Task.Run(() =>
    {
        using (Annotator annotator = new Annotator(inputPath))
        {
            // Add annotations
            annotator.Save(outputPath);
            return outputPath;
        }
    });
}

如何快取常用的已註釋 PDF？

將註釋後的位元組陣列存入分散式快取（如 Redis），在請求時直接回傳。快取可消除重複註釋工作，降低高流量情境的延遲。

private static readonly Dictionary<string, byte[]> AnnotationCache = 
    new Dictionary<string, byte[]>();

private byte[] GetCachedAnnotation(string documentHash)
{
    return AnnotationCache.ContainsKey(documentHash) 
        ? AnnotationCache[documentHash] 
        : null;
}

真實案例與應用

企業如何使用 PDF 註釋？

企業將 PDF 註釋整合至多種業務流程：法務團隊在合約上添加評論與批准印章；教育者在講義上提供回饋；工程師標註技術圖紙；保險公司則高亮保單條款以加速理賠。這些案例展現了程式化 PDF 標記的彈性與價值。

常見問題排除

為何會出現「找不到檔案」錯誤？

此錯誤通常因提供的路徑不正確、檔案被其他程序鎖定，或應用程式缺乏足夠權限所致。請確認路徑使用正確的斜線樣式、檔案確實存在，並授予執行使用者讀寫權限。

為何註釋顯示在錯誤位置？

座標不對齊是因為 GroupDocs 使用左上角為原點，而許多 PDF 工具使用左下角。檢查頁面尺寸（PageWidth、PageHeight），必要時套用 PageHeight - y 轉換。使用簡單座標測試可協助校正定位邏輯。

為何應用程式會耗盡記憶體？

未使用串流處理大型 PDF 會耗盡記憶體。將工作分割為較小批次，啟用 AnnotatorOptions.UseMemoryCache = false 以串流資料，並以 64 位元程序執行以擴增可用位址空間。

為何正式環境會出現浮水印？

使用試用授權時系統會自動加入浮水印。部署完整授權檔案，於任何 SDK 使用前呼叫 License 類別，並確認授權檔案正確放置，即可移除浮水印。

常見問答

Q: 可以註釋除 PDF 之外的檔案類型嗎？
A: 可以。GroupDocs.Annotation 支援 超過 50 種格式，包括 DOCX、XLSX、PPTX 以及常見影像類型，使用相同 API。

Q: 如何開啟受密碼保護的 PDF？
A: 在 Annotator 建構子中傳入密碼：

using (Annotator annotator = new Annotator(inputFilePath, new LoadOptions { Password = "your_password" }))
{
    // Your annotation code
}

Q: 每份文件的註釋數量有限制嗎？
A: 沒有硬性上限，但約 1,000 個註釋 後效能會下降，建議將大型檔案拆分處理。

Q: 能否程式化擷取現有註釋？
A: 使用 Get 方法可取得所有註釋的集合：

List<AnnotationBase> annotations = annotator.Get();

Q: 如何自訂註釋的顏色與字型？
A: 每種註釋類型皆提供外觀屬性，例如在 TextAnnotation 上設定 BackgroundColor 與 Font：

TextAnnotation text = new TextAnnotation()
{
    FontColor = 16777215, // White
    FontSize = 12,
    FontFamily = "Arial",
    BackgroundColor = 255 // Red
};

Q: SDK 在多執行緒 Web 應用中安全嗎？
A: Annotator 實例 不具備執行緒安全；請為每個請求建立新實例或實作同步機制。

Q: 如何移除特定的註釋？
A: 依 ID 找到註釋後呼叫 Delete：

List<AnnotationBase> annotations = annotator.Get();
annotator.Remove(annotations[0]); // Remove first annotation

結論

您現在已掌握使用 GroupDocs.Annotation 建立 PDF 註釋 .NET 的完整、可投入生產的路線圖。從安裝套件與授權、建構高亮、文字、箭頭與批次流程，到處理大型檔案與除錯，每個關鍵環節皆已說明。先挑選簡單案例，實作上述程式碼片段，然後逐步演進至更複雜的工作流程，例如協同審閱或 AI 驅動的標記。

最後更新： 2026-05-21
測試版本： GroupDocs.Annotation 25.4.0 for .NET
作者： GroupDocs

其他資源

{< /blocks/products/pf/tutorial-page-section >} {< /blocks/products/pf/main-container >} {< /blocks/products/pf/main-wrap-class >} {< blocks/products/products-backtop-button >}

相關教程