ملحق Signer

وقع مستندات PDF و Word بتوقيع مرئي وختم رقمي

يقوم ملحق Signer بوضع توقيع مرئي على المستند، وبشكل افتراضي، يختتمه بتوقيع رقمي يمكن لقارئ PDF التحقق منه. يقوم بتوقيع ملفات PDF و Word (.docx). يكون التوقيع المرئي دائمًا صورة PNG: مرسومة، مكتوبة، أو تم تحميلها من قبل المُوقّع.

الواجهةمتى تستخدمها
DocumentSigner (C#)توقع على الخادم، دون متصفح
Drop-in widget (doconutSigner.js)تريد شاشة جاهزة للتحميل، التوقيع والتنزيل في صفحتك
HTTP endpoints (?sign=open|run|download)تبني واجهة توقيع خاصة بك مقابل عقد خادم موثّق

كل توقيع يُوضع مرة واحدة، على صفحة واحدة. يمكن أن يسافر اسم المُوقّع والسبب والموقع معه.

تثبيت الحزمة

ثبت أحدث نسخة مستقرة من ملحق Signer:

bash
dotnet add package Doconut.NET6.Signer

لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:

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

احتفظ بحزمة Signer بنفس الإصدار كما هو في Doconut.NET6. معرف الحزمة هو Doconut.NET6.Signer؛ يظهر .<version> فقط في اسم الملف .nupkg الذي تم تنزيله.

ملف ترخيص الملحق، Doconut.Viewer.Signer.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يتم قراءته مع ترخيص العارض.

المنصات. يعمل الملحق أينما يعمل Doconut.NET6: Windows، ولينكس المبني على glibc على x64 (ليس Alpine أو توزيعات musl الأخرى). على لينكس، ثبّت مكتبة تكوين الخطوط قبل فتح أول مستند:

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 الخاصة به خيار منفصل، AddSignerWidget() (انظر الودجت المدمج).

يحتاج الملحق إلى ترخيص يمنح القدرة على Signer. بدون ذلك، يطرح AddDoconut() عند بدء التشغيل، قبل أن يخدم التطبيق أي طلب:

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

يحدث ذلك عند عدم وجود ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Signer، أو ترخيص مدفوع يُستخدم خارج نافذة إصداره. تُقبل تراخيص Demo/NFR المؤقتة. انظر إعداد الترخيص لمعرفة كيفية تحميل التراخيص.

الترخيص والعلامة المائية

حالة الترخيصبدء التشغيلالتوقيع المصدقالتوقيع المرئي
ترخيص مدفوع يمنح Signer، شهادة مكوّنةيبدأمختوم بشهادتك، نظيف (watermarked: false)نظيف
ترخيص مدفوع يمنح Signer، بدون شهادةيبدأمرفوض: No signing certificate configured.نظيف
ترخيص مدفوع، الشهادة منتهية أو غير صالحة بعديبدأ (مع تمكين الودجت، يُسجل تحذير)مرفوض: The signing certificate expired on yyyy-MM-dd.نظيف
ترخيص Demo/NFR مؤقت، نشط أو منتهييبدأمختوم بشهادة العرض المدمجة، مع علامة مائية (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>().

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 (توقيع مرئي + ختم رقمي)؛ 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") حتى يمكنك تسمية الملف. أنت مالك التيار: قم بتحريره عندما تنتهي.

التوقيع البصري يطبع الصورة فقط ولا يحتاج إلى شهادة:

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

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

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

مصدر Word يتم توقيعه إلى PDF ما لم تطلب إخراج Word. سمِّ النتيجة من result.Extension:

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

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

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

SignAsync يطرح استثناءً بدلاً من الإرجاع عندما لا يمكن أن ينجح الاستدعاء:

الاستثناءالرسالةمتى
InvalidOperationExceptionNo signing certificate configured.وضع معتمد، رخصة مدفوعة، ولا توجد شهادة مُمرَّرة
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.وضع معتمد مع شهادة خارج نافذة صلاحيتها
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 من حملها.
  • كلمة المرور الصحيحة.
  • داخل فترة الصلاحية الخاصة به. شهادة منتهية الصلاحية أو غير صالحة بعد لا توقف التطبيق: تُسجل كتحذير عند بدء التشغيل، وتُرفض التوقيعات الموثقة حتى يتم استبدالها. التوقيعات البصرية لا تتأثر.
  • مُصدرة لتوقيع المستندات: استخدام مفتاح مع توقيع رقمي أو عدم إنكار، واستخدام مفتاح ممتد، إذا كان موجودًا، يسمح بتوقيع المستندات، حماية البريد الإلكتروني أو مصادقة العميل. شهادة صُدرت لشيء آخر، مثل شهادة خادم TLS، لا تزال تُوقّع، لكن تُسجل كتحذير وتُظهر قارئات PDF العلامة على التوقيع.
  • الرموز المادية، البطاقات الذكية، وحدات HSM ومتجر شهادات 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 غير المُكوَّن بشكل صحيح عند بدء التشغيل بدلاً من التوقيع الأول. ثلاث مشكلات تُطلق 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.

تحذير عندما تكون منتهية الصلاحية، غير صالحة بعد، أو غير صادرة لتوقيع المستندات:

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.

ومعلومات عندما لا تكون هناك شهادة مُكوَّنة:

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.

السطر الأخير هو نفسه تحت جميع التراخيص. تحت ترخيص مدفوع لا تُستخدم شهادة العرض التجريبية أبدًا: بدون شهادة، تعمل فقط التوقيعات البصرية.

الواجهة C# لا تُفحص عند بدء التشغيل. الشهادة التي تمرّرها إلى SignAsync تُقرأ عند التوقيع، لذا فإن مسارًا خاطئًا أو كلمة مرور خاطئة تُفشل تلك الاستدعاء.

أداة الإدراج الفوري

تمكين نقاط النهاية

نقاط النهاية ?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 للتوقيع التجريبي (المُعَلَّم بالماء)
    });
});

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 أو عنصرًا، يطرح استثناءً إذا لم يُعثر على التركيب، ويعيد مقبضًا.

