پلاگین امضاکننده

امضای اسناد 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.NET8.Signer

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

bash
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 اجرا می‌شود اجرا می‌شود: ویندوز و لینوکس مبتنی بر 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() است (به ویجت Drop‑in مراجعه کنید).

پلاگین به مجوزی نیاز دارد که قابلیت 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 تنظیم می‌شود (امضای قابل مشاهده + مهر دیجیتال)؛ 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 (پیش‌فرض)امضای قابل مشاهده به‌همراه یک مهر دیجیتالدر یک لایسنس پولی لازم استبله
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 بدهید. یا بایت‌ها یا مسیر را به‌همراه رمز عبور فراهم کنید:

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 را باز کنید و گواهی را پیدا کنید (آیکون آن زمانی که کلید خصوصی موجود باشد، یک کلید نشان می‌دهد). روی آن کلیک راست کنید، تمام وظایف → خروجی… را انتخاب کنید، بله، کلید خصوصی را صادر کنید را انتخاب کنید، تبادل اطلاعات شخصی – 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: ببینید Certificate راه‌اندازی؛ برای demo (watermarked) امضا آن را 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 یا یک عنصر را می‌گیرد، اگر mount پیدا نشود خطا می‌اندازد و یک handle برمی‌گرداند.

امضاکننده یک فایل 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گزینه Digital signature / Visual only را نشان می‌دهد. با false، ویجت با signatureMode امضا می‌کند
wordOutputstring'pdf'خروجی اولیه برای منابع .docx: 'pdf' یا 'docx'. هر مقدار دیگر به 'pdf' تبدیل می‌شود
showOutputFormatTogglebooleantrueگزینه PDF / Word را نشان می‌دهد، فقط برای منابع .docx. با false، ویجت از wordOutput استفاده می‌کند
labelsobject{}هر زیرمجموعه‌ای از رشته‌های انگلیسی را بازنویسی می‌کند

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

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

بازگشت‌ها

بازگشتزمان اجرابار
onReadyیک‌بار، هنگام mount (دوباره در reset() نیست)—
onSourceLoadedفایل باز می‌شود و پیش‌نمایش آن نشان داده می‌شود{ file: { token, name, pages, ext } }
onSignedامضا موفق می‌شود{ downloadToken, downloadName, watermarked }
onDownloadدر هر کلیک دانلود{ downloadName, downloadToken }
onErrorیک مرحله باز کردن، امضا یا دانلود شکست می‌خورد، یا فایل حالت Image بیش از حد بزرگ است{ message }

یک بازگشت که خطا می‌اندازد، گرفته و لاگ می‌شود؛ هرگز جریان ویجت را خراب نمی‌کند.

دستگیره امری

متدرفتار
reset()به صفحهٔ رهاسازی باز می‌گردد و جریان فعلی را پاک می‌کند. دوباره onReady را فراخوانی نمی‌کند. پس از destroy() هیچ کاری انجام نمی‌دهد.
loadFile(file)جریان را با یک File آغاز می‌کند. مگر اینکه ویجت در صفحهٔ رهاسازی باشد، کاری انجام نمی‌دهد؛ در صورت نیاز ابتدا reset() را فراخوانی کنید.
destroy()شنونده‌ها را حذف می‌کند، نقطهٔ نصب را خالی می‌سازد و نمونه را منجمد می‌کند.
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 (چندبخشی، یک فایل)یک PDF یا .docx را بارگذاری کنید و برای پیش‌نمایش باز کنید200 — { token, name, pages, ext }
POST ?sign=run (بدنه JSON)فایل بارگذاری‌شده را امضا کنید200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>فایل امضاشده را به‌صورت جریان (stream) ارائه دهید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 / h0..1 نرمال‌شده از گوشهٔ بالا‑چپ، با x + w ≤ 1 و y + h ≤ 1
meta.signerName / reason / locationاختیاری. هر کدام برش می‌شوند، مقدار خالی حذف می‌شود و هر کدام به ۲۵۶ کاراکتر محدود می‌شوند
wordOutputpdf (پیش‌فرض) یا docx؛ برای منابع PDF نادیده گرفته می‌شود. هر چیز دیگر به pdf تبدیل می‌شود
modecertified (پیش‌فرض) یا visual. هر چیز دیگر به certified تبدیل می‌شود

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

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

مسیروضعیتزمانبدنه
هرکدام404ویجت فعال نیستفقط وضعیت
هرکدام405فعل نادرست (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.NET8.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 باید حداقل ۳۲ بایت باشد و در هر گره یکسان باشد. آن را از یک مخزن اسرار بارگذاری کنید؛ هرگز به‌صورت ثابت کد نکنید. ثبت‌نام هنگام عدم وجود RootPath یا کوتاه‌تر بودن FarmKey از ۳۲ بایت، یک ArgumentException را پرتاب می‌کند.
  • 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 and 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 از ۱ شروع می‌شود؛ X، Y، W و H از گوشهٔ بالا‑چپ به صورت 0..1 نرمال‌سازی می‌شوند.

SignatureMode and 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 را برمی‌گرداند تا فراخوانی‌ها زنجیره‌ای شوند. یک 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()
خروجی دارای واترمارک استمجوز موقت است (دمو/NFR)از یک مجوز پرداختی که Signer را اعطا می‌کند استفاده کنید
run پاسخ می‌دهد 400 No signing certificate configured.یک مجوز پرداختی، حالت Certified، و بدون گواهیپیکربندی کنید SigningCertificate، یا در حالت Visual امضا کنید
run پاسخ می‌دهد 400 The signing certificate expired on yyyy-MM-dd.گواهی منقضی شده استآن را جایگزین کنید؛ امضاهای بصری در این میان کار می‌کنند
لاگ می‌گوید خروجی «از گواهی دموی داخلی استفاده می‌کند»، اما یک مجوز پرداختی امضاهای 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 استدر AddSignerWidget MaxUploadMb را افزایش دهید؛ maxUploadMb ویجت فقط یک بررسی سمت کلاینت است
run یا download پاسخ می‌دهد 404 Upload expired — please re-open the file.پنجرهٔ ۳۰ دقیقه‌ای تمام شده است، یا یک گرهٔ وب‌فارم آپلود را نداردفایل را دوباره باز کنید؛ در یک فارم، AddDoconutDistributedWidgets را ثبت کنید
یک .docx امضا شده در برخی نمایشگرها امضایی نشان نمی‌دهدخروجی Word شامل امضای بستهٔ OOXML است، که بسیاری از نمایشگرها آن را نشان نمی‌دهندبه PDF امضا کنید، پیش‌فرض
خوانندگان PDF می‌گویند هویت امضا کننده ناشناخته استخواننده ریشهٔ گواهی را اعتماد نمی‌کند (گواهی دموی هرگز مورد اعتماد نیست)از یک گواهی از ریشه‌ای که خوانندگان شما به آن اعتماد دارند استفاده کنید
ویجت وقتی UI در منبع دیگری است شکست می‌خوردنقطه‌های انتهایی پشتیبانی CORS ندارندUI را از همان منبع سرو کنید، یا مسیرهای Doconut را معکوس-پروکسی کنید
تم اعمال نمی‌شودانتخابگر به عنصری داخل mount هدف می‌گیردمستقیم به خود mount هدف بگیرید: #host.dsw یا #host

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