ปลั๊กอิน Signer

ลงนามเอกสาร PDF และ Word ด้วยลายเซ็นที่มองเห็นได้และตราปิดผนึกดิจิทัล

ปลั๊กอิน Signer จะวางลายเซ็นที่มองเห็นได้บนเอกสารและโดยค่าเริ่มต้นจะปิดผนึกด้วยลายเซ็นดิจิทัลที่โปรแกรมอ่าน PDF สามารถตรวจสอบได้ มันลงนามไฟล์ PDF และ Word (.docx) ลายเซ็นที่มองเห็นได้จะเป็นภาพ PNG เสมอ: วาด, พิมพ์, หรืออัปโหลดโดยผู้ลงนาม

พื้นผิวใช้เมื่อ
DocumentSigner (C#)คุณลงนามบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง
Drop-in widget (doconutSigner.js)คุณต้องการหน้าจออัปโหลด, ลงนาม และดาวน์โหลดที่พร้อมใช้งานในหน้าเว็บของคุณ
HTTP endpoints (?sign=open|run|download)คุณสร้าง UI การลงนามของคุณเองโดยอิงสัญญาเซิร์ฟเวอร์ที่มีเอกสารอธิบาย

ลายเซ็นแต่ละอันจะถูกวางเพียงครั้งเดียวบนหน้าเดียว ชื่อผู้ลงนาม, เหตุผลและตำแหน่งสามารถเดินทางไปพร้อมกับมัน

ติดตั้งแพคเกจ

ติดตั้งปลั๊กอิน Signer รุ่นเสถียรล่าสุด:

bash
dotnet add package Doconut.NET8.Signer

เพื่อระบุเวอร์ชันของปลั๊กอินให้ตรงกับรุ่นที่เอกสารนี้อธิบาย, ส่งเวอร์ชันแยกต่างหาก:

bash
dotnet add package Doconut.NET8.Signer --version 26.10.0

รักษาแพคเกจ Signer ให้เป็นเวอร์ชันเดียวกับ Doconut.NET8. ID ของแพคเกจคือ Doconut.NET8.Signer; .<version> จะปรากฏเฉพาะในชื่อไฟล์ที่ดาวน์โหลด .nupkg.

ไฟล์ใบอนุญาตของปลั๊กอิน, Doconut.Viewer.Signer.lic, จะอยู่ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic; จะถูกอ่านพร้อมกับใบอนุญาตของตัวดู.

แพลตฟอร์ม. ปลั๊กอินทำงานได้ทุกที่ที่ Doconut.NET8 ทำงาน: Windows, และ Linux ที่ใช้ glibc บนสถาปัตยกรรม x64 (ไม่รวม Alpine หรือดิสทริบิวชันที่ใช้ musl อื่นๆ) บน Linux ให้ติดตั้งไลบรารีการกำหนดค่าแบบอักษรก่อนที่เอกสารแรกจะเปิด:

bash
apt-get update && apt-get install -y libfontconfig1

บน RHEL, Fedora และดิสทริบิวชันที่คล้ายกัน แพคเกจคือ fontconfig. หากไม่มีมัน การเปิดเอกสารจะล้มเหลวพร้อมข้อความ The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

ลงทะเบียนปลั๊กอิน

เช่นเดียวกับปลั๊กอิน Doconut ทุกตัว, Signer จะลงทะเบียนกับ AddPlugin<TPlugin>() ภายใน AddDoconut():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

นั่นคือทั้งหมดที่ส่วนต่อประสาน C# ต้องการ วิดเจ็ตและ HTTP endpoint ของมันเป็นการเลือกใช้แยกต่างหาก, AddSignerWidget() (ดูที่ วิดเจ็ตแบบฝังตัว).

ปลั๊กอินต้องการใบอนุญาตที่ให้ความสามารถ Signer หากไม่มี, AddDoconut() จะโยนข้อผิดพลาดขณะเริ่มต้น ก่อนที่แอปจะให้บริการคำขอ:

text
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.

มันจะโยนข้อผิดพลาดเมื่อไม่มีใบอนุญาต, ไฟล์ TRIAL เก่า, ใบอนุญาตที่ไม่มี Signer, และใบอนุญาตแบบชำระเงินที่ใช้เกินช่วงเวอร์ชัน ใบอนุญาต Demo/NFR ชั่วคราวจะได้รับการยอมรับ ดูที่ การตั้งค่าใบอนุญาต เพื่อดูวิธีโหลดใบอนุญาต

การให้ใบอนุญาตและลายน้ำ

สถานะใบอนุญาตการเริ่มต้นลายเซ็นที่รับรองลายเซ็นภาพ
ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer, กำหนดค่าใบรับรองแล้วเริ่มทำงานปิดผนึกด้วยใบรับรองของคุณ, สะอาด (watermarked: false)สะอาด
ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer, ไม่มีใบรับรองเริ่มทำงานปฏิเสธ: No signing certificate configured.สะอาด
ใบอนุญาตแบบชำระเงิน, ใบรับรองหมดอายุหรือยังไม่ถึงวันใช้งานเริ่มทำงาน (พร้อมวิดเจ็ตเปิดใช้งาน, มีการบันทึกคำเตือน)ปฏิเสธ: The signing certificate expired on yyyy-MM-dd.สะอาด
ใบอนุญาต Demo/NFR ชั่วคราว, ยังใช้งานหรือหมดอายุเริ่มทำงานปิดผนึกด้วยใบรับรอง Demo ที่สร้างมาในตัว, มีลายน้ำ (watermarked: true)มีลายน้ำ
ไม่มีใบอนุญาต, ไฟล์ TRIAL เก่า, ใบอนุญาตที่ไม่มี Signer, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันAddDoconut() จะโยนข้อผิดพลาด——

กฎนี้เหมือนกันสำหรับส่วนต่อประสาน C# และวิดเจ็ต: ผลลัพธ์จะมีลายน้ำเมื่อใบอนุญาตไม่ใช่ใบอนุญาตผู้ดูแบบชำระเงินหรือเป็นใบอนุญาตชั่วคราว ภายใต้ใบอนุญาตชั่วคราวปลั๊กอินจะลงนามด้วยใบรับรอง Demo ที่สร้างมาในตัวเสมอ และใบรับรองใดๆ ที่คุณกำหนดจะไม่ได้ใช้

ใบรับรอง Demo สร้างตราปิดผนึกที่แท้จริง แต่โปรแกรมอ่าน PDF จะไม่เชื่อถือมัน การบูรณาการสามารถสร้างและทดสอบแบบครบวงจรบนใบอนุญาตประเมินผล; เพื่อให้ได้ผลลัพธ์ที่สะอาดและเชื่อถือได้ คุณต้องมีทั้งใบอนุญาตแบบชำระเงินและ ใบรับรองการลงนาม ของคุณเอง.

การใช้จาก C#

DocumentSigner ถูกลงทะเบียนโดย AddDoconut() และดึงมาจากการฉีดพึ่งพา. ตัวสร้างของมันเป็น internal, ดังนั้นอย่า new มัน. การดึงโดยไม่มี AddPlugin<SignerPlugin>() จะทำให้เกิด No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // โหมดตั้งค่าเริ่มต้นเป็น Certified (visible signature + digital seal); WordOutput มีค่าเริ่มต้นเป็น Pdf.

        SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
        using (result.Stream)
        using (var output = new MemoryStream())
        {
            await result.Stream.CopyToAsync(output, ct);
            return output.ToArray();
        }
    }
}

