在 Java 中使用 GroupDocs 建立漸層數位簽章

如果您需要 create gradient digital signature 物件，外觀精緻、符合品牌色彩，同時仍符合密碼學標準，您來對地方了。在本教學中，我們將一步步說明從將 GroupDocs.Signature 函式庫加入專案、設定線性漸層筆刷、定位簽章，到處理常見的陷阱。完成後，您只需幾行 Java 程式碼，即可在 PDF、Word 檔或圖片中嵌入視覺上吸引人的漸層簽章。

快速回答

  • 什麼是漸層數位簽章？ 使用顏色漸層作為背景或文字填充的數位簽章視覺元素。
  • 哪個程式庫在 Java 中支援此功能？ GroupDocs.Signature for Java 內建漸層筆刷支援。
  • 漸層會影響密碼學安全性嗎？ 不會。漸層純屬視覺效果，底層的數位簽章保持不變。
  • 需要哪個 Java 版本？ JDK 8 或以上（建議 JDK 11+）。
  • 正式環境需要授權嗎？ 需要——非評估使用必須擁有有效的 GroupDocs.Signature 授權。

為什麼在數位簽章中使用漸層筆刷？

漸層筆刷可讓您為簽章背景加入符合品牌的顏色過渡，使已簽署的文件感覺更專業且值得信賴。漸層簽章提升視覺層次，協助辨識批准等級，並在不影響簽章密碼完整性的前提下加強企業形象。

您將學到什麼

在本教學中，您將學會如何設定 GroupDocs.Signature 函式庫、建立使用線性漸層筆刷的文字簽章、調整顏色、透明度與位置等視覺屬性，並解決實作過程中常見的問題。指南亦涵蓋效能優化與最佳實踐模式，讓簽章程式碼乾淨且可重用。

  • 設定 GroupDocs.Signature for Java（Maven、Gradle 或手動）
  • 使用線性漸層筆刷 create gradient digital signature 物件
  • 自訂外觀、定位與透明度
  • 疑難排解常見問題並最佳化效能
  • 套用可維護的簽章程式碼最佳實踐模式

前置條件

開始之前，請確保您已具備：

  • Java Development Kit (JDK) 8 或以上（建議 JDK 11+）
  • IDE （IntelliJ IDEA、Eclipse 或具 Java 擴充功能的 VS Code）
  • GroupDocs.Signature for Java 函式庫（透過 Maven、Gradle 或手動 JAR 加入）
  • 基本的 Java 物件、方法與例外處理概念

必要函式庫

使用您偏好的建置工具將 GroupDocs.Signature 加入專案。

Maven（加入至 pom.xml）:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

Gradle（加入至 build.gradle）:

implementation 'com.groupdocs:groupdocs-signature:23.12'

手動安裝：若未使用建置工具（雖建議使用），請從 GroupDocs Signatures releases 下載 JAR，並加入 classpath。

授權取得

GroupDocs 提供開發用的免費試用，但商業使用必須取得正式授權。

  1. 免費試用 – 從 GroupDocs Free Trial 下載
  2. 臨時授權 – 於 GroupDocs Temporary License 取得 30 天測試金鑰，完整體驗全部功能
  3. 正式授權 – 透過定價入口購買，用於正式上線

試用版會加上評估浮水印，請於向客戶發布應用程式前取得臨時或正式授權。

設定 GroupDocs.Signature for Java

讓我們先把環境建好。此步驟適用於新專案，也適用於既有程式碼庫的整合。

安裝步驟

  1. 加入相依性（如上所述）。
  2. 驗證安裝：建立簡易測試類別：
import com.groupdocs.signature.Signature;

public class SignatureTest {
    public static void main(String[] args) {
        System.out.println("GroupDocs.Signature loaded successfully!");
    }
}

若此程式編譯無誤，即可繼續。

  1. 整理文件資料夾 – 清晰的結構有助於大量檔案的處理：
project-root/
├── src/
├── resources/
│   ├── input/        // Source documents to sign
│   └── output/       // Signed documents
└── pom.xml (or build.gradle)
  1. 基本初始化 – Signature 物件是所有簽署操作的入口：
import com.groupdocs.signature.Signature;
import com.groupdocs.signature.exception.GroupDocsSignatureException;

