افزونه Signer

امضای PDF و اسناد Word با امضای قابل مشاهده و مهر دیجیتال

افزونه Signer یک امضای قابل مشاهده روی سند قرار می‌دهد و به‌صورت پیش‌فرض آن را با یک امضای دیجیتال مهر می‌زند که یک خواننده PDF می‌تواند آن را تأیید کند. این افزونه فایل‌های PDF و Word (.docx) را امضا می‌کند. امضای قابل مشاهده همیشه یک تصویر PNG است: کشیده‌شده، تایپ‌شده یا توسط امضاکننده بارگذاری شده.

سطحزمانی که استفاده می‌کنید
DocumentSigner (C#)شما روی سرور امضا می‌کنید و مرورگری درگیر نیست
ویجت تعبیه‌شده (doconutSigner.js)می‌خواهید یک صفحه آماده بارگذاری، امضا و دانلود در صفحه خود داشته باشید
نقاط انتهایی HTTP (?sign=open|run|download)می‌خواهید رابط کاربری امضای خود را بر پایه یک قرارداد سرور مستند بسازید

هر امضا یک‌بار، بر روی یک صفحه قرار می‌گیرد. نام امضاکننده، دلیل و مکان می‌توانند همراه آن حرکت کنند.

نصب بسته

نصب آخرین نسخه پایدار افزونه Signer:

bash
dotnet add package Doconut.NETStandard.Signer

برای قفل کردن افزونه به نسخه‌ای که این مستندات توصیف می‌کند، نسخه را به‌صورت جداگانه پاس دهید:

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

بسته Signer را با همان نسخه‌ی Doconut.NETStandard نگه دارید. شناسه بسته Doconut.NETStandard.Signer است؛ .<version> فقط در نام فایل دانلود شده‌ی .nupkg ظاهر می‌شود.

فایل مجوز افزونه، Doconut.Viewer.Signer.lic، در همان پوشه‌ای که Doconut.Viewer.lic قرار دارد قرار می‌گیرد؛ همراه با مجوز نمایشگر خوانده می‌شود.

ثبت افزونه

مانند هر افزونه Doconut، Signer با AddPlugin<TPlugin>() داخل AddDoconut() ثبت می‌شود:

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

این تمام آنچه فاساد C# نیاز دارد. ویجت و نقاط انتهایی HTTP آن یک گزینه‌ی جداگانه‌ی opt‑in هستند، 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");
        // Mode به صورت پیش‌فرض به 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") تا بتوانید نام فایل را تعیین کنید. شما مالک جریان هستید: هنگام اتمام آن را dispose کنید.

یک امضای Visual فقط تصویر را مهر می‌زند و نیازی به گواهی ندارد:

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

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

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

یک منبع Word به PDF امضا می‌شود مگر اینکه خروجی Word را درخواست کنید. نام نتیجه را از result.Extension بگیرید:

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

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

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

SignAsync به جای بازگشت، هنگام عدم موفقیت فراخوانی استثنا می‌اندازد:

استثناپیامزمان
InvalidOperationExceptionNo signing certificate configured.حالت Certified، یک لایسنس پرداخت‌شده، و عدم ارسال گواهی
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.حالت Certified با گواهی خارج از بازه اعتبار آن
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.بایت‌های خالی PNG، یا موقعیتی که معتبر نیست
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.هر نوع منبع دیگری

حالت‌های امضا، خروجی Word و گواهی‌ها

حالت‌های امضا

SignRequest.Mode انتخاب می‌کند که آیا امضا مهر می‌شود یا نه.

حالتچه چیزی تولید می‌کندگواهیقابل تأیید
SignatureMode.Certified (پیش‌فرض)امضای قابل مشاهده به‌همراه یک مهر دیجیتالتحت یک لایسنس پرداخت‌شده لازم استبله
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 بتوانند آن را حمل کنند.
  • رمز عبور صحیح.
  • در بازهٔ اعتبار خود. یک گواهی‌نامه منقضی شده یا هنوز معتبر نیست برنامه را متوقف نمی‌کند: به‌عنوان هشدار در زمان راه‌اندازی لاگ می‌شود و امضاهای Certified تا جایگزینی آن رد می‌شوند. امضاهای Visual تحت تأثیر قرار نمی‌گیرند.
  • صادر شده برای امضای سند: استفاده از کلید با امضای دیجیتال یا عدم انکار، و استفادهٔ کلید گسترش‌یافته، اگر موجود باشد، که اجازهٔ امضای سند، حفاظت ایمیل یا احراز هویت مشتری را می‌دهد. گواهی‌نامه‌ای که برای چیز دیگری صادر شده باشد، مانند گواهی‌نامهٔ سرور TLS، هنوز امضا می‌کند، اما به‌عنوان هشدار لاگ می‌شود و خوانندگان PDF امضا را پرچم می‌زنند.
  • توکن‌های سخت‌افزاری، کارت‌های هوشمند، HSMها و فروشگاه گواهی‌نامه ویندوز پشتیبانی نمی‌شوند. گواهی‌نامه را همراه با کلید خصوصی و زنجیره‌اش به یک PFX صادر کنید.

یک PFX از گواهی‌نامه و کلید خصوصی آن ایجاد کنید با OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# رمز عبور صادراتی که از شما درخواست می‌شود SigningCertificate.Password است.

از فروشگاه گواهی‌نامه ویندوز یک مورد صادر کنید: certmgr.msc را باز کنید و گواهی‌نامه را پیدا کنید (آیکون آن زمانی که کلید خصوصی موجود باشد، یک کلید نشان می‌دهد). روی آن کلیک راست کنید، همه وظایف → صدور… را انتخاب کنید، بله، کلید خصوصی را صادر کنید را برگزینید، 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.

آن خط آخر تحت هر مجوز یکسان است. تحت یک مجوز پولی، گواهی‌نامهٔ نمایشی هرگز استفاده نمی‌شود: بدون گواهی‌نامه، فقط امضاهای Visual کار می‌کنند.

واسط C# در زمان راه‌اندازی بررسی نمی‌شود. گواهی‌نامه‌ای که به SignAsync پاس می‌دهید هنگام امضا خوانده می‌شود، بنابراین مسیر یا رمز عبور اشتباه باعث شکست آن فراخوانی می‌شود.

ویجت Drop‑in

فعال‌سازی نقاط انتهایی

نقاط انتهایی ?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: ببینید تنظیم گواهی؛ برای نمایشی (دارای واترمارک) آن را 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حداکثر سمت کلاینت برای حالت Image. آن را برابر با MaxSignatureImageKb سرور نگه دارید
previewWidthnumber560عرض پیکسل پیش‌نمایش صفحه
licenseUrlstring | nullnullاعلان watermark دمو را به لینکی به این URL تبدیل می‌کند
signatureModestring'certified'نوع امضای اولیه: 'certified' یا 'visual'. هر مقدار دیگر به 'certified' تبدیل می‌شود
showSignatureModeTogglebooleantrueگزینه امضای دیجیتال / فقط بصری را نشان می‌دهد. با false، ویجت با signatureMode امضا می‌کند
wordOutputstring'pdf'خروجی اولیه برای منابع .docx: 'pdf' یا 'docx'. هر مقدار دیگر به 'pdf' تبدیل می‌شود
showOutputFormatTogglebooleantrueگزینه PDF / Word را نشان می‌دهد، فقط برای منابع .docx. با false، ویجت از wordOutput استفاده می‌کند
labelsobject{}هر زیرمجموعه‌ای از رشته‌های انگلیسی را بازنویسی می‌کند

پنهان کردن یک سوئیچ ویژگی را غیرفعال نمی‌کند؛ مقدار را ثابت می‌کند. دو پیکربندی رایج:

javascript
// هر دو سوئیچ نشان داده می‌شوند، امضای دیجیتال به‌صورت پیش‌فرض: یک امضاکننده کامل خودخدمت.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// فقط بصری، بدون سوئیچ: یک مهر ساده بدون ارائه امضای دیجیتال.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

فراخوانی‌ها

فراخوانیزمان اجراداده
onReadyیک بار، هنگام سوار شدن (دوباره در 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، یک قلم UI سیستمی، و یک قلم امضای خوشنویسی.

ساخت فرانت‌اند خودتان

ویجت یک کلاینت برای این قرارداد HTTP است. هر سه مسیر زیر مسیری که UseDoconut() سوار شده است (به طور معمول /doconut) قرار دارند و تا زمانی که AddSignerWidget() فراخوانی شود، به 404 پاسخ می‌دهند. خطاها شامل بدنه JSON هستند، { "error": "..." }، به‌جز جایی که جدول می‌گوید «فقط وضعیت». مقدار ناشناخته ?sign= به 400 پاسخ می‌دهد.

مسیرهدفپاسخ موفق
POST ?sign=open (multipart, one file)آپلود یک PDF یا .docx و باز کردن آن برای پیش‌نمایش200 — { token, name, pages, ext }
POST ?sign=run (JSON body)امضای فایل آپلود شده200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>پخش فایل امضا شده200 — فایل، Content-Disposition: attachment، Cache-Control: no-store

ext در پاسخ open شامل نقطه پیشرو (".docx") است. پیش‌نمایش صفحه از مسیر تصویر نمایشگر استاندارد، {basePath}?token={token}&page={n}&thumb=1&width={px} استفاده می‌کند؛ صفحه نمایش داده شده به placement.page تبدیل می‌شود.

بدنه run:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
فیلدنکات
tokenتوکن از open
signature.kindDrawn، Typed یا Image، بدون حساسیت به حروف؛ هر چیز دیگری به Drawn تبدیل می‌شود. فقط یک نکته: داده همیشه یک PNG است
signature.payloadیک PNG پایه base64، بدون پیشوند data:. باید یک PNG واقعی باشد و پس از رمزگشایی بزرگتر از MaxSignatureImageKb نباشد
placement.pageمبتنی بر ۱
placement.x / y / w / h‏0..1 نرمال‌شده از گوشه بالا‑چپ، با x + w ≤ 1 و y + h ≤ 1
meta.signerName / reason / locationاختیاری. هر کدام برش می‌شوند، مقدار خالی حذف می‌شود، و هر کدام به ۲۵۶ کاراکتر محدود می‌شود
wordOutput‏pdf (پیش‌فرض) یا docx؛ برای منابع PDF نادیده گرفته می‌شود. هر چیز دیگری به pdf تبدیل می‌شود
mode‏certified (پیش‌فرض) یا visual. هر چیز دیگری به certified تبدیل می‌شود

‏downloadName خروجی را دنبال می‌کند: <source>-signed.pdf یا <source>-signed.docx، و download ‎Content-Type مطابقت‌دار را ارسال می‌کند.

منبع آپلود شده و نتیجه امضا شده هر کدام برای ۳۰ دقیقه نگهداری می‌شوند. پس از آن، run و download به 404 پاسخ می‌دهند و فایل باید دوباره باز شود. تمام توکن‌ها GUID هستند.

مسیروضعیتزمانبدنه
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آپلود بیش از MaxUploadMb استFile is too large.
run400بدنه JSON معتبر نیست یا خالی استMalformed request. / Empty request.
run400توکن موجود نیست یا GUID نیستInvalid token.
run404آپلود منقضی شده یا هرگز باز نشدهUpload expired — please re-open the file.
run400امضا وجود ندارد یا قرارگیری نیستNo signature supplied. / No placement supplied.
run400داده base64 نیست، خالی است، بیش از حد بزرگ است یا PNG نیستSignature 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 ندارد. UI و اسکریپت ویجت را از همان مبدا Doconut سرو کنید، یا هر دو مسیر /doconut (مسیر میانی و مسیر منابع) را تحت مبدا UI خود معکوس‑پروکسی کنید.

در محیط تولید

  1. پلاگین را نصب کنید در کنار بستهٔ هسته، با همان نسخه: dotnet add package Doconut.NETStandard.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;                   // حداقل ۳۲ بایت، یکسان در هر گره
    // store.Ttl = TimeSpan.FromMinutes(30);   // مدت زمان نگهداری یک بارگذاری (پیش‌فرض)
});
  • یک سرور تک‌نقشه به چیزی نیاز ندارد: بدون این فراخوانی، فروشگاه در‑حافظه استفاده می‌شود.
  • بارگذاری‌ها و نتایج در حالت استراحت بر روی اشتراک رمزگذاری می‌شوند (AES-256، encrypt-then-MAC)، و هر فایل به توکن خود متصل است، به طوری که یک توکن هرگز نمی‌تواند فایل توکن دیگر را بخواند.
  • FarmKey باید حداقل ۳۲ بایت باشد و در هر گره یکسان باشد. آن را از یک مخزن اسرار بارگذاری کنید؛ هرگز به‌صورت ثابت کدنویسی نکنید. ثبت‌نام یک ArgumentException را زمانی که RootPath موجود نیست یا FarmKey کوتاه‌تر از ۳۲ بایت است، پرتاب می‌کند.
  • RootPath را به همان مکان مشترکی که نمایشگر توزیع‌شده استفاده می‌کند، اشاره دهید و به هر گره همان گواهی امضا را بدهید.