SignAsync รับสตรีมต้นทาง, ส่วนขยายของมัน (".pdf" หรือ ".docx"), คำขอ, และใบรับรอง สำหรับการเรียกนี้. ชั้นหน้า (facade) ไม่ได้อ่าน SignerWidgetOptions.SigningCertificate; การตั้งค่านั้นเป็นสำหรับวิดเจ็ต. ส่ง null ภายใต้ใบอนุญาตทดลอง, หรือในโหมด Visual.

SignResult เก็บเอกสารที่ลงนามเป็นสตรีมที่สามารถเลื่อนตำแหน่งได้, พร้อมกับ Extension ของมัน (".pdf" หรือ ".docx") เพื่อให้คุณสามารถตั้งชื่อไฟล์ได้. คุณเป็นเจ้าของสตรีม: ปล่อย (dispose) มันเมื่อเสร็จสิ้น.

ลายเซ็น Visual จะทำการประทับภาพเท่านั้นและไม่ต้องการใบรับรอง:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Image, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    Mode: SignatureMode.Visual);

SignResult result = await signer.SignAsync(stream, ".pdf", request, ct: ct);

แหล่ง Word จะถูกลงนามเป็น PDF เว้นแต่คุณขอผลลัพธ์เป็น Word. ตั้งชื่อผลลัพธ์จาก result.Extension:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Drawn, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    WordOutput: WordOutput.Docx);

SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension;   // ".docx"

SignAsync จะทำการ throw แทนการคืนค่าเมื่อการเรียกไม่สำเร็จ:

ExceptionMessageWhen
InvalidOperationExceptionNo signing certificate configured.โหมด Certified, ใบอนุญาตแบบชำระเงิน, และไม่มีการส่งใบรับรอง
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.โหมด Certified พร้อมใบรับรองที่อยู่นอกช่วงเวลาที่มีผล
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.ไบต์ PNG ว่างเปล่า, หรือการวางตำแหน่งที่ไม่ถูกต้อง
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.ประเภทแหล่งอื่นใด

โหมดการลงนาม, ผลลัพธ์ Word และใบรับรอง

โหมดการลงนาม

SignRequest.Mode เลือกว่าลายเซ็นจะถูกปิดผนึกหรือไม่.

ModeWhat it producesCertificateVerifiable
SignatureMode.Certified (default)ลายเซ็นที่มองเห็นได้พร้อมตราดิจิทัลจำเป็นภายใต้ใบอนุญาตแบบชำระเงินYes
SignatureMode.Visualลายเซ็นที่มองเห็นได้เท่านั้นไม่จำเป็นNo: เป็นเพียงรูปภาพ

ใช้ Certified เมื่อลายเซ็นต้องสามารถพิสูจน์ได้: การอนุมัติ, สัญญา, สิ่งใดที่ผู้ตรวจสอบต้องตรวจสอบเพื่อยืนยันตัวตนและความสมบูรณ์. ใช้ Visual เมื่อคุณต้องการเพียงรูปลักษณ์ของลายเซ็น, หรือไม่มีใบรับรอง. ใบอนุญาตชั่วคราวจะใส่น้ำลายน้ำทั้งสองแบบ.

ตรา PDF คือลายเซ็นแบบแยก (detached) PKCS#7 (adbe.pkcs7.detached) ด้วย SHA-256, สำหรับคีย์ RSA หรือ ECDSA. พวกมันบรรจุใบรับรองของผู้ออกที่พบในไฟล์ PFX ของคุณ, ดังนั้นผู้อ่านที่เชื่อถือรากของคุณสามารถสร้างสายการตรวจสอบได้. ตราที่เป็นของ Word เป็นลายเซ็นแพ็กเกจ OOXML และบรรจุเฉพาะใบรับรองของผู้ลงนามเท่านั้น.

เอกสาร Word

สำหรับแหล่งข้อมูล .docx, SignRequest.WordOutput จะเลือกผลลัพธ์. จะถูกละเว้นสำหรับแหล่งข้อมูล PDF ซึ่งจะสร้าง PDF เสมอ.