يقوم المُوقِّع بتحميل ملف PDF أو ملف .docx، يُنشئ توقيعًا (Draw على لوحة رسم، Type اسمًا بخط توقيع، أو Image من PNG أو JPG أو GIF)، يسحبها ويُعيد تحجيمها على الصفحة، ثم يوقع ويُنزّل النتيجة. تُرسل الأداة دائمًا التوقيع كملف PNG؛ تُحوَّل الصورة المُحمَّلة في المتصفح إلى PNG يتناسب مع 520×160.

الخيارات

الخيارالنوعالافتراضيملاحظات
basePathstring'/doconut'أين تُقدَّم نقاط النهاية ?sign= وصور المعاينة
resPathstring'/doconut-res'محجوز؛ الأداة تُضمّن CSS الخاص بها
maxUploadMbnumber25تحقق من جانب العميل فقط، لذا يُفشل الملف الضخم بسرعة. الحد الأقصى على الخادم هو MaxUploadMb في AddSignerWidget
maxSignatureKbnumber512الحد الأقصى من جانب العميل لوضع الصورة. احرص على أن يكون مساويًا لـ MaxSignatureImageKb على الخادم
previewWidthnumber560عرض البكسل لمعاينة الصفحة
licenseUrlstring | nullnullيحوِّل إشعار العلامة المائية التجريبية إلى رابط لهذا العنوان
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مرة واحدة، عند التركيب (ليس مرة أخرى على reset())—
onSourceLoadedيتم فتح الملف وعرض معاينته{ file: { token, name, pages, ext } }
onSignedنجاح التوقيع{ downloadToken, downloadName, watermarked }
onDownloadعند كل نقرة تنزيل{ downloadName, downloadToken }
onErrorفشل خطوة الفتح أو التوقيع أو التنزيل، أو أن ملف وضع الصورة كبير جدًا{ message }

يتم التقاط أي رد نداء يطرح استثناء وتسجيله؛ لا يُعطِّل تدفق الأداة أبدًا.

المعالج الإلزامي

الطريقةالسلوك
reset()يعيد إلى شاشة الإسقاط ويمسح التدفق الحالي. لا يُطلق onReady مرة أخرى. لا يفعل شيئًا بعد destroy()
loadFile(file)يبدأ التدفق بـ File. لا يفعل شيئًا ما لم يكن الودجت في شاشة الإسقاط؛ استدعِ reset() أولاً إذا لزم الأمر
destroy()يزيل المستمعين، يفرغ العنصر المركب، ويجمد النسخة
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 إلى عنصر التركيب الخاص به ويقرأ ألوانه ونصف قطره وخطوطه من خصائص 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، خط واجهة نظام، وخط توقيع مائل.