مرجع API

واسط و گزینه‌های ویجت در فضای نام Doconut قرار دارند؛ انواع درخواست و نتیجه در Doconut.Core.Models.Signing هستند. SignerPlugin در Doconut.Plugins.Signer قرار دارد.

امضاکننده سند

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 نادیده گرفته می‌شود، و خروجی دارای واترمارک است.

درخواست امضا

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
}

یک امضای قابل مشاهده یک بار قرار می‌گیرد، به‌اضافهٔ فرادادهٔ اختیاری امضاکننده.

امضای قابل مشاهده و نوع امضا

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes خالی نیست
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes برای هر نوع یک PNG است. یک امضای کشیده‌شده یا تایپ‌شده شفاف است؛ یک تصویر بارگذاری‌شده شفافیت خود را حفظ می‌کند، بنابراین یک JPG مات همان‌طور که هست باقی می‌ماند. Kind فقط یک نکته است.

مکان‌گذاری امضا

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 از ۱ شروع می‌شود؛ X، Y، W و H از گوشهٔ بالا‑چپ به صورت 0..1 نرمال‌سازی می‌شوند.

حالت امضا و خروجی Word

csharp
public enum SignatureMode { Certified, Visual }   // Certified پیش‌فرض است
public enum WordOutput { Pdf, Docx }              // Pdf پیش‌فرض است; برای منابع PDF نادیده گرفته می‌شود