ผลลัพธ์สิ่งที่เกิดขึ้นการสนับสนุนตัวตรวจสอบ
WordOutput.Pdf (ค่าเริ่มต้น)เอกสารถูกแปลงเป็น PDF, จากนั้นทำการเซ็นและปิดผนึกกว้าง: PDF ที่เซ็นแล้วตรวจสอบได้ทุกที่
WordOutput.Docxเอกสารถูกเก็บเป็น Word: ภาพลายเซ็นจะถูกวางลงในเอกสาร, พร้อมลายเซ็นแพ็กเกจ OOXMLจำกัด: ไม่ใช่ทุกโปรแกรมแสดงลายเซ็นแพ็กเกจ OOXML

เก็บเป็น PDF เว้นแต่ผู้รับต้องการไฟล์ Word ที่แก้ไขได้และยอมรับการสนับสนุนตัวตรวจสอบที่จำกัด

การตั้งค่าใบรับรอง

เพื่อปิดผนึกด้วยอัตลักษณ์ของคุณเอง, ให้ปลั๊กอินไฟล์ PFX (PKCS#12) ที่รวมคีย์ส่วนตัวไว้. สำหรับวิดเจ็ต, ตั้งค่า SignerWidgetOptions.SigningCertificate; สำหรับฟาซาเด C#, ส่งใบรับรองไปยัง SignAsync. ให้ทั้งไบต์หรือพาธ, พร้อมรหัสผ่าน:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});
csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = "/secure/signing.pfx",
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});

ใบรับรองจะถูกเก็บไว้ในหน่วยความจำเท่านั้น. จะไม่มีการบันทึก, ส่งกลับให้ไคลเอนต์, หรือบันทึกลงฐานข้อมูล, และรหัสผ่านจะไม่ปรากฏในบรรทัดบันทึกหรือข้อความแสดงข้อผิดพลาดใด ๆ

ข้อกำหนด:

  • PFX / PKCS#12 ชุด พร้อมคีย์ส่วนตัว. ไฟล์ที่มีเฉพาะคีย์สาธารณะ (.cer, .crt) ไม่สามารถเซ็นได้. ส่งออกสายการออกใบรับรองพร้อมกับมัน, เพื่อให้ซีล PDF สามารถบรรจุได้
  • รหัสผ่านที่ถูกต้อง
  • อยู่ใน ช่วงเวลาที่ใช้งานได้. ใบรับรองที่หมดอายุหรือยังไม่ถึงวันเริ่มใช้งานจะไม่ทำให้แอปหยุดทำงาน: จะบันทึกเป็น Warning ตอนเริ่มต้น, และลายเซ็น Certified จะถูกปฏิเสธจนกว่าจะเปลี่ยนใหม่. ลายเซ็น Visual จะไม่ได้รับผลกระทบ
  • ออกสำหรับการเซ็นเอกสาร: การใช้คีย์ที่มี digital signature หรือ non-repudiation, และการใช้คีย์ขยาย (extended key usage) หากมี, ที่อนุญาตให้เซ็นเอกสาร, ปกป้องอีเมล หรือยืนยันตัวตนของไคลเอนต์. ใบรับรองที่ออกเพื่อวัตถุประสงค์อื่น, เช่น ใบรับรองเซิร์ฟเวอร์ TLS, ยังคงสามารถเซ็นได้, แต่จะบันทึกเป็น Warning และโปรแกรมอ่าน PDF จะทำเครื่องหมายว่าลายเซ็นนั้น
  • โทเค็นฮาร์ดแวร์, สมาร์ทการ์ด, HSMs และที่เก็บใบรับรองของ Windows ไม่ได้รับการสนับสนุน. ส่งออกใบรับรองพร้อมคีย์ส่วนตัวและสายการออกเป็น PFX

สร้าง PFX จากใบรับรองและคีย์ส่วนตัว ด้วย OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# รหัสผ่านการส่งออกที่คุณถูกขอคือ SigningCertificate.Password.

ส่งออกจากที่เก็บใบรับรองของ Windows: เปิด certmgr.msc และค้นหาใบรับรอง (ไอคอนจะแสดงกุญแจเมื่อมีคีย์ส่วนตัว). คลิกขวา, เลือก All Tasks → Export…, เลือก Yes, export the private key, เลือก Personal Information Exchange – PKCS #12 (.PFX), แล้วตั้งรหัสผ่าน

การตรวจสอบเมื่อเริ่มต้น

เมื่อวิดเจ็ตถูกเปิดใช้งาน, ใบรับรองใน SignerWidgetOptions.SigningCertificate จะถูกตรวจสอบครั้งเดียว, ภายใน AddDoconut(), ดังนั้น PFX ที่กำหนดค่าไม่ถูกต้องจะล้มเหลวตอนเริ่มต้นแทนที่จะเกิดขึ้นที่ลายเซ็นแรก. ปัญหา 3 ประการจะทำให้เกิด InvalidOperationException:

ข้อความวิธีแก้
Doconut Signer: the certificate file was not found at '{path}'.แก้ไข PfxPath; ตรวจสอบให้ไฟล์ถูกปรับใช้และอ่านได้โดยบัญชีของแอป
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.ตรวจสอบรหัสผ่าน; ตรวจสอบให้ไฟล์เป็น .pfx จริง, ไม่ใช่ .cer หรือ .pem
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.ส่งออก PFX อีกครั้งพร้อมคีย์ส่วนตัว

หากไม่มีปัญหา, โฮสต์จะเขียนบรรทัดเดียวลงบันทึกเมื่อเริ่มทำงาน. ข้อมูลเมื่อใบรับรองพร้อมใช้งาน:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

Warning เมื่อใบรับรองหมดอายุ, ยังไม่ถึงวันเริ่มใช้งาน, หรือไม่ได้ออกสำหรับการเซ็นเอกสาร:

text
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.

และ Information เมื่อไม่มีการกำหนดค่าใบรับรอง:

text
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.

