شروع سریع

رندر اولین سند خود را در چند دقیقه

این راهنما یک برنامهٔ ASP.NET Core را از یک Program.cs خالی به سندی که در مرورگر رندر می‌شود، می‌برد: ثبت سرور، بستهٔ کامل Viewer (نوار ابزار Viewer، نصب Viewer، و نوارهای اختیاری جستجو/حاشیه‌نویسی)، مراجع دارایی‌ها، مقداردهی اولیهٔ کلاینت، باز کردن سند، و اجرا.

تنظیم سرور

AddDoconut() سرویس‌ها را ثبت می‌کند؛ UseDoconutResources() و UseDoconut() میانه‌افزار را وصل می‌کنند. فراخوانی منابع باید ابتدا باشد. UseDoconut() به هر درخواست که به آن می‌رسد پاسخ می‌دهد، بنابراین آن را با app.Map در شاخهٔ جداگانه‌اش نصب کنید. فراخوانی‌های جلسه نیز لازم هستند — امنیت سند پیش‌فرض Doconut هر درخواست صفحه را در برابر وضعیت جلسهٔ ASP.NET اعتبارسنجی می‌کند. وضعیت جلسه به یک کش نیاز دارد: AddDistributedMemoryCache() یک مورد فراهم می‌کند. یک برنامهٔ MVC یا Razor Pages قبلاً آن را ثبت می‌کند، اما برنامهٔ minimal‑API این کار را نمی‌کند و بدون آن برنامه در زمان راه‌اندازی با Unable to resolve service for type 'IDistributedCache' متوقف می‌شود. آیا Doconut را در طول نصب قبلاً ثبت کرده‌اید؟ به بخش بعدی بروید.

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // حالت جلسه به یک کش نیاز دارد (MVC/Razor Pages در حال حاضر یک کش اضافه می‌کند)
builder.Services.AddSession(); // امنیت سند Doconut بر پایه حالت جلسه ASP.NET است

app.UseSession();          // قبل از UseDoconut()، UseSession() را فراخوانی کنید
app.UseDoconutResources(); // باید قبل از UseDoconut() ثبت شود
app.Map("/doconut", branch => branch.UseDoconut());

برای یک چیدمان مسیر به سبک تولید، میدلویر سند را به یک شاخهٔ صریح نگاشت کنید و چهار تنظیم مسیر را هم‌راستا نگه دارید:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath یک مقدار هماهنگی است؛ به تنهایی شاخهٔ ASP.NET Core را نگاشت نمی‌کند. در این مثال میزبان /doconut را نگاشت می‌کند، بنابراین کلاینت از BasePath: 'doconut' استفاده می‌کند. ResourcesPath بستهٔ جاسازی‌شده را در /doconut-res سرو می‌کند، و مسیر منبع تصویر ویجت به همین دلیل ResPath: 'doconut-res/images' است. هر دو را بدون اسلش پیش‌رو بنویسید: viewer خودش یک اسلش اضافه می‌کند، بنابراین '/doconut' به //doconut/DocImage.axd تبدیل می‌شود، که مرورگر آن را به عنوان درخواست به میزانی به نام doconut می‌خواند، و viewer با پیام "The viewer handler could not be reached" شکست می‌خورد.

افزودن viewer به یک صفحه

Viewer هستهٔ مورد نیاز صفحه است. سطح رندر آن از دو div تو در تو استفاده می‌کند:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

نوار ابزار، نصب‌های ماژول و سطح Viewer را به عنوان یک ترکیب صفحه در نظر بگیرید. جستجو و حاشیه‌نویسی نوارهای جاسازی‌شده خود را به نصب‌های اختیاری تزریق می‌کنند، اما این ماژول‌ها هرگز به‌تنهایی نیستند: همیشه به Viewer در همان صفحه متصل می‌شوند. از این ترتیب استفاده کنید:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- دکمه‌های ناوبری، زوم، جستجو و حاشیه‌نویسی Viewer -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

ارجاع به دارایی‌های viewer

در یک Razor view، سرویس تزریق‌شدهٔ Viewer تگ‌های <link> و <script> viewer را به ترتیب وابستگی تولید می‌کند — ویجت یک افزونهٔ jQuery است، بنابراین jQuery باید قبل از اسکریپت‌های viewer بارگذاری شود:

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss = true,
    IncludeViewerCss    = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery        = true,
    IncludeBootstrap     = true,
    IncludeViewerScripts = true
}))

برای بستهٔ کامل Viewer، منابع Viewer و ماژول را به‌صورت همزمان درخواست کنید:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss  = true,
    IncludeViewerCss     = true,
    IncludeSearchCss     = true,
    IncludeAnnotationCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeBootstrap         = true,
    IncludeViewerScripts     = true,
    IncludeSearchScripts     = true,
    IncludeSearchBar         = true,
    IncludeAnnotationScripts = true,
    IncludeAnnotationBar     = true
}))

