ปลั๊กอิน 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.NET6.Signer

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

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

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

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

แพลตฟอร์ม. ปลั๊กอินทำงานได้ทุกที่ที่ Doconut.NET6 ทำงาน: 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.

มันจะเกิดข้อผิดพลาดเมื่อไม่มีลิขสิทธิ์, ไฟล์ legacy 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)มีลายน้ำ
ไม่มีลิขสิทธิ์, ไฟล์ legacy TRIAL, ลิขสิทธิ์ที่ไม่มี Signer, หรือ ลิขสิทธิ์แบบชำระเงินที่อยู่นอกช่วงเวอร์ชันAddDoconut() เกิดข้อผิดพลาด——

กฎเดียวกันใช้กับชั้น C# และวิดเจ็ต: ผลลัพธ์จะมีลายน้ำเมื่อลิขสิทธิ์ไม่ใช่ลิขสิทธิ์ viewer แบบชำระเงินหรือเป็นลิขสิทธิ์ชั่วคราว. ภายใต้ลิขสิทธิ์ชั่วคราวปลั๊กอินจะลงนามเสมอด้วยใบรับรอง 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 (ลายเซ็นที่มองเห็นได้ \u002B ซีลดิจิทัล); 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"), คำขอ, และใบรับรอง สำหรับการเรียกนี้. ฟาซาดไม่อ่าน SignerWidgetOptions.SigningCertificate; การตั้งค่านั้นเป็นสำหรับวิดเจ็ต. ส่ง null ภายใต้ใบอนุญาตทดลอง, หรือในโหมด Visual.

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

ลายเซ็น 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;   // \u0022.docx\u0022

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

ข้อยกเว้นข้อความเมื่อ
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 เลือกว่าลายเซ็นจะถูกปิดผนึกหรือไม่.

โหมดสิ่งที่สร้างใบรับรองตรวจสอบได้
SignatureMode.Certified (default)ลายเซ็นที่มองเห็นได้พร้อมกับตราดิจิทัลจำเป็นภายใต้ใบอนุญาตที่ชำระเงินใช่
SignatureMode.Visualลายเซ็นที่มองเห็นได้เท่านั้นไม่เคยต้องการไม่: เป็นเพียงรูปภาพ

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

ตรา PDF คือลายเซ็นแยกส่วน 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, ยังสามารถลงลายเซ็นได้, แต่จะบันทึกเป็นคำเตือนและโปรแกรมอ่าน 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

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

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 สำหรับการลงนามแบบสาธิต (watermarked)
    });
});

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 หรือองค์ประกอบ, จะโยนข้อผิดพลาดหากไม่พบ mount, และคืนค่า handle.

ผู้ลงนามอัปโหลดไฟล์ PDF หรือไฟล์ .docx, สร้างลายเซ็น (วาด บนแคนวาส, พิมพ์ ชื่อในฟอนต์ลายเซ็น, หรือ รูปภาพ จาก 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 ให้เป็นลิงก์ไปยัง URL นี้
signatureModestring'certified'ประเภทลายเซ็นเริ่มต้น: 'certified' หรือ 'visual'. ค่าที่อื่นจะกลายเป็น 'certified'
showSignatureModeTogglebooleantrueแสดงตัวเลือก ลายเซ็นดิจิทัล / เฉพาะภาพ. หากมี false, วิดเจ็ตจะลงนามด้วย signatureMode
wordOutputstring'pdf'ผลลัพธ์เริ่มต้นสำหรับแหล่ง .docx: 'pdf' หรือ 'docx'. ค่าที่อื่นจะกลายเป็น 'pdf'
showOutputFormatTogglebooleantrueแสดงตัวเลือก PDF / Word สำหรับแหล่ง .docx เท่านั้น. หากมี false, วิดเจ็ตจะใช้ wordOutput
labelsobject{}แทนที่ส่วนใดส่วนหนึ่งของสตริงภาษาอังกฤษ

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

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เมื่อคลิกดาวน์โหลดทุกครั้ง{ 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 (multipart, one file)อัปโหลด PDF หรือ .docx และเปิดเพื่อดูตัวอย่าง200 — { token, name, pages, ext }
POST ?sign=run (JSON body)เซ็นไฟล์ที่อัปโหลด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 / h0..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 และไฟล์ต้องถูกเปิดใหม่อีกครั้ง. โทเคนทั้งหมดเป็น GUIDs.

เส้นทางสถานะเมื่อเนื้อหา
ใดก็ได้404วิดเจ็ตไม่ได้เปิดใช้งานเพียงสถานะ
ใดก็ได้405คำกริยาไม่ถูกต้อง (open และ run ต้องการ POST, download ต้องการ GET)เพียงสถานะ
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การประมวลผลล้มเหลวข้อความที่ทำให้ปลอดภัย
download400โทเคนหายไปหรือไม่ใช่ GUIDเพียงสถานะ
download404โทเคนที่ไม่รู้จักหรือหมดอายุเพียงสถานะ

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

javascript
// file: ไฟล์ที่ต้องเซ็น; pngBase64: ลายเซ็นในรูปแบบ base64 PNG แบบไม่มีคำนำ data:,
// เช่น canvas.toDataURL(\u0027image/png\u0027).split(\u0027,\u0027)[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 (เส้นทางมิดเดิลแวร์และเส้นทางทรัพยากร) ภายใต้ต้นทางของ UI ของคุณ.

ในการผลิต

  1. ติดตั้งปลั๊กอิน ข้างแพ็คเกจหลัก, ที่เวอร์ชันเดียวกัน: dotnet add package Doconut.NET6.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. ภายหลังโหลดบาลานเซอร์ที่ไม่มีเซสชันแบบติดหนึบ, คำขอ 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

ส่วนหน้ากากและตัวเลือกวิดเจ็ตอยู่ในเนมสเปซ 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 และ 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‑based; X, Y, W และ H เป็นค่า 0..1 ปกติจากมุมบนซ้าย.

SignatureMode และ 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 ไม่ว่าง
}

ตั้งค่า either 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

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