บรรทัดสุดท้ายนี้เหมือนกันในทุกไลเซนส์. ใต้ไลเซนส์แบบชำระเงิน, ใบรับรองสาธิตจะไม่ถูกใช้: หากไม่มีใบรับรอง, จะทำงานได้เฉพาะลายเซ็น Visual เท่านั้น

ฟาซาเด C# จะไม่ถูกตรวจสอบตอนเริ่มต้น. ใบรับรองที่คุณส่งไปยัง SignAsync จะถูกอ่านเมื่อคุณเซ็น, ดังนั้นพาธหรือรหัสผ่านที่ผิดจะทำให้การเรียกนั้นล้มเหลว.

วิดเจ็ตแบบดรอปอิน

เปิดใช้งาน endpoints

วิดเจ็ตของ ?sign=open|run|download endpoints มีค่า ปิดโดยค่าเริ่มต้น. เปิดใช้งานพวกมันข้างการลงทะเบียนปลั๊กอิน:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // ค่าเริ่มต้น
        widget.MaxSignatureImageKb = 512;  // ค่าเริ่มต้น
        // widget.SigningCertificate: ดูการตั้งค่า Certificate; ปล่อยให้เป็น null สำหรับการลงนามสาธิต (มีลายน้ำ)
    });
});

AddSignerWidget() โดยไม่มีอาร์กิวเมนต์จะเปิดใช้งานวิดเจ็ตด้วยค่าเริ่มต้น. มันไม่ได้ให้สิทธิ์การลงนามโดยตัวเอง: ต้องการ AddPlugin<SignerPlugin>(), หรือ AddDoconut() จะโยนข้อผิดพลาด:

text
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.

หากไม่มี AddSignerWidget(), ทุกคำขอ ?sign= จะตอบกลับด้วย 404. สคริปต์เองยังคงให้บริการ, ดังนั้นวิดเจ็ตจะโหลดและวาดโซนดรอปของมัน, จากนั้นรายงาน Signing is not enabled on this server. ในคำขอแรกของมัน.

ฝังมัน

UseDoconutResources() ให้บริการสคริปต์ที่ {ResourcesPath}/js/doconutSigner.js (ค่าเริ่มต้น /doconut-res/js/doconutSigner.js). มันเป็นไฟล์เดียวที่รวมทุกอย่างโดยไม่มีการพึ่งพา:

html
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
  const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>

Doconut.signer(selectorOrElement, options) รับ CSS selector หรือ element, จะโยนข้อผิดพลาดหากไม่พบ mount, และคืนค่า handle.

ผู้ลงนามอัปโหลดไฟล์ PDF หรือไฟล์ .docx, สร้างลายเซ็น (วาด บน canvas, พิมพ์ ชื่อในฟอนต์ลายเซ็น, หรือ รูปภาพ จาก PNG, JPG หรือ GIF), ลากและปรับขนาดบนหน้า, แล้วลงนามและดาวน์โหลดผลลัพธ์. วิดเจ็ตจะส่งลายเซ็นเป็น PNG เสมอ; ภาพที่อัปโหลดจะถูกแปลงในเบราว์เซอร์เป็น PNG ที่มีขนาด 520×160.

ตัวเลือก

ตัวเลือกชนิดค่าเริ่มต้นหมายเหตุ
basePathstring'/doconut'ที่ที่ endpoints ?sign= และภาพตัวอย่างถูกให้บริการ
resPathstring'/doconut-res'สงวนไว้; วิดเจ็ตรวม CSS ของตัวเอง
maxUploadMbnumber25ตรวจสอบเฉพาะด้านไคลเอนต์, ดังนั้นไฟล์ที่ใหญ่เกินจะล้มเหลวอย่างรวดเร็ว. ขีดจำกัดของเซิร์ฟเวอร์คือ MaxUploadMb ใน AddSignerWidget
maxSignatureKbnumber512ขีดจำกัดด้านไคลเอนต์สำหรับโหมด Image. ให้เท่ากับ MaxSignatureImageKb ของเซิร์ฟเวอร์
previewWidthnumber560ความกว้างพิกเซลของตัวอย่างหน้า
licenseUrlstring | nullnullเปลี่ยนข้อความแจ้งเตือน demo-watermark ให้เป็นลิงก์ไปยัง URL นี้
signatureModestring'certified'ประเภทลายเซ็นเริ่มต้น: 'certified' หรือ 'visual'. ค่าที่อื่นจะกลายเป็น 'certified'
showSignatureModeTogglebooleantrueแสดงตัวเลือก ลายเซ็นดิจิทัล / เฉพาะภาพ. หากมี false, วิดเจ็ตจะลงนามด้วย signatureMode
wordOutputstring'pdf'ผลลัพธ์เริ่มต้นสำหรับแหล่งที่มาของ .docx: 'pdf' หรือ 'docx'. ค่าที่อื่นจะกลายเป็น 'pdf'
showOutputFormatTogglebooleantrueแสดงตัวเลือก PDF / Word, เฉพาะแหล่งที่มาของ .docx. หากมี false, วิดเจ็ตจะใช้ wordOutput
labelsobject{}แทนที่ส่วนใดส่วนหนึ่งของสตริงภาษาอังกฤษ

การซ่อน toggle ไม่ได้ปิดการทำงานของฟีเจอร์; มันกำหนดค่าคงที่. มีการกำหนดค่าที่พบบ่อยสองแบบ:

javascript
// แสดงสวิตช์ทั้งสอง, ลายเซ็นดิจิทัลเป็นค่าเริ่มต้น: ผู้ลงนามแบบเซลฟ์เซอร์วิสเต็มรูปแบบ.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// แสดงผลอย่างเดียว, ไม่มีสวิตช์: ตราประทับง่ายๆ ที่ไม่มีลายเซ็นดิจิทัล
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

คอลแบ็ก