نتیجه‌امضا

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

سند امضا شده به‌صورت یک جریان قابل جستجو، و پسوند آن با نقطه (".pdf" یا ".docx").

گواهی‌امضا

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.

گزینه‌های ویجت امضاکننده

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 را برمی‌گرداند تا فراخوانی‌ها زنجیره‌ای شوند. یک 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 ثبت نشده استدرون AddDoconut() ، AddPlugin<SignerPlugin>() را اضافه کنید
خروجی دارای واترمارک استمجوز موقت است (دمو/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.پنجرهٔ ۳۰ دقیقه‌ای تمام شده است، یا یک گرهٔ وب‌فارم آپلود را نداردفایل را دوباره باز کنید؛ در یک فارم، AddDoconutDistributedWidgets را ثبت کنید
یک .docx امضا شده در برخی نمایشگرها امضایی نشان نمی‌دهدخروجی Word دارای امضای بسته OOXML است که بسیاری از نمایشگرها آن را نشان نمی‌دهندبه PDF امضا کنید، پیش‌فرض
خوانندگان PDF می‌گویند هویت امضاکننده ناشناخته استخواننده ریشهٔ گواهی را اعتماد نمی‌کند (گواهی دموی هرگز مورد اعتماد نیست)از گواهی‌ای که از ریشه‌ای که خوانندگان شما به آن اعتماد دارند استفاده کنید
ویجت هنگام اینکه UI در منبع دیگری باشد، شکست می‌خوردنقطه‌های انتهایی پشتیبانی CORS ندارندUI را از همان منبع سرو کنید، یا مسیرهای Doconut را به‌صورت reverse‑proxy کنید
تم اعمال نمی‌شودسلکتور به عنصری داخل mount هدف می‌گیردمستقیم به mount هدف بگیرید: #host.dsw یا #host

آیا این صفحه مفید بود؟