IncludeViewerCss و IncludeViewerScripts پرچم‌های هسته‌ای اجباری هستند. هرگز مثال نوار جستجو یا حاشیه‌نویسی را بدون آن‌ها، نصب Viewer، و یک نمونهٔ docViewer منتشر نکنید. ReferenceCss و ReferenceScripts منابع یک ماژول اختیاری را زمانی که مجوز فعلی آن قابلیت را اعطا نمی‌کند، حذف می‌کنند؛ Viewer هسته‌ای همچنان شروع می‌شود.

مقداردهی اولیه نمایشگر

ویجت سمت‌کلاینت یک افزونه jQuery است. این یک مجموعهٔ حداقل گزینه‌های واقعی مقداردهی اولیه است (نه کد ساختگی):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   'doconut',             // بدون '/' پیشرو
    ResPath:    'doconut-res/images',  // بدون '/' پیشرو
    onViewerReady: function () {
        // صفحات قابل مشاهده‌اند؛ امن است که در اینجا لودر را مخفی کنید
    },
    // رویدادهای چرخه‌حیات annotation را به ribbon جاسازی‌شده وقتی موجود باشد، ارسال کنید
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

قالب‌بندی حروف گزینه‌ها واقعاً ترکیبی است — showThumbs، autoLoad، و pageZoom به صورت camelCase هستند، اما FitType، BasePath، و ResPath به صورت PascalCase. هیچ قاعدهٔ ثابتی وجود ندارد؛ اگر قالب‌بندی را اشتباه کنید گزینه به‌صورت ساکن نادیده گرفته می‌شود (ویجت به‌جای پرتاب خطا به مقدار پیش‌فرض خود باز می‌گردد).

چهار جزئیات دیگر بدون پیام خطا شکست می‌خورند:

  • BasePath دارای اسلش ابتدایی نیست. 'doconut' درخواست /doconut/DocImage.axd را می‌کند؛ '/doconut' باعث تولید //doconut/DocImage.axd می‌شود که مرورگر آن را به‌عنوان درخواست به میزبان دیگری می‌خواند.
  • ResPath: 'doconut-res/images' — آیکون‌ها یک پوشه زیر ریشهٔ منابع قرار دارند. با 'doconut-res'، هر آیکون ۴۰۴ برمی‌گرداند: هیچ نماد نوارابزار و هیچ چرخ‌دندهٔ بارگذاری وجود ندارد، در حالی که خود سند همچنان رندر می‌شود. یک اسلش ابتدایی همانند BasePath آن را خراب می‌کند.
  • Callbackها گزینه‌ها هستند. onViewerReady، onError و بقیه در شیء‌ای که به docViewer(...) پاس داده می‌شود قرار می‌گیرند. یک تابع سراسری با نام نمایشگر، مانند ctlDoc_ViewerReady، هرگز فراخوانی نمی‌شود.
  • نمایشگر را نگه دارید، سپس View را به‌صورت جداگانه فراخوانی کنید. docViewer(...) شیء‌ای را برمی‌گرداند که شامل Zoom، Next و FitType است؛ View(...) چیز دیگری برمی‌گرداند. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) سند را رندر می‌کند، سپس در اولین کلیک نوارابزار با objViewer.Zoom is not a function شکست می‌خورد.

ترکیب بستهٔ کامل Viewer

یک صفحهٔ کامل Viewer بخش‌های زیر را به‌صورت همزمان نصب می‌کند:

بخش بستهنیازمندینحوهٔ اتصال
منابع Viewer، mount، و objViewerضروریرندرکنندهٔ اصلی سند
نوارابزار Viewerضروری برای یک صفحهٔ کاملنشانه‌گذاری میزبان؛ دکمه‌ها همان objViewer را فراخوانی می‌کنند
نوار جستجواختیاری، ماژول دارای لایسنسdoconutSearchBar(...).attach(objViewer)
نوار حاشیه‌نویسیاختیاری، ماژول دارای لایسنسdoconutAnnotationBar(...).attach(objViewer)

اگرچه نوارابزار اصلی Viewer یک نشانه‌گذاری میزبان است، همراه با Viewer نصب می‌شود و هرگز نباید به‌عنوان یک کنترل جداگانه مستند شود. این کار چیدمان، برچسب‌ها، آیکون‌ها و قوانین مجوزدهی آن را تحت کنترل برنامهٔ شما نگه می‌دارد در حالی که هر دکمه همان نمونهٔ Viewer را هدایت می‌کند:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
    <button type="button" onclick="objViewer.FitType('height')">Fit height</button>
    <button type="button" id="openSearch">Search</button>
    <button type="button" id="openAnnotations">Annotations</button>
</nav>

کمک‌کننده‌های چرخش، تصویر کوچک، چاپ، تمام‌صفحه، چیدمان و وضعیت دکمه باید در اسکریپت نوارابزار خود شما قرار گیرند، که همان objViewer را فراخوانی می‌کند. آن را پس از Viewer.ReferenceScripts(...) بارگذاری کنید و همراه با نشانه‌گذاری <nav id="toolbar"> آن نگه دارید.