คอลแบ็กเกิดเมื่อเพย์โหลด
onReadyครั้งเดียว, ที่การ mount (ไม่อีกครั้งบน reset())—
onSourceLoadedไฟล์ถูกเปิดและแสดงตัวอย่างของมัน{ file: { token, name, pages, ext } }
onSignedการลงนามสำเร็จ{ downloadToken, downloadName, watermarked }
onDownloadเมื่อคลิก Download ทุกครั้ง{ downloadName, downloadToken }
onErrorขั้นตอนเปิด, ลงนาม หรือดาวน์โหลดล้มเหลว, หรือไฟล์โหมด Image มีขนาดใหญ่เกินไป{ message }

คอลแบ็กที่โยนข้อยกเว้นจะถูกจับและบันทึก; มันจะไม่ทำให้การทำงานของวิดเจ็ตหยุดชะงัก.

การจัดการเชิงบังคับ

วิธีการพฤติกรรม
reset()กลับไปที่หน้าจอดรอปและล้างการไหลปัจจุบัน ไม่ทำการเรียก onReady อีกครั้ง ไม่ทำอะไรหลังจาก destroy()
loadFile(file)เริ่มการไหลด้วย File. ไม่ทำอะไรหากวิดเจ็ตไม่อยู่ที่หน้าจอดรอป; เรียก reset() ก่อนหากจำเป็น
destroy()ลบผู้ฟัง, ทำให้ mount ว่างเปล่า, และทำให้อินสแตนซ์ค้าง
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/doconut',
  onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
  onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());

ป้ายกำกับ

ทุกสตริงมีค่าเริ่มต้นเป็นภาษาอังกฤษ; labels จะทับส่วนใดส่วนหนึ่งและส่วนที่เหลือจะคงเป็นภาษาอังกฤษ ชิ้นส่วนที่เปลี่ยนแปลงในเวลารันใช้ {placeholders}, เช่น uploading: 'Uploading {name}…' และ pages: '{n} pages'.

คีย์ค่าเริ่มต้นภาษาอังกฤษ
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

คีย์เพิ่มเติมครอบคลุมขั้นตอนการวาง, หน้าจอข้อผิดพลาด, แบบฟอร์มที่เชื่อมโยงของประกาศสาธิต (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) และประกาศ aria-live.

เมื่อ open หรือ run ตอบ 404 โดยไม่มีข้อผิดพลาด JSON, วิดเจ็ตจะแสดง signingNotEnabled. ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะชนะเสมอ, ดังนั้นข้อความเช่นการอัปโหลดที่หมดอายุจะยังคงแสดงอยู่.

การตั้งธีม

วิดเจ็ตเพิ่มคลาส dsw ไปยังองค์ประกอบ mount ของมันและอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ CSS แบบกำหนดเอง, ดังนั้นคุณสามารถตั้งธีมได้โดยไม่ต้องแก้ไขภายใน:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* ลิงก์, โฟกัส, โหมดทำงาน */
  --dsw-bg: #fffaf3;
  --dsw-fg: #3b2a1a;
  --dsw-muted: #8a7a68;
  --dsw-border: #e0cbb0;
  --dsw-radius: 14px;
  --dsw-font: Georgia, "Times New Roman", serif;
  --dsw-signature-font: "Segoe Script", "Brush Script MT", cursive;   /* โหมด Type */
}

ค่าเริ่มต้น: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, ฟอนต์ UI ของระบบ, และฟอนต์ลายเซ็นแบบลายมือ.

สร้างส่วนหน้าของคุณเอง

วิดเจ็ตเป็นไคลเอนต์สำหรับสัญญา HTTP นี้ ทั้งสามเส้นทางอยู่ภายใต้พาธที่ UseDoconut() ถูกเมานท์ (โดยปกติ /doconut), และพวกมันตอบกลับ 404 จนกว่า AddSignerWidget() จะถูกเรียก ข้อผิดพลาดจะมีเนื้อหา JSON, { "error": "..." }, ยกเว้นในกรณีที่ตารางระบุว่า "status only". ค่าที่ไม่รู้จักของ ?sign= จะตอบกลับ 400.

เส้นทางวัตถุประสงค์การตอบสนองสำเร็จ
POST ?sign=open (หลายส่วน, หนึ่งไฟล์)อัปโหลด PDF หรือ .docx และเปิดเพื่อดูตัวอย่าง200 — { token, name, pages, ext }
POST ?sign=run (เนื้อหา JSON)เซ็นไฟล์ที่อัปโหลด200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>สตรีมไฟล์ที่เซ็นแล้ว200 — ไฟล์, Content-Disposition: attachment, Cache-Control: no-store

ext ในการตอบสนอง open มีจุดนำหน้า (".docx"). การแสดงตัวอย่างหน้าใช้เส้นทางรูปภาพผู้ชมมาตรฐาน, {basePath}?token={token}&page={n}&thumb=1&width={px}; หน้าแสดงผลจะกลายเป็น placement.page.

ส่วนเนื้อหา run:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
ฟิลด์หมายเหตุ
tokenโทเค็นจาก open
signature.kindDrawn, Typed หรือ Image, ไม่สนใจตัวพิมพ์ใหญ่/เล็ก; อย่างอื่นจะกลายเป็น Drawn. เพียงแค่บอก: payload จะเป็น PNG เสมอ
signature.payloadPNG base64 แบบเปล่า, ไม่มีคำนำหน้า data:. ต้องเป็น PNG จริงและไม่ใหญ่กว่า MaxSignatureImageKb หลังจากถอดรหัส
placement.pageเริ่มจาก 1
placement.x / y / w / hNormalized 0..1 จากมุมบนซ้าย, พร้อมกับ x + w ≤ 1 และ y + h ≤ 1
meta.signerName / reason / locationเป็นตัวเลือก. แต่ละรายการจะถูกตัดขอบ, ค่าที่ว่างจะถูกละทิ้ง, และแต่ละรายการจะถูกตัดที่ 256 ตัวอักษร
wordOutputpdf (ค่าเริ่มต้น) หรือ docx; จะถูกละเลยสำหรับแหล่ง PDF. อย่างอื่นจะกลายเป็น pdf
modecertified (ค่าเริ่มต้น) หรือ visual. อย่างอื่นจะกลายเป็น certified