أنشئ الواجهة الأمامية الخاصة بك

الودجت هو عميل لهذا العقد HTTP. جميع المسارات الثلاثة تقع تحت المسار حيث يتم تركيب UseDoconut() (عادةً /doconut)، وتستجيب 404 حتى يتم استدعاء AddSignerWidget(). الأخطاء تحمل جسم JSON، { "error": "..." }، باستثناء حيث تقول الجدول "status only". قيمة غير معروفة لـ ?sign= تجيب بـ 400.

المسارالغرضاستجابة النجاح
POST ?sign=open (متعدد الأجزاء، ملف واحد)تحميل PDF أو .docx وفتحها للمعاينة200 — { token, name, pages, ext }
POST ?sign=run (جسم JSON)توقيع الملف المرفوع200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>بث الملف الموقع200 — الملف، Content-Disposition: attachment، Cache-Control: no-store

ext في استجابة open يتضمن النقطة الأولى (".docx"). معاينة الصفحة تستخدم مسار صورة المشاهد القياسي، {basePath}?token={token}&page={n}&thumb=1&width={px}؛ الصفحة المعروضة تصبح placement.page.

جسم run:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
الحقلملاحظات
tokenالرمز من open
signature.kindDrawn، Typed أو Image، غير حسّاس لحالة الأحرف؛ أي شيء آخر يصبح Drawn. مجرد تلميح: الحمولة دائمًا 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.

المسارالحالةمتىالمحتوى
any404الودجت غير مفعّلفقط الحالة
any405فعل غير صحيح (open وrun يحتاجان POST، download يحتاج GET)فقط الحالة
open400ليس تحميلًا متعدد الأجزاءExpected 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.
run400الحمولة ليست 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: التوقيع كصورة PNG base64 صافية، بدون بادئة data:
// على سبيل المثال canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/doconut';

  // 1. open: رفع الملف
  const form = new FormData();
  form.append('file', file, file.name);
  const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();

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

  // 3. download: جلب الملف الموقع
  const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = signed.downloadName;
  link.click();
  URL.revokeObjectURL(link.href);
}

النقاط النهاية هي same-origin: هذا الإصدار لا يدعم CORS. قدّم واجهة المستخدم الخاصة بك وسكربت الودجت من نفس الأصل مثل Doconut، أو استخدم reverse-proxy لكلا مساري /doconut (مسار الوسيط ومسار الموارد) تحت أصل واجهة المستخدم الخاصة بك.

في الإنتاج

  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) تُصدر، حسب علمنا، بالمفتاح الخاص على رمز مادي أو 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، تشفير ثم MAC)، ويُربط كل ملف برمز التوكن الخاص به، لذا لا يمكن لتوكن واحد قراءة ملف آخر.
  • يجب أن يكون FarmKey بطول لا يقل عن 32 بايت وأن يكون نفسه على كل عقدة. حمّله من مخزن أسرار؛ لا تُبرمجه صلبًا أبدًا. يُطلق التسجيل استثناءً من نوع 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);
}

يتم حله عبر حقن الاعتمادية؛ المُنشئ داخلي. 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؛ 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 غير فارغ
}

عيّن إما 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 تعني شهادة العرض التجريبية تحت رخصة مؤقتة، والتواقيع البصرية فقط تحت رخصة مدفوعة.

استكشاف الأخطاء وإصلاحها

العَرَضالسببالحل
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.رخصة مدفوعة، وضع معتمد، ولا شهادةقم بإعداد SigningCertificate، أو وقع في الوضع البصري
run يجيب 400 The signing certificate expired on yyyy-MM-dd.الشهادة منتهية الصلاحيةاستبدلها؛ التواقيع البصرية تستمر في العمل في الوقت الحالي
السجل يقول إن الإخراج "يستخدم شهادة العرض التجريبية المدمجة"، ومع ذلك رخصة مدفوعة ترفض التواقيع المعتمدةيُكتب هذا السطر كلما لم تُضبط شهادة، بغض النظر عن الرخصةقم بإعداد 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

هل كانت هذه الصفحة مفيدة؟