public class BasicSignatureSetup {
    public static void main(String[] args) {
        try {
            // Initialize with your source document path
            Signature signature = new Signature("resources/input/sample.pdf");
            
            // Your signing code will go here
            
            signature.dispose(); // Always clean up resources
        } catch (GroupDocsSignatureException e) {
            System.err.println("Signature error: " + e.getMessage());
            e.printStackTrace();
        } catch (Exception e) {
            System.err.println("General error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

小技巧：將 Signature 實例放在 try‑with‑resources 區塊中，或手動呼叫 dispose()。未釋放檔案句柄會導致「檔案被使用」錯誤。

實作指南：建立漸層簽章

接下來，我們將一步步完成 create gradient digital signature。

步驟 1：初始化簽章選項

首先定義簽章內容。TextSignOptions 類別負責文字型簽章。

定義說明：TextSignOptions 代表文字簽章的設定，包括文字內容、字型、顏色與視覺效果。

import com.groupdocs.signature.domain.enums.HorizontalAlignment;
import com.groupdocs.signature.domain.enums.VerticalAlignment;
import com.groupdocs.signature.domain.signatures.TextSignOptions;

TextSignOptions options = new TextSignOptions("John Smith");

此程式碼片段會產生一個顯示「John Smith」的基本簽章，預設為黑色文字、透明背景——相當單調。

步驟 2：使用漸層筆刷自訂背景

接著套用線性漸層筆刷，讓簽章更具質感。

定義說明：LinearGradientBrush 描述沿直線填滿形狀的顏色過渡，由起始與結束顏色以及角度決定。

import com.groupdocs.signature.domain.Background;
import com.groupdocs.signature.domain.extensions.brushes.LinearGradientBrush;
import java.awt.Color;

// Create the background container
Background background = new Background();
background.setColor(Color.GREEN);        // Fallback color (rarely seen)
background.setTransparency(0.5f);         // 50% transparency (0.0 = opaque, 1.0 = invisible)

// Define the gradient: start color, end color, and angle
LinearGradientBrush brush = new LinearGradientBrush(
    Color.GREEN,    // Start color (left/top)
    Color.WHITE,    // End color (right/bottom)
    45              // Angle in degrees (45 = diagonal)
);

// Apply the brush to the background
background.setBrush(brush);
options.setBackground(background);

重點說明：

  • setColor(Color.GREEN) 為在無法渲染漸層時的備援純色。
  • setTransparency(0.5f) 讓簽章半透明，避免遮蔽底層文字。值接近 0 為不透明，接近 1 為幾乎看不見。
  • 角度 45 產生左上至右下的對角過渡。0 為水平，90 為垂直，亦可自行設定其他角度。

選擇符合品牌的顏色（例如藍‑白代表信任，綠‑白代表核准）可讓簽章一眼即被辨識。

步驟 3：設定簽章位置

現在告訴引擎在頁面上放置簽章的位置。

定義說明：SignatureOptions（所有選項類型的基底類別）保存共通屬性，如對齊方式、邊距與尺寸。

import com.groupdocs.signature.domain.Padding;

// Set signature dimensions (in pixels or points, depending on document)
options.setWidth(100);
options.setHeight(80);

// Center the signature both horizontally and vertically
options.setVerticalAlignment(VerticalAlignment.Center);
options.setHorizontalAlignment(HorizontalAlignment.Center);

// Add margins to fine‑tune positioning
Padding padding = new Padding();
padding.setTop(20);      // 20 units from the alignment point
padding.setRight(20);    // 20 units from the right edge
options.setMargin(padding);

對齊與邊距的差異：

  • Alignment 鎖定簽章（例如 HorizontalAlignment.Right）。
  • Margin 偏移鎖定點（例如 setMarginTop(-10)）。

常見配置：

目標位置HorizontalAlignmentVerticalAlignment常用邊距設定
右下角RightBottomsetMarginTop(-20)
頁眉區RightTopsetMarginTop(20)
頁面中心CenterCentersetMarginLeft(0)

依文字長度與文件頁面大小調整 setWidth 與 setHeight。

步驟 4：套用簽章並儲存

最後，對文件簽章並將結果寫入新檔。

定義說明：SignResult 提供簽署作業的詳細資訊，包括成功與失敗的簽章。

import com.groupdocs.signature.Signature;
import com.groupdocs.signature.domain.SignResult;

try {
    // Initialize signature with source document
    Signature signature = new Signature("resources/input/sample.pdf");
    
    // Apply the signature options we configured above
    SignResult result = signature.sign("resources/output/SignedWithGradient.pdf", options);
    
    // Check the result
    if (result.getSucceeded().size() > 0) {
        System.out.println("Document signed successfully!");
        System.out.println("Signed with " + result.getSucceeded().size() + " signature(s)");
    } else {
        System.out.println("No signatures were applied.");
    }
    
    // Clean up
    signature.dispose();
    
} catch (Exception e) {
    System.err.println("Error signing document: " + e.getMessage());
    e.printStackTrace();
}

sign() 方法接受來源檔案、套用已設定的選項，並產生包含視覺簽章的新檔，原檔保持不變。務必檢查 signResult.getSucceeded() 以確認成功。

完整範例程式

以下為可直接複製、執行的完整類別：

import com.groupdocs.signature.Signature;
import com.groupdocs.signature.domain.Background;
import com.groupdocs.signature.domain.Padding;
import com.groupdocs.signature.domain.SignResult;
import com.groupdocs.signature.domain.enums.HorizontalAlignment;
import com.groupdocs.signature.domain.enums.VerticalAlignment;
import com.groupdocs.signature.domain.extensions.brushes.LinearGradientBrush;
import com.groupdocs.signature.domain.signatures.TextSignOptions;
import java.awt.Color;

public class GradientSignatureExample {
    public static void main(String[] args) {
        try {
            // Initialize signature object with source document
            Signature signature = new Signature("resources/input/sample.pdf");
            
            // Configure text signature options
            TextSignOptions options = new TextSignOptions("John Smith");
            
            // Create gradient background
            Background background = new Background();
            background.setColor(Color.GREEN);
            background.setTransparency(0.5f);
            
            LinearGradientBrush brush = new LinearGradientBrush(
                Color.GREEN,  // Start color
                Color.WHITE,  // End color
                45            // Angle
            );
            
            background.setBrush(brush);
            options.setBackground(background);
            
            // Set positioning
            options.setWidth(100);
            options.setHeight(80);
            options.setVerticalAlignment(VerticalAlignment.Center);
            options.setHorizontalAlignment(HorizontalAlignment.Center);
            
            Padding padding = new Padding();
            padding.setTop(20);
            padding.setRight(20);
            options.setMargin(padding);
            
            // Sign and save
            SignResult result = signature.sign(
                "resources/output/SignedWithGradient.pdf", 
                options
            );
            
            System.out.println("Success! Signatures applied: " + 
                result.getSucceeded().size());
            
            signature.dispose();
            
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

將 PDF 放置於 resources/input/ 後執行程式，輸出檔即會包含時尚的漸層簽章。

常見應用情境

1. 企業合約管理

不同批准層級可使用不同漸層顏色——例如主管使用藍‑白、法務使用金‑白、主管層使用深藍‑淺藍。此視覺層次讓審核者立即辨識簽署者。

2. 自動化發票處理

在發票上套用細膩的品牌漸層後再寄給客戶，既專業又不影響可讀性。

3. 證書產生

使用鮮豔的漸層（紫‑粉、金‑黃）製作證書，使其更具官方感與分享價值。

4. 文件浮水印

將漸層技術套用於透明文字，製作「草稿」「機密」或「已批准」的浮水印，且不會遮蔽內容。透明度設為 0.7‑0.8 可得到柔和效果。

疑難排解常見問題

以下列出我在使用漸層簽章時遇到（並解決）的問題。

問題 1：「檔案被其他程序使用中」

直接回答（40‑70 字）：此例外發生是因為 Signature 物件仍持有開啟的檔案句柄。簽署完畢後務必關閉或釋放 Signature 實例。使用 try‑with‑resources 區塊可自動釋放檔案，避免後續操作出現「檔案被使用」錯誤。

解決方案：

// Always use try‑with‑resources (Java 7+)
try (Signature signature = new Signature("path/to/document.pdf")) {
    // Your signing code here
} catch (Exception e) {
    // Handle errors
}
// File handle automatically released when try block exits

或手動：

Signature signature = null;
try {
    signature = new Signature("path/to/document.pdf");
    // Your signing code
} finally {
    if (signature != null) {
        signature.dispose();
    }
}

問題 2：簽章顯示但漸層未出現

直接回答：若檢視器不支援漸層、透明度設定為 1.0，或筆刷未正確附加，漸層都可能看不到。請確認使用支援的 PDF 檢視器（Adobe Acrobat、Foxit 或現代瀏覽器），將透明度設定在 0.3‑0.7 之間，並確保呼叫 background.setBrush(brush) 與 options.setBackground(background)。

可能原因：

  1. 檢視器不支援漸層 – 改用較新檢視器測試。
  2. 透明度過高 – 降至 0.3‑0.7。
  3. 未套用筆刷 – 再次確認方法呼叫。

除錯小技巧：先使用高對比色（如紅‑藍）驗證漸層是否正確渲染，再進行微調。

問題 3：簽章覆蓋重要文件內容

直接回答：當定位值將簽章放在既有文字或表單欄位上時，就會發生覆蓋。可動態計算空白區域，或使用頁面層級分析自動重新定位簽章。

解決模式：

// For documents with content primarily at the top
options.setVerticalAlignment(VerticalAlignment.Bottom);
Padding padding = new Padding();
padding.setBottom(30);  // Leave space from bottom edge
options.setMargin(padding);

// For documents that need signatures in specific locations
options.setVerticalAlignment(VerticalAlignment.Top);
options.setHorizontalAlignment(HorizontalAlignment.Left);
padding.setTop(600);     // Absolute Y position
padding.setLeft(400);    // Absolute X position
options.setMargin(padding);

問題 4：大型文件的效能問題

直接回答：簽署大型 PDF 可能較慢，因為 GroupDocs 會處理整個檔案並為每頁渲染漸層。可限制簽署特定頁面、使用簡單的雙色漸層、縮小簽章尺寸，並以非同步方式執行，以保持 UI 響應。

效能範例：

// Faster configuration
TextSignOptions options = new TextSignOptions("Approved");
options.setWidth(80);   // Smaller than default 100
options.setHeight(60);  // Smaller than default 80

// Simple horizontal gradient (fastest)
LinearGradientBrush brush = new LinearGradientBrush(
    Color.BLUE, 
    Color.WHITE, 
    0  // Horizontal gradient
);

問題 5：顏色與預期不符

直接回答：顏色偏差可能來自 RGB 到 PDF 色彩空間的轉換、透明度混合或螢幕校色差異。請使用精確的 sRGB 值、將透明度維持在 0.3‑0.5，並在多種檢視器上測試，以確保品牌色彩一致。

生產環境最佳實踐

實踐為何重要
在輔助類別中集中樣式設定確保所有文件的外觀一致
簽署前驗證來源文件防止損毀檔案中斷簽署流程
記錄每一次簽署操作提供合規審計追蹤
優雅處理例外在非預期情況下保持服務穩定
使用真實 PDF（表單、掃描圖、已有簽章）測試確保漸層在各種情境下皆能正確呈現

輔助類別範例：

public class SignatureStyles {
    public static TextSignOptions getApprovalSignature(String signerName) {
        TextSignOptions options = new TextSignOptions(signerName);
        
        Background background = new Background();
        background.setTransparency(0.4f);
        
        LinearGradientBrush brush = new LinearGradientBrush(
            new Color(0, 102, 204),  // Brand blue
            Color.WHITE,
            45
        );
        
        background.setBrush(brush);
        options.setBackground(background);
        
        // Standard positioning
        options.setWidth(100);
        options.setHeight(70);
        
        return options;
    }
    
    // Add more style methods as needed
}

文件驗證程式碼：

try {
    Signature signature = new Signature("path/to/document.pdf");
    
    // Validate format
    if (!"PDF".equalsIgnoreCase(signature.getDocumentInfo().getFileType())) {
        throw new IllegalArgumentException("Only PDF files supported");
    }
    
    // Ensure at least one page
    if (signature.getDocumentInfo().getPageCount() < 1) {
        throw new IllegalArgumentException("Document has no pages");
    }
    
    // Proceed with signing...
    
} catch (Exception e) {
    // Handle validation errors
}

日誌範例：

SignResult result = signature.sign(outputPath, options);
logger.info("Document signed: " + outputPath);
logger.info("Signatures applied: " + result.getSucceeded().size());
logger.info("Signer: " + signerName);
logger.info("Timestamp: " + LocalDateTime.now());

if (!result.getFailed().isEmpty()) {
    logger.warn("Failed signatures: " + result.getFailed().size());
}

例外處理模式：

try {
    SignResult result = signature.sign(outputPath, options);
    return result.getSucceeded().size() > 0;
} catch (GroupDocsSignatureException e) {
    logger.error("Signature error: " + e.getMessage());
    return false;
} catch (IOException e) {
    logger.error("File I/O error: " + e.getMessage());
    return false;
} catch (Exception e) {
    logger.error("Unexpected error during signing: " + e.getMessage());
    return false;
}

進階使用者小技巧

小技巧 1：建立自訂色彩方案

一次定義品牌調色盤，之後重複使用：

public class BrandColors {
    public static final Color PRIMARY   = new Color(0, 102, 204);
    public static final Color SECONDARY = new Color(102, 178, 255);
    public static final Color ACCENT    = new Color(255, 193, 7);
    
    public static LinearGradientBrush getPrimaryGradient(int angle) {
        return new LinearGradientBrush(PRIMARY, Color.WHITE, angle);
    }
}

小技巧 2：根據文件類型動態調整透明度

public static float getOptimalTransparency(Signature signature) {
    if (hasComplexBackground(signature)) {
        return 0.6f; // More transparent for image‑heavy docs
    }
    return 0.4f;
}

小技巧 3：使用執行緒池進行批次處理

ExecutorService executor = Executors.newFixedThreadPool(4);
List<String> files = getDocumentsToSign();

for (String file : files) {
    executor.submit(() -> {
        try {
            signDocument(file);
        } catch (Exception e) {
            logger.error("Failed to sign: " + file, e);
        }
    });
}
executor.shutdown();
executor.awaitTermination(5, TimeUnit.MINUTES);

小技巧 4：根據簽章類型套用條件樣式

public static TextSignOptions getStyledSignature(String name, SignatureType type) {
    TextSignOptions options = new TextSignOptions(name);
    LinearGradientBrush brush;
    switch (type) {
        case APPROVAL:   brush = new LinearGradientBrush(Color.GREEN, Color.WHITE, 45); break;
        case REJECTION:  brush = new LinearGradientBrush(Color.RED,   Color.WHITE, 45); break;
        case REVIEW:     brush = new LinearGradientBrush(Color.ORANGE,Color.WHITE,45); break;
        default:         brush = new LinearGradientBrush(Color.BLUE,  Color.WHITE,45);
    }
    Background bg = new Background();
    bg.setBrush(brush);
    bg.setTransparency(0.5f);
    options.setBackground(bg);
    return options;
}

常見問答

Q: 可以在基於 Web 的 Java 服務中使用嗎？
A: 可以。GroupDocs.Signature 為純 Java 程式庫，適用於任何 Java 後端，包括 Spring Boot、Jakarta EE 或微服務框架。

Q: 漸層會增加簽署後 PDF 的檔案大小嗎？
A: 只會略微增加。漸層以視覺外觀串流儲存，通常只會多幾 KB。

Q: 如何簽署受密碼保護的 PDF？
A: 在建立 Signature 物件時傳入密碼，例如 new Signature("file.pdf", "password")。

Q: 能否將漸層套用於圖像型簽章，而非文字？
A: 完全可以。使用 ImageSignOptions，並像文字範例一樣為其 Background 設定 LinearGradientBrush。

Q: 若需要徑向漸層而非線性漸層該怎麼辦？
A: 目前 GroupDocs 只支援 LinearGradientBrush。若需徑向效果，可先產生徑向漸層 PNG，然後作為背景圖使用。

最後更新： 2026-07-25
測試環境： GroupDocs.Signature 23.12 for Java
作者： GroupDocs

相關教學