downloadName ตามผลลัพธ์: <source>-signed.pdf หรือ <source>-signed.docx, และ download ส่ง Content-Type ที่ตรงกัน.

แหล่งที่อัปโหลดและผลลัพธ์ที่เซ็นจะถูกเก็บไว้แต่ละรายการเป็นเวลา 30 นาที. หลังจากนั้น, run และ download จะตอบกลับ 404 และไฟล์ต้องเปิดใหม่อีกครั้ง. โทเค็นทั้งหมดเป็น GUID.

เส้นทางสถานะเมื่อเนื้อหา
any404วิดเจ็ตไม่ได้เปิดใช้งานstatus only
any405คำกริยาไม่ถูกต้อง (open และ run ต้องการ POST, download ต้องการ GET)status only
open400ไม่ใช่การอัปโหลดแบบ multipartExpected a multipart file upload.
open400ไม่มีไฟล์ หรือไฟล์ว่างNo file uploaded.
open400อย่างอื่นที่ไม่ใช่ .pdf หรือ .docxSigning supports PDF and Word (.docx) files only.
open413การอัปโหลดเกิน MaxUploadMbFile is too large.
run400เนื้อหาไม่เป็น JSON ที่ถูกต้อง, หรือว่างเปล่าMalformed request. / Empty request.
run400โทเค็นหายหรือไม่ใช่ GUIDInvalid token.
run404การอัปโหลดหมดอายุหรือไม่เคยเปิดUpload expired — please re-open the file.
run400ไม่มีลายเซ็น, หรือไม่มีการวางNo signature supplied. / No placement supplied.
run400payload ไม่ใช่ base64, ว่างเปล่า, ใหญ่เกินไป, หรือไม่ใช่ PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400การวางอยู่นอกหน้าThe signature or its placement is invalid.
run400โหมดรับรอง, ใบอนุญาตชำระเงินและไม่มีใบรับรองNo signing certificate configured.
run400โหมดรับรองพร้อมใบรับรองที่อยู่นอกช่วงเวลาที่มีผลThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500การประมวลผลล้มเหลวA sanitized message
download400โทเค็นหายหรือไม่ใช่ GUIDstatus only
download404โทเค็นไม่รู้จักหรือหมดอายุstatus only

การเดินทางรอบสมบูรณ์ด้วย fetch:

javascript
// file: ไฟล์ที่ต้องเซ็น; pngBase64: ลายเซ็นในรูปแบบ base64 PNG, โดยไม่มีคำนำหน้า data:,
// เช่น canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/doconut';

  // 1. open: อัปโหลดไฟล์
  const form = new FormData();
  form.append('file', file, file.name);
  const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();

  // 2. run: เซ็น
  const signed = await (await fetch(base + '?sign=run', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: opened.token,
      signature: { kind: 'Drawn', payload: pngBase64 },
      placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
      meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
      wordOutput: 'pdf',
      mode: 'certified'
    })
  })).json();

  // 3. download: ดึงไฟล์ที่เซ็นแล้ว
  const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = signed.downloadName;
  link.click();
  URL.revokeObjectURL(link.href);
}

จุดเชื่อมต่อเป็น same-origin: เวอร์ชันนี้ไม่มีการสนับสนุน CORS. ให้บริการ UI ของคุณและสคริปต์วิดเจ็ตจากต้นทางเดียวกับ Doconut, หรือทำ reverse-proxy ทั้งสองเส้นทาง /doconut (เส้นทาง middleware และเส้นทาง resources) ภายใต้ต้นทางของ UI ของคุณ.

ในการผลิต

  1. ติดตั้งปลั๊กอิน ข้างๆ แพ็กเกจหลัก, ที่เวอร์ชันเดียวกัน: dotnet add package Doconut.NET8.Signer.

  2. เพิ่มไฟล์ใบอนุญาต วาง Doconut.Viewer.Signer.lic ในโฟลเดอร์เดียวกับ Doconut.Viewer.lic.

  3. รับใบรับรองของคุณเป็น PFX พร้อมกับคีย์ส่วนตัวและสายการออกใบรับรอง, จากหน่วยงานออกใบรับรองหรือ PKI ขององค์กรของคุณ. เพื่อทดลองก่อน, ใช้ใบอนุญาตเดโม (ใบรับรองเดโมในตัว, มีลายน้ำ) หรือ PFX ที่เซ็นด้วยตนเอง.

  4. อ่านใบรับรองจากการกำหนดค่า, ดังนั้นการเปลี่ยนแปลงมันไม่ต้องการการเปลี่ยนแปลงโค้ดเลย:

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var signerSettings = builder.Configuration.GetSection("DoconutSigner");
    
    builder.Services.AddDoconut(options =>
    {
        options.LicensePath = "Doconut.Viewer.lic";
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]),
            Password = signerSettings["Password"] ?? "",
        });
    });

    เก็บ .pfx ไว้นอก wwwroot, และเก็บรหัสผ่านให้อยู่นอก appsettings.json: ความลับของผู้ใช้ในระหว่างการพัฒนา (dotnet user-secrets set "DoconutSigner:Password" "<password>"), ตัวแปรสภาพแวดล้อม (DoconutSigner__Password) หรือคลังข้อมูลในสภาพแวดล้อมการผลิต.

  5. ตรวจสอบบันทึกการเริ่มต้น. ควรอ่านว่า using certificate '{subject}' (valid until …). Signatures are digitally sealed. คำเตือน; หากไม่ใช่หมายความว่าใบรับรองหมดอายุ, ยังไม่เป็นที่ใช้ได้, หรือไม่ได้ออกสำหรับการลงนามเอกสาร.

เชื่อถือในโปรแกรมอ่าน PDF. โปรแกรมอ่านจะแสดงลายเซ็นเป็นที่ถูกต้องเมื่อมันเชื่อถือรากของใบรับรอง. ด้วย PKI ขององค์กรของคุณ, สิ่งนี้จะใช้ได้กับทุกเครื่องที่เชื่อถือรากของคุณ, ซึ่งโดยปกติจะเป็นทุกเครื่องภายในองค์กร. ใบรับรองที่ Adobe เชื่อถือบนเครื่องใดก็ได้ (Adobe Approved Trust List) นั้น, ตามที่เราทราบ, ถูกออกโดยใช้คีย์ส่วนตัวบนโทเค็นฮาร์ดแวร์หรือ HSM, ซึ่งปลั๊กอินนี้ไม่สามารถใช้ได้: มันเซ็นจาก PFX เท่านั้น. ยืนยันกับผู้ให้บริการใบรับรองของคุณก่อนพึ่งพาการเชื่อมั่นแบบนี้.

ฟาร์มเว็บ

วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ไว้ในหน่วยความจำบนโหนดที่ให้บริการ open. ภายหลังโหลดบาลานเซอร์โดยไม่มีเซสชันแบบ sticky, คำขอ run, download หรือการดูตัวอย่างในภายหลังอาจไปถึงโหนดอื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสหนึ่งครั้ง, หลังจาก AddDoconut():

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // โฟลเดอร์ที่ทุกโหนดสามารถอ่านและเขียนได้
    store.FarmKey = farmKey;                   // อย่างน้อย 32 ไบต์, เหมือนกันบนทุกโหนด
    // store.Ttl = TimeSpan.FromMinutes(30);   // ระยะเวลาที่ไฟล์อัปโหลดจะถูกเก็บ (ค่าเริ่มต้น)
});
  • เซิร์ฟเวอร์เดียวไม่ต้องการอะไร: หากไม่มีการเรียกนี้ที่เก็บในหน่วยความจำจะถูกใช้.
  • การอัปโหลดและผลลัพธ์ถูกเข้ารหัสเมื่อพักอยู่บนแชร์ (AES-256, encrypt-then-MAC), และแต่ละไฟล์ถูกผูกกับโทเค็นของมัน, ดังนั้นโทเค็นหนึ่งจะไม่สามารถอ่านไฟล์ของโทเค็นอื่นได้.
  • FarmKey ต้องมีขนาดอย่างน้อย 32 ไบต์และต้องเหมือนกันบนทุกโหนด. โหลดจากที่เก็บความลับ; อย่า hard‑code. การลงทะเบียนจะโยน ArgumentException เมื่อ RootPath ขาดหายหรือ FarmKey สั้นกว่า 32 ไบต์.
  • ตั้งค่า RootPath ให้ชี้ไปยังตำแหน่งที่แชร์เดียวกันที่ตัวดูแบบกระจายใช้, และให้ทุกโหนดใช้ใบรับรองการเซ็นเดียวกัน.

การอ้างอิง API

Facade และตัวเลือกของวิดเจ็ตอยู่ใน namespace Doconut; ประเภทของคำขอและผลลัพธ์อยู่ใน Doconut.Core.Models.Signing. SignerPlugin อยู่ใน Doconut.Plugins.Signer.

DocumentSigner

csharp
public sealed class DocumentSigner
{
    public Task<SignResult> SignAsync(
        Stream source, string sourceExtension, SignRequest request,
        SigningCertificate? cert = null, CancellationToken ct = default);
}

ได้รับการแก้ไขจากการฉีดพึ่งพา; ตัวสร้างเป็น internal. sourceExtension คือ ".pdf" หรือ ".docx". ภายใต้ใบอนุญาตแบบชำระเงิน cert จะถูกใช้และผลลัพธ์จะสะอาด; ภายใต้ใบอนุญาตชั่วคราว ใบรับรองสาธิตในตัวจะถูกใช้, cert จะถูกละเลย, และผลลัพธ์จะมีลายน้ำ.

SignRequest

csharp
public sealed record SignRequest(
    VisibleSignature   Signature,
    SignaturePlacement Placement,
    string?            SignerName = null,
    string?            Reason     = null,
    string?            Location   = null,
    WordOutput         WordOutput = WordOutput.Pdf,
    SignatureMode      Mode       = SignatureMode.Certified)
{
    public bool IsValid { get; }   // Signature.IsValid && Placement.IsValid
}

ลายเซ็นที่มองเห็นได้หนึ่งครั้งที่วางไว้หนึ่งตำแหน่ง, พร้อมเมตาดาต้าของผู้ลงนามที่เป็นตัวเลือก.

VisibleSignature and SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes ไม่ว่างเปล่า
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes เป็น PNG สำหรับทุกประเภท. ลายเซ็นที่วาดหรือพิมพ์จะเป็นแบบโปร่งแสง; ภาพที่อัปโหลดจะคงความโปร่งแสงที่มีอยู่, ดังนั้น JPG ที่ทึบจะยังคงทึบ. Kind เป็นเพียงคำแนะนำ.

SignaturePlacement

csharp
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
    public bool IsValid { get; }   // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}

Page มีค่าเริ่มจาก 1; X, Y, W และ H เป็น 0..1 ที่ทำให้เป็นมาตรฐานจากมุมบนซ้าย.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified เป็นค่าเริ่มต้น
public enum WordOutput { Pdf, Docx }              // Pdf เป็นค่าเริ่มต้น; ถูกละเว้นสำหรับแหล่งที่มาของ PDF

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

เอกสารที่ลงนามเป็นสตรีมที่สามารถเลื่อนตำแหน่งได้, และนามสกุลของมันพร้อมจุด (".pdf" หรือ ".docx").

SigningCertificate

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes ไม่ว่างเปล่า, หรือ PfxPath ไม่ว่าง
}

ตั้งค่า PfxBytes หรือ PfxPath, พร้อมกับ Password.

SignerWidgetOptions

csharp
public sealed class SignerWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
    public int MaxSignatureImageKb { get; set; } = 512;
    public SigningCertificate? SigningCertificate { get; set; }
}

ตั้งค่าผ่าน DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), ซึ่งคืนค่า DoconutOptions เพื่อให้สามารถเรียกต่อกันได้. ค่า null SigningCertificate หมายถึงใบรับรองสาธิตภายใต้ใบอนุญาตชั่วคราว, และลายเซ็น Visual จะใช้ได้เฉพาะใบอนุญาตแบบชำระเงิน.

การแก้ไขปัญหา

อาการสาเหตุวิธีแก้
AddDoconut() โยน The Signer plugin is registered via AddPlugin but no active license grants Signer.ไม่มีใบอนุญาต, ไฟล์ TRIAL, ใบอนุญาตที่ไม่มี Signer, หรือใบอนุญาตแบบชำระเงินที่อยู่นอกช่วงเวอร์ชันของมันติดตั้งใบอนุญาตที่ให้สิทธิ Signer, หรือเอา AddPlugin<SignerPlugin>() ออก
AddDoconut() โยน AddSignerWidget() was called but the Signer plugin is not registered.วิดเจ็ตถูกเปิดใช้งานโดยไม่มีปลั๊กอินของมันเพิ่ม options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() โยน Doconut Signer: the certificate file was not found at '{path}'.PfxPath ชี้ไปที่ไฟล์ที่หายไปแก้ไขเส้นทาง; ปรับใช้ไฟล์ในตำแหน่งที่บัญชีแอปสามารถอ่านได้
AddDoconut() โยน Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.รหัสผ่านผิด, หรือไม่ใช่ไฟล์ PKCS#12ตรวจสอบรหัสผ่าน; ใช้ .pfx จริง
AddDoconut() โยน Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX ถูกส่งออกโดยไม่มีคีย์ส่วนตัวส่งออกอีกครั้งพร้อมคีย์ส่วนตัว
การแก้ไข DocumentSigner โยน No IDocumentSigner is registered.SignerPlugin ยังไม่ได้ลงทะเบียนเพิ่ม AddPlugin<SignerPlugin>() ภายใน AddDoconut()
ผลลัพธ์มีลายน้ำใบอนุญาตเป็นแบบชั่วคราว (Demo/NFR)ใช้ใบอนุญาตแบบชำระเงินที่ให้สิทธิ Signer
run ตอบ 400 No signing certificate configured.ใบอนุญาตแบบชำระเงิน, โหมด Certified, และไม่มีใบรับรองตั้งค่า SigningCertificate, หรือลงนามในโหมด Visual
run ตอบ 400 The signing certificate expired on yyyy-MM-dd.ใบรับรองหมดอายุเปลี่ยนใหม่; ลายเซ็น Visual ยังคงทำงานในระหว่างนี้
บันทึกบอกว่าผลลัพธ์ "ใช้ใบรับรองสาธิตในตัว", แต่ใบอนุญาตแบบชำระเงินปฏิเสธลายเซ็น Certifiedบรรทัดนั้นเขียนขึ้นเมื่อไม่มีการกำหนดค่าใบรับรอง, ไม่ว่าจะแบบใดก็ตามตั้งค่า SigningCertificate
วิดเจ็ตโหลดแล้วแต่บอกว่า Signing is not enabled on this server.AddSignerWidget() ไม่ได้ถูกเรียก, หรือ basePath ไม่ตรงกับตำแหน่งที่ UseDoconut() ถูกเมานท์เรียก AddSignerWidget(); แก้ไข basePath
run ตอบ 400 The signature image must be a PNG., Signature image is not valid base64. หรือ Signature image is too large.UI ที่กำหนดเองส่ง URL data:, JPG, หรือมากกว่า MaxSignatureImageKbส่ง PNG base64 แบบไม่มีส่วนหัวภายในขีดจำกัด
open ตอบ 413 File is too large.การอัปโหลดเกิน MaxUploadMbยก MaxUploadMb ใน AddSignerWidget; maxUploadMb ของวิดเจ็ตเป็นเพียงการตรวจสอบด้านไคลเอนต์
run หรือ download ตอบ 404 Upload expired — please re-open the file.ช่วงเวลา 30 นาทีหมดแล้ว, หรือโหนดเว็บฟาร์มไม่มีไฟล์อัปโหลดเปิดไฟล์อีกครั้ง; ในฟาร์ม, ลงทะเบียน AddDoconutDistributedWidgets
ไฟล์ .docx ที่ลงนามแสดงไม่มีลายเซ็นในบางโปรแกรมดูผลลัพธ์ Word มีลายเซ็นแพ็กเกจ OOXML, ซึ่งโปรแกรมดูหลายตัวไม่แสดงลงนามเป็น PDF, ค่าเริ่มต้น
โปรแกรมอ่าน PDF บอกว่าตัวตนของผู้ลงนามไม่ทราบโปรแกรมอ่านไม่เชื่อถือรากของใบรับรอง (ใบรับรองสาธิตไม่มีวันได้รับความเชื่อถือ)ใช้ใบรับรองจากรากที่โปรแกรมอ่านของคุณเชื่อถือ
วิดเจ็ตล้มเหลวเมื่อ UI อยู่บนต้นทางอื่นendpoint ไม่มีการสนับสนุน CORSให้บริการ UI จากต้นทางเดียวกัน, หรือ reverse-proxy เส้นทาง Doconut
ธีมไม่ทำงานselector ชี้ไปยังองค์ประกอบภายใน mountชี้ไปยัง mount เอง: #host.dsw หรือ #host

หน้านี้เป็นประโยชน์หรือไม่?