ปลั๊กอิน Signer
ลงนามเอกสาร PDF และ Word ด้วยลายเซ็นที่มองเห็นได้และตราดิจิทัล
ปลั๊กอิน Signer จะวางลายเซ็นที่มองเห็นได้บนเอกสารและโดยค่าเริ่มต้นจะปิดผนึกด้วยลายเซ็นดิจิทัลที่โปรแกรมอ่าน PDF สามารถตรวจสอบได้ มันลงนามไฟล์ PDF และ Word (.docx) ไฟล์ ลายเซ็นที่มองเห็นได้จะเป็นภาพ PNG เสมอ: วาด, พิมพ์, หรืออัปโหลดโดยผู้ลงนาม.
| วิธี | ใช้เมื่อ |
|---|---|
DocumentSigner (C#) | คุณลงนามบนเซิร์ฟเวอร์โดยไม่มีเบราว์เซอร์เข้ามาเกี่ยวข้อง |
Drop-in widget (doconutSigner.js) | คุณต้องการหน้าจออัปโหลด, ลงนามและดาวน์โหลดที่พร้อมใช้งานในหน้าของคุณ |
HTTP endpoints (?sign=open|run|download) | คุณสร้าง UI การลงนามของคุณเองตามสัญญาเซิร์ฟเวอร์ที่มีเอกสารอธิบาย |
ลายเซ็นแต่ละอันจะถูกวางเพียงครั้งเดียวบนหน้าเดียว. ชื่อผู้ลงนาม, เหตุผลและตำแหน่งสามารถเดินทางพร้อมกับลายเซ็นได้.
ติดตั้งแพคเกจ
ติดตั้งปลั๊กอิน Signer รุ่นเสถียรล่าสุด:
dotnet add package Doconut.NET6.Signerเพื่อระบุเวอร์ชันของปลั๊กอินให้ตรงกับรุ่นที่เอกสารนี้อธิบาย, ส่งเวอร์ชันแยกต่างหาก:
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, ติดตั้งไลบรารีการกำหนดค่าแบบอักษรก่อนที่เอกสารแรกจะเปิด:
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():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});นั่นคือทั้งหมดที่ชั้น C# ต้องการ. วิดเจ็ตและ HTTP endpoint ของมันเป็นการเลือกใช้แยกต่างหาก, AddSignerWidget() (ดู วิดเจ็ตแบบดรอปอิน).
ปลั๊กอินต้องการลิขสิทธิ์ที่ให้ความสามารถ Signer. หากไม่มี, AddDoconut() จะเกิดข้อผิดพลาดขณะเริ่มต้น, ก่อนแอปจะให้บริการคำขอ:
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>().
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 จะประทับภาพเท่านั้นและไม่ต้องการใบรับรอง:
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:
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\u0022SignAsync จะโยนข้อยกเว้นแทนการคืนค่าเมื่อการเรียกไม่สำเร็จ:
| ข้อยกเว้น | ข้อความ | เมื่อ |
|---|---|---|
InvalidOperationException | No signing certificate configured. | โหมด Certified, ใบอนุญาตแบบชำระเงิน, และไม่มีการส่งใบรับรอง |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | โหมด Certified ที่มีใบรับรองอยู่นอกช่วงเวลาที่ใช้ได้ |
ArgumentException | The sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page. | ไบต์ PNG ว่างเปล่า, หรือการวางตำแหน่งที่ไม่ถูกต้อง |
NotSupportedException | The 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. ให้ข้อมูลเป็นไบต์หรือเส้นทาง พร้อมรหัสผ่าน:
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"],
};
});
});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:
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 อีกครั้งพร้อมคีย์ส่วนตัว |
หากไม่เช่นนั้น โฮสต์จะเขียนบรรทัดเดียวลงในบันทึกเมื่อเริ่มทำงาน. ข้อมูลเมื่อใบรับรองพร้อม:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.คำเตือน (Warning) เมื่อใบรับรองหมดอายุ, ยังไม่ถึงวันเริ่มใช้งาน, หรือไม่ได้ออกเพื่อการลงลายเซ็นเอกสาร:
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) เมื่อไม่มีการกำหนดค่าใบรับรอง:
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 ของวิดเจ็ตถูก ปิดโดยค่าเริ่มต้น. เปิดใช้งานพวกมันข้างการลงทะเบียนปลั๊กอิน:
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() จะโยนข้อผิดพลาด:
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). มันเป็นไฟล์เดียวที่รวมทุกอย่างและไม่มีการพึ่งพา:
<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.
ตัวเลือก
| ตัวเลือก | ประเภท | ค่าเริ่มต้น | หมายเหตุ |
|---|---|---|---|
basePath | string | '/doconut' | ตำแหน่งที่ให้บริการ endpoints ?sign= และภาพตัวอย่าง |
resPath | string | '/doconut-res' | สงวนไว้; วิดเจ็ตรวม CSS ของตนเอง |
maxUploadMb | number | 25 | ตรวจสอบเฉพาะด้านไคลเอนต์, ดังนั้นไฟล์ที่ใหญ่เกินจะล้มเหลวอย่างรวดเร็ว. ขีดจำกัดของเซิร์ฟเวอร์คือ MaxUploadMb ใน AddSignerWidget |
maxSignatureKb | number | 512 | ขีดจำกัดด้านไคลเอนต์สำหรับโหมด Image. ให้เท่ากับ MaxSignatureImageKb ของเซิร์ฟเวอร์ |
previewWidth | number | 560 | ความกว้างพิกเซลของภาพตัวอย่างหน้า |
licenseUrl | string | null | null | แปลงข้อความลายน้ำ demo ให้เป็นลิงก์ไปยัง URL นี้ |
signatureMode | string | 'certified' | ประเภทลายเซ็นเริ่มต้น: 'certified' หรือ 'visual'. ค่าที่อื่นจะกลายเป็น 'certified' |
showSignatureModeToggle | boolean | true | แสดงตัวเลือก ลายเซ็นดิจิทัล / เฉพาะภาพ. หากมี false, วิดเจ็ตจะลงนามด้วย signatureMode |
wordOutput | string | 'pdf' | ผลลัพธ์เริ่มต้นสำหรับแหล่ง .docx: 'pdf' หรือ 'docx'. ค่าที่อื่นจะกลายเป็น 'pdf' |
showOutputFormatToggle | boolean | true | แสดงตัวเลือก PDF / Word สำหรับแหล่ง .docx เท่านั้น. หากมี false, วิดเจ็ตจะใช้ wordOutput |
labels | object | {} | แทนที่ส่วนใดส่วนหนึ่งของสตริงภาษาอังกฤษ |
การซ่อนสวิตช์ไม่ได้ปิดการทำงานของฟีเจอร์; มันกำหนดค่าคงที่. การตั้งค่าทั่วไปสองแบบ:
// แสดงสวิตช์ทั้งสอง, ลายเซ็นดิจิทัลเป็นค่าเริ่มต้น: ผู้ลงนามแบบบริการตนเองเต็มรูปแบบ.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// แสดงผลอย่างเดียว, ไม่มีสวิตช์: ตราประทับง่าย ๆ ที่ไม่มีลายเซ็นดิจิทัล.
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 ว่างเปล่า, และทำให้อินสแตนซ์ค้างอยู่ |
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'.
| คีย์ | ค่าเริ่มต้นภาษาอังกฤษ |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
คีย์เพิ่มเติมครอบคลุมขั้นตอนการวางตำแหน่ง, หน้าจอข้อผิดพลาด, แบบฟอร์มที่เชื่อมโยงของประกาศสาธิต (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) และประกาศ aria-live.
เมื่อ open หรือ run ตอบ 404 โดยไม่มีข้อผิดพลาด JSON, วิดเจ็ตจะแสดง signingNotEnabled. ข้อผิดพลาด JSON จากเซิร์ฟเวอร์จะมีลำดับความสำคัญสูงสุด, ดังนั้นข้อความเช่นการอัปโหลดที่หมดอายุจะยังคงแสดงอยู่.
ธีม
วิดเจ็ตเพิ่มคลาส dsw ไปยังองค์ประกอบ mount ของมันและอ่านสี, รัศมีและฟอนต์จากคุณสมบัติ 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:
{
"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.kind | Drawn, Typed หรือ Image, ไม่สนใจตัวพิมพ์ใหญ่/เล็ก; อย่างอื่นทั้งหมดจะกลายเป็น Drawn. คำแนะนำเท่านั้น: payload จะเป็น PNG เสมอ |
signature.payload | PNG base64 อย่างเดียว, ไม่มีคำนำหน้า data:. ต้องเป็น PNG จริงและไม่ใหญ่กว่า MaxSignatureImageKb หลังจากถอดรหัส |
placement.page | เริ่มจาก 1 |
placement.x / y / w / h | 0..1 ปกติจากมุมบนซ้าย, พร้อมกับ x + w ≤ 1 และ y + h ≤ 1 |
meta.signerName / reason / location | ไม่บังคับ. แต่ละค่า จะถูกตัดขอบ, ค่าว่างจะถูกละทิ้ง, และแต่ละค่าจะถูกตัดที่ 256 ตัวอักษร |
wordOutput | pdf (ค่าเริ่มต้น) หรือ docx; ไม่สนใจสำหรับแหล่ง PDF. อย่างอื่นทั้งหมดจะกลายเป็น pdf |
mode | certified (ค่าเริ่มต้น) หรือ visual. อย่างอื่นทั้งหมดจะกลายเป็น certified |
downloadName ตามผลลัพธ์: <source>-signed.pdf หรือ <source>-signed.docx, และ download ส่ง Content-Type ที่ตรงกัน
แหล่งที่อัปโหลดและผลลัพธ์ที่เซ็นจะถูกเก็บไว้แต่ละรายการเป็นเวลา 30 นาที. หลังจากนั้น, run และ download จะตอบกลับด้วย 404 และไฟล์ต้องถูกเปิดใหม่อีกครั้ง. โทเคนทั้งหมดเป็น GUIDs.
| เส้นทาง | สถานะ | เมื่อ | เนื้อหา |
|---|---|---|---|
| ใดก็ได้ | 404 | วิดเจ็ตไม่ได้เปิดใช้งาน | เพียงสถานะ |
| ใดก็ได้ | 405 | คำกริยาไม่ถูกต้อง (open และ run ต้องการ POST, download ต้องการ GET) | เพียงสถานะ |
open | 400 | ไม่ใช่การอัปโหลด multipart | Expected a multipart file upload. |
open | 400 | ไม่มีไฟล์ หรือไฟล์ว่างเปล่า | No file uploaded. |
open | 400 | อย่างอื่นที่ไม่ใช่ .pdf หรือ .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | การอัปโหลดเกิน MaxUploadMb | File is too large. |
run | 400 | เนื้อหาไม่เป็น JSON ที่ถูกต้อง หรือว่างเปล่า | Malformed request. / Empty request. |
run | 400 | โทเคนหายไปหรือไม่ใช่ GUID | Invalid token. |
run | 404 | การอัปโหลดหมดอายุหรือไม่เคยเปิด | Upload expired — please re-open the file. |
run | 400 | ไม่มีลายเซ็น หรือไม่มีการวางตำแหน่ง | No signature supplied. / No placement supplied. |
run | 400 | payload ไม่ใช่ base64, ว่างเปล่า, ใหญ่เกินไป, หรือไม่ใช่ PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | การวางตำแหน่งอยู่นอกหน้า | The signature or its placement is invalid. |
run | 400 | โหมดรับรอง, มีใบอนุญาตแบบชำระเงินและไม่มีใบรับรอง | No signing certificate configured. |
run | 400 | โหมดรับรองที่มีใบรับรองอยู่นอกช่วงเวลาที่ใช้ได้ | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | การประมวลผลล้มเหลว | ข้อความที่ทำให้ปลอดภัย |
download | 400 | โทเคนหายไปหรือไม่ใช่ GUID | เพียงสถานะ |
download | 404 | โทเคนที่ไม่รู้จักหรือหมดอายุ | เพียงสถานะ |
การเดินทางรอบสมบูรณ์ด้วย fetch:
// 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 ของคุณ.
ในการผลิต
-
ติดตั้งปลั๊กอิน ข้างแพ็คเกจหลัก, ที่เวอร์ชันเดียวกัน:
dotnet add package Doconut.NET6.Signer. -
เพิ่มไฟล์ใบอนุญาต. วาง
Doconut.Viewer.Signer.licในโฟลเดอร์เดียวกับDoconut.Viewer.lic. -
รับใบรับรองของคุณเป็น PFX พร้อมคีย์ส่วนตัวและสายการออกใบรับรอง, จากหน่วยงานออกใบรับรองหรือ PKI ขององค์กรของคุณ. เพื่อทดลองก่อน, ใช้ใบอนุญาตเดโม (ใบรับรองเดโมที่มีอยู่ในตัว, มีลายน้ำ) หรือ PFX ที่เซ็นด้วยตนเอง.
-
อ่านใบรับรองจากการกำหนดค่า, เพื่อให้การเปลี่ยนแปลงไม่ต้องแก้ไขโค้ด:
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }csharpvar 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) หรือคลังข้อมูลในสภาพแวดล้อมการผลิต. -
ตรวจสอบบันทึกการเริ่มต้น ควรอ่านว่า
using certificate '{subject}' (valid until …). Signatures are digitally sealed.คำเตือนหมายความว่าใบรับรองหมดอายุ, ยังไม่เป็นที่ใช้ได้, หรือไม่ได้ออกสำหรับการลงนามเอกสาร.
เชื่อถือในโปรแกรมอ่าน PDF. โปรแกรมอ่านจะแสดงลายเซ็นว่าเป็นที่ถูกต้องเมื่อมันเชื่อถือรากของใบรับรอง. ด้วย PKI ขององค์กรของคุณ, สิ่งนี้จะใช้ได้กับทุกเครื่องที่เชื่อถือรากของคุณ, ซึ่งโดยทั่วไปคือทุกเครื่องภายในองค์กร. ใบรับรองที่ Adobe เชื่อถือบนเครื่องใดก็ได้ (Adobe Approved Trust List) ตามที่เราทราบ, ถูกออกโดยใช้คีย์ส่วนตัวบนโทเค็นฮาร์ดแวร์หรือ HSM, ซึ่งปลั๊กอินนี้ไม่สามารถใช้ได้: มันเซ็นจาก PFX เท่านั้น. ยืนยันกับผู้ให้บริการใบรับรองของคุณก่อนพึ่งพาการเชื่อมโยงแบบนั้น.
ฟาร์มเว็บ
วิดเจ็ตเก็บการอัปโหลดแต่ละรายการและผลลัพธ์ไว้ในหน่วยความจำบนโหนดที่ให้บริการ open. ภายหลังโหลดบาลานเซอร์ที่ไม่มีเซสชันแบบติดหนึบ, คำขอ run, download หรือการแสดงตัวอย่างในภายหลังอาจไปยังโหนดอื่นและไม่พบการอัปโหลด. ลงทะเบียนที่เก็บวิดเจ็ตที่แชร์และเข้ารหัสหนึ่งครั้ง, หลังจาก AddDoconut():
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
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
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
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes ไม่ว่างเปล่า
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes เป็น PNG สำหรับทุกประเภท. ลายเซ็นที่วาดหรือพิมพ์จะเป็นแบบโปร่งใส; ภาพที่อัปโหลดจะคงความโปร่งใสที่มีอยู่, ดังนั้น JPG ที่ทึบจะยังคงทึบ. Kind เป็นเพียงคำแนะนำ.
SignaturePlacement
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
public enum SignatureMode { Certified, Visual } // Certified เป็นค่าเริ่มต้น
public enum WordOutput { Pdf, Docx } // Pdf เป็นค่าเริ่มต้น; ถูกละเว้นสำหรับแหล่ง PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);เอกสารที่ลงนามเป็นสตรีมที่สามารถเลื่อนตำแหน่งได้, และนามสกุลของมันพร้อมจุด (".pdf" หรือ ".docx").
SigningCertificate
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
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 |
หน้านี้เป็นประโยชน์หรือไม่?