ملحق التوقيع
وقع مستندات PDF و Word بتوقيع مرئي وختم رقمي
يقوم ملحق Signer بوضع توقيع مرئي على المستند، وبشكل افتراضي، يختمه بتوقيع رقمي يمكن لقارئ PDF التحقق منه. يوقع ملفات PDF و Word (.docx). يكون التوقيع المرئي دائمًا صورة PNG: مرسومة، مكتوبة، أو تم تحميلها من قبل الموقع.
| السطح | متى تستخدمه |
|---|---|
DocumentSigner (C#) | توقع على الخادم، دون تدخل المتصفح |
Drop-in widget (doconutSigner.js) | تريد شاشة جاهزة للتحميل، التوقيع والتنزيل في صفحتك |
HTTP endpoints (?sign=open|run|download) | تبني واجهة توقيع خاصة بك مقابل عقد خادم موثق |
يتم وضع كل توقيع مرة واحدة، على صفحة واحدة. يمكن أن يصاحب التوقيع اسم الموقع والسبب والموقع الجغرافي.
تثبيت الحزمة
قم بتثبيت أحدث نسخة مستقرة من ملحق Signer:
dotnet add package Doconut.NET8.Signerلتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:
dotnet add package Doconut.NET8.Signer --version 26.10.0احتفظ بحزمة Signer بنفس الإصدار كما هو في Doconut.NET8. معرف الحزمة هو Doconut.NET8.Signer؛ يظهر .<version> فقط في اسم الملف .nupkg الذي تم تنزيله.
ملف ترخيص الملحق، Doconut.Viewer.Signer.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يُقرأ مع ترخيص العارض.
المنصات. يعمل الملحق أينما يعمل Doconut.NET8: 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 الخاصة بها هي خيار منفصل، 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.يحدث الاستثناء عند عدم وجود ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Signer، أو ترخيص مدفوع يُستخدم خارج نافذة إصداره. تُقبل تراخيص Demo/NFR المؤقتة. انظر License Setup لمعرفة كيفية تحميل التراخيص.
الترخيص والعلامة المائية
| حالة الترخيص | بدء التشغيل | توقيع معتمد | التوقيع البصري |
|---|---|---|---|
ترخيص مدفوع يمنح Signer، شهادة مكوَّنة | يبدأ | مختوم بشهادتك، نظيف (watermarked: false) | نظيف |
ترخيص مدفوع يمنح Signer، بدون شهادة | يبدأ | مرفوض: No signing certificate configured. | نظيف |
| ترخيص مدفوع، شهادة منتهية أو غير صالحة بعد | يبدأ (مع تمكين الواجهة المصغرة، يُسجل تحذير) | مرفوض: The signing certificate expired on yyyy-MM-dd. | نظيف |
| ترخيص Demo/NFR مؤقت، نشط أو منتهي | يبدأ | مختوم بشهادة العرض المدمجة، مع علامة مائية (watermarked: true) | مع علامة مائية |
بدون ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Signer، أو ترخيص مدفوع خارج نافذة إصداره | AddDoconut() يطرح استثناء | — | — |
القاعدة هي نفسها لواجهة C# والواجهة المصغرة: يكون الناتج مغطى بعلامة مائية عندما لا يكون الترخيص ترخيص عارض مدفوع أو يكون مؤقتًا. تحت ترخيص مؤقت، يوقع الملحق دائمًا بشهادة العرض المدمجة، ولا تُستخدم أي شهادة تقوم بتكوينها.
شهادة العرض تنتج ختمًا حقيقيًا، لكن قارئات PDF لا تثق بها. يمكن بناء واختبار تكامل من البداية إلى النهاية باستخدام ترخيص تجريبي؛ للحصول على ناتج نظيف وموثوق تحتاج إلى كل من ترخيص مدفوع وشهادتك الخاصة شهادة التوقيع.
الاستخدام من C#
DocumentSigner مسجل بواسطة AddDoconut() ويتم حله عبر حقن التبعيات. مُنشئه داخلي، لذا لا تقم أبداً بـ 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 (التوقيع المرئي + الختم الرقمي)؛ 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 تحت ترخيص تجريبي، أو في الوضع البصري.
SignResult يحتفظ بالمستند الموقّع كتدفق قابل للتمرير، بالإضافة إلى Extension الخاص به (".pdf" أو ".docx") حتى تتمكن من تسمية الملف. أنت مالك التدفق: احذف (dispose)ه عندما تنتهي.
التوقيع البصري يطبع الصورة فقط ولا يحتاج إلى شهادة:
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; // ".docx"SignAsync يرمي استثناءً بدلاً من الإرجاع عندما لا يمكن أن ينجح الاستدعاء:
| الاستثناء | الرسالة | متى |
|---|---|---|
InvalidOperationException | No signing certificate configured. | وضع معتمد، ترخيص مدفوع، ولم يتم تمرير شهادة |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | وضع معتمد مع شهادة خارج نافذة صلاحيتها |
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 (الافتراضي) | التوقيع الظاهر بالإضافة إلى ختم رقمي | مطلوب تحت ترخيص مدفوع | نعم |
SignatureMode.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 من حملها. - كلمة المرور الصحيحة.
- داخل نافذة الصلاحية الخاصة به. شهادة منتهية الصلاحية أو غير صالحة بعد لا توقف التطبيق: تُسجل كتحذير عند بدء التشغيل، وتُرفض التوقيعات الموثقة حتى يتم استبدالها. التوقيعات البصرية لا تتأثر.
- مُصدرة لتوقيع المستندات: استخدام مفتاح مع توقيع رقمي أو عدم إنكار، واستخدام مفتاح ممتد، إذا كان موجودًا، يسمح بتوقيع المستندات، حماية البريد الإلكتروني أو مصادقة العميل. شهادة صُدرت لغرض آخر، مثل شهادة خادم TLS، لا تزال تُوقع، لكنها تُسجل كتحذير وتُظهر قرّاء PDF العلامة على التوقيع.
- الرموز المادية، البطاقات الذكية، HSMs ومتجر شهادات Windows غير مدعومة. صدّر الشهادة، مع المفتاح الخاص والسلسلة، إلى ملف PFX.
إنشاء ملف PFX من شهادة ومفتاحها الخاص باستخدام OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# كلمة مرور التصدير التي يُطلب منك إدخالها هي SigningCertificate.Password.تصدير واحدة من متجر شهادات Windows: افتح certmgr.msc وابحث عن الشهادة (أيقونتها تُظهر مفتاحًا عندما يكون المفتاح الخاص موجودًا). انقر بزر الماوس الأيمن عليها، اختر كل المهام → تصدير…، حدد نعم، تصدير المفتاح الخاص، اختر تبادل المعلومات الشخصية – PKCS #12 (.PFX)، واضبط كلمة مرور.
فحوصات بدء التشغيل
عند تمكين الودجت، تُفحص الشهادة في SignerWidgetOptions.SigningCertificate مرة واحدة، داخل AddDoconut()، بحيث يفشل ملف PFX غير المُكوَّن بشكل صحيح عند بدء التشغيل بدلاً من التوقيع الأول. ثلاث مشاكل تُطلق 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.تحذير عندما تكون منتهية الصلاحية، غير صالحة بعد، أو غير صادرة لتوقيع المستندات:
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.ومعلومات عندما لا تكون هناك شهادة مُكوَّنة:
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.السطر الأخير هو نفسه تحت كل ترخيص. تحت ترخيص مدفوع لا تُستخدم شهادة العرض التجريبية أبدًا: بدون شهادة، تعمل فقط التوقيعات البصرية.
الواجهة C# لا تُفحص عند بدء التشغيل. الشهادة التي تمرّرها إلى SignAsync تُقرأ عندما تقوم بالتوقيع، لذا مسار أو كلمة مرور خاطئة تُفشل تلك الاستدعاء.
عنصر واجهة المستخدم القابل للإدماج
تمكين نقاط النهاية
نقاط النهاية ?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 لتوقيع العرض التجريبي (مُعلَّم بالماء)
});
});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 أو عنصرًا، يرفع استثناءً إذا لم يُعثر على التركيب، ويعيد مقبضًا.
يقوم المُوقّع بتحميل ملف PDF أو ملف .docx، يُنشئ توقيعًا (رسم على لوحة، كتابة اسم بخط التوقيع، أو صورة من PNG أو JPG أو GIF)، يسحبها ويُعيد تحجيمها على الصفحة، ثم يوقع ويُنزّل النتيجة. يرسل الودجت دائمًا التوقيع كملف PNG؛ تُحوَّل الصورة التي تم تحميلها في المتصفح إلى PNG يتناسب مع 520×160.
الخيارات
| الخيار | النوع | الافتراضي | ملاحظات |
|---|---|---|---|
basePath | string | '/doconut' | أين تُخدم نقاط النهاية ?sign= وصور المعاينة |
resPath | string | '/doconut-res' | محجوز؛ الحزمة تضم CSS الخاص بها |
maxUploadMb | number | 25 | تحقق من جانب العميل فقط، لذا يفشل الملف الضخم بسرعة. الحد الأقصى على الخادم هو MaxUploadMb في AddSignerWidget |
maxSignatureKb | number | 512 | الحد الأقصى من جانب العميل لوضع الصورة. احفظه مساويًا للحد على الخادم MaxSignatureImageKb |
previewWidth | number | 560 | عرض البكسل لمعاينة الصفحة |
licenseUrl | string | null | null | يحول إشعار العلامة المائية التجريبية إلى رابط لهذا العنوان |
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 | مرة واحدة عند التركيب (ليس مرة أخرى على reset()) | — |
onSourceLoaded | يُفتح الملف وتُظهر معاينته | { file: { token, name, pages, ext } } |
onSigned | ينجح التوقيع | { downloadToken, downloadName, watermarked } |
onDownload | عند كل نقرة تنزيل | { downloadName, downloadToken } |
onError | فشل خطوة فتح أو توقيع أو تنزيل، أو كان ملف وضع الصورة كبيرًا جدًا | { message } |
يتم التقاط الاستدعاء الذي يرفع استثناء وتسجيله؛ لا يُعطل تدفق الودجت أبدًا.
التعامل الإجباري
| الطريقة | السلوك |
|---|---|
reset() | يعيد إلى شاشة الإسقاط ويمسح التدفق الحالي. لا يُطلق onReady مرة أخرى. لا يفعل شيئًا بعد destroy() |
loadFile(file) | يبدأ التدفق بـ File. لا يفعل شيئًا إلا إذا كان الودجت في شاشة الإسقاط؛ استدعِ reset() أولاً إذا لزم الأمر |
destroy() | يزيل المستمعين، يفرغ التركيب، ويجمد النسخة |
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 إلى عنصر التركيب الخاص به ويقرأ ألوانه ونصف قطره وخطوطه من خصائص 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; /* وضع الكتابة */
}القيم الافتراضية: --dsw-accent: #2b6cb0، --dsw-bg: #ffffff، --dsw-fg: #1a202c، --dsw-muted: #718096، --dsw-border: #cbd5e0، --dsw-radius: 8px، خط واجهة نظام، وخط توقيع مائل.
بناء الواجهة الأمامية الخاصة بك
الودجت هو عميل لهذا العقد HTTP. جميع المسارات الثلاثة تقع تحت المسار حيث يتم تركيب UseDoconut() (عادةً /doconut)، وتستجيب 404 حتى يتم استدعاء AddSignerWidget(). الأخطاء تحمل جسم JSON، { "error": "..." }، باستثناء حيث تقول الجدول "الحالة فقط". قيمة غير معروفة لـ ?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:
{
"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. مجرد تلميح: الحمولة دائمًا 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.
| المسار | الحالة | متى | المحتوى |
|---|---|---|---|
| any | 404 | الودجت غير مفعّل | الحالة فقط |
| any | 405 | الفعل غير صحيح (open و run يحتاجان POST، download يحتاج GET) | الحالة فقط |
open | 400 | ليس رفعًا متعدد الأجزاء | 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 | الحمولة ليست 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: prefix,
// على سبيل المثال 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. قدّم واجهة المستخدم الخاصة بك وبرنامج الواجهة من نفس الأصل مثل Doconut، أو استخدم reverse-proxy لكلا مساري /doconut (مسار الوسيط ومسار الموارد) تحت أصل واجهة المستخدم الخاصة بك.
في الإنتاج
-
ثبت الإضافة بجانب حزمة النواة، بنفس الإصدار:
dotnet add package Doconut.NET8.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) تُصدر، حسب علمنا، باستخدام المفتاح الخاص على رمز مادي أو HSM، ولا يمكن لهذه الإضافة استخدامها: فهي توقّع فقط من PFX. تأكد من مزود شهادتك قبل الاعتماد على هذا النوع من الثقة.
مزارع الويب
تحتفظ الواجهة (widget) بكل تحميل ونتيجته في الذاكرة على العقدة التي قدمت open. خلف موازن تحميل دون جلسات ثابتة، قد يصل طلب لاحق run، download أو طلب معاينة إلى عقدة أخرى ولا يجد التحميل. سجّل مخزن الواجهة المشترك المشفر مرة واحدة، بعد AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // مجلد يمكن لكل node قراءته وكتابته
store.FarmKey = farmKey; // على الأقل 32 بايت، متطابق على كل node
// store.Ttl = TimeSpan.FromMinutes(30); // المدة التي يُحتفظ فيها بالرفع (الافتراضي)
});- يحتاج خادم واحد إلى لا شيء: بدون هذا الاستدعاء يُستخدم المخزن في الذاكرة.
- يتم تشفير التحميلات والنتائج أثناء التخزين على المشاركة (AES-256، تشفير ثم MAC)، وكل ملف مرتبط برمزّه، لذا لا يمكن لأي رمز قراءة ملف رمز آخر.
- يجب أن يكون
FarmKeyبطول لا يقل عن 32 بايت وأن يكون نفسه على كل عقدة. حمّله من مخزن أسرار؛ لا تقم بتضمينه صراحةً. يُطلق التسجيل خطأ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);
}يتم الحصول عليه عبر حقن الاعتماديات؛ المُنشئ داخلي. sourceExtension هو ".pdf" أو ".docx". تحت رخصة مدفوعة يُستخدم cert وتكون النتيجة نظيفة؛ تحت رخصة مؤقتة يُستخدم شهادة العرض التجريبية المدمجة، ويتم تجاهل cert، وتكون النتيجة مائية.
طلب التوقيع
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
}توقيع مرئي واحد يُوضع مرة واحدة، بالإضافة إلى بيانات تعريف الموقّع الاختيارية.
التوقيع المرئي ونوع التوقيع
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes غير فارغ
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes هو PNG لكل نوع. التوقيع المرسوم أو المكتوب يكون شفافًا؛ الصورة التي تم تحميلها تحتفظ بالشفافية التي كانت عليها، لذا يبقى JPG غير شفاف. Kind هو مجرد تلميح.
موضع التوقيع
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 مُعَدلّة من الزاوية العليا اليسرى.
وضع التوقيع وإخراج Word
public enum SignatureMode { Certified, Visual } // Certified هو الافتراضي
public enum WordOutput { Pdf, Docx } // Pdf هو الافتراضي؛ يتم تجاهله لمصادر PDFنتيجة التوقيع
public sealed record SignResult(Stream Stream, string Extension);المستند الموقّع كدفق قابل للتمرير، وامتداده مع النقطة (".pdf" أو ".docx").
شهادة التوقيع
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.
خيارات ودجت الموقّع
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 تعني شهادة العرض التجريبية تحت رخصة مؤقتة، وتكون التواقيع البصرية فقط تحت رخصة مدفوعة.
استكشاف الأخطاء وإصلاحها
| العَرَض | السبب | الحل |
|---|---|---|
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. | واجهة مخصصة أرسلت عنوان 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 يقولون إن هوية الموقّع غير معروفة | القارئ لا يثق بجذر الشهادة (شهادة العرض التجريبية لا تُوثق أبدًا) | استخدم شهادة من جذر يثق به قراءك |
| الودجت يفشل عندما تكون الواجهة على أصل مختلف | النقاط النهاية لا تدعم CORS | قدّم الواجهة من نفس الأصل، أو استخدم reverse-proxy لمسارات Doconut |
| السمة لا تُطبق | المحدد يستهدف عنصرًا داخل التركيب | استهدف التركيب نفسه: #host.dsw أو #host |
هل كانت هذه الصفحة مفيدة؟