این ترتیب مقداردهی اولیه را حفظ کنید:

  1. CSS مربوط به Viewer و ماژول‌های دارای لایسنس را تولید کنید.
  2. نوارابزار Viewer، mountهای جستجو/حاشیه‌نویسی و mount Viewer را به‌صورت همزمان رندر کنید.
  3. اسکریپت‌های مربوط به Viewer و ماژول‌های دارای لایسنس را تولید کنید.
  4. اسکریپت کمکی نوارابزار خود برنامهٔ میزبان را بارگذاری کنید.
  5. docViewer را مقداردهی اولیه کنید و objViewer حاصل را نگه دارید.
  6. هر نوار جستجو یا حاشیه‌نویسی دارای لایسنس را مقداردهی اولیه کنید.
  7. در هر نوار attach(objViewer) را فراخوانی کنید.
  8. سند را باز کنید و توکن آن را برای درخواست‌های Viewer و ماژول نگه دارید.

در یک استقرار توزیع‌شده، مقدار درخواست اضافی access و تنظیمات تلاش مجدد رندر ناهمزمان متعلق به لایهٔ انتقال هستند؛ آن‌ها نحوهٔ ترکیب Viewer، نوارابزار یا نوارها را تغییر نمی‌دهند.

محافظ‌های سمت‑سرور مهم هستند: وقتی یک قابلیت اختیاری در دسترس نیست، اسکریپت آن تولید نمی‌شود، بنابراین تابع افزونهٔ jQuery آن وجود ندارد.

html
<script>
    let token = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    annBar.attach(objViewer);
        </text>
    }

    document.getElementById('openSearch').addEventListener('click', () => {
        if (!searchBar) return;
        searchBar.isOpen() ? searchBar.close() : searchBar.open();
    });

    document.getElementById('openAnnotations').addEventListener('click', () => {
        if (!annBar) return;
        annBar.isOpen() ? annBar.close() : annBar.open();
    });
</script>

هر دو مؤلفهٔ جاسازی‌شده DOM نوار خود را تولید می‌کنند. جستجو شامل گروه‌های Find، Options و Results است. حاشیه‌نویسی شامل ابزارهای نویسندگی، کنترل‌های سبک، عملیات ذخیره و عملیات اختیاری export/image است. نوارها open()، close()، reset() و isOpen() را در دسترس می‌گذارند؛ همیشه پس از ایجاد آن‌ها یک بار attach(objViewer) را فراخوانی کنید.

مثال بالا callbackهای اختیاری میزبان و نقاط انتهایی export/image حاشیه‌نویسی را برای حفظ حداقل‌سازی راه‌اندازی حذف کرده است. برای تنظیم کامل ویژگی‑محور به Search و Annotations مراجعه کنید، یا برای استایل یا جایگزینی نوارابزار Viewer متعلق به میزبان به Custom Themes نگاه کنید.

باز کردن یک سند

سمت سرور یک نقطه انتهایی است: سرویس تزریق‌شده Viewer سند را باز می‌کند و یک توکن نشست برمی‌گرداند.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // توکن غیرقابل‌خواندن است — آن را به widget بدهید، هرگز لاگ نکنید یا ذخیره نکنید.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

کلاینت این توکن را دریافت می‌کند و آن را به ویجت با objViewer.View(token) می‌دهد:

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

بستن سند

زمانی که کاربر ویور را ترک می‌کند یا سند جایگزینی باز می‌کند، objViewer.Close(true) را فراخوانی کنید: این کار ویجت را پاک می‌کند و درخواست بستن را به سرور ارسال می‌نماید. objViewer.Close() بدون آرگومان فقط ویجت را پاک می‌کند. در جریان‌های کاری مبتنی بر سرور، viewer.CloseDocument(token) بلافاصله نشست کش‌شده را حذف می‌کند، موتور رندرینگ را از بین می‌برد، علامت امنیتی آن را پاک می‌سازد و توکن را لغو می‌کند. انقضای لغزان به‌تدریج همان پاک‌سازی را انجام می‌دهد، اما بسته شدن صریح برای اسناد بزرگ توصیه می‌شود.

جریان کامل درخواست به‌صورت زیر است:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

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

اجرا

یک فایل PDF را در wwwroot/files/Sample.pdf قرار دهید، dotnet run را اجرا کنید و صفحه‌ای که ویجت را میزبانی می‌کند باز کنید. صفحهٔ اول در ویور رندر می‌شود، با یک پنل تصویر بند انگشتی در سمت چپ. اگر این‌طور نیست، به بخش عیب‌یابی مراجعه کنید.

آنچه بدون لایسنس دریافت می‌کنید

عدم وجود لایسنس خطایی نمی‌اندازد. ویور به‌صورت عادی رندر می‌شود، اما هر صفحه یک واترمارک ارزیابی دارد. برای آگاهی از نحوهٔ یافتن لایسنس توسط Doconut و تغییراتی که پس از آن رخ می‌دهد، به بخش راه‌اندازی لایسنس مراجعه کنید.

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