شروع سریع

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

این راهنما یک برنامهٔ 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(); // session state به یک کش نیاز دارد (MVC/Razor Pages قبلاً یکی اضافه می‌کند)
builder.Services.AddSession(); // امنیت سند Doconut بر پایه session state 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' است. هر دو را بدون اسلش پیش‌رو بنویسید: نمایشگر خود یک اسلش اضافه می‌کند، بنابراین '/doconut' به //doconut/DocImage.axd تبدیل می‌شود، که مرورگر آن را به عنوان درخواست به میزانی به نام doconut می‌خواند و نمایشگر با خطای «The viewer handler could not be reached» شکست می‌خورد.

افزودن نمایشگر به صفحه

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

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

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

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

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

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

ارجاع به دارایی‌های نمایشگر

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

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 () {
        // صفحات قابل مشاهده‌اند؛ امن است که در اینجا نشانگر بارگذاری را مخفی کنید
    },
    // رویدادهای چرخه‌حیات حاشیه‌نویسی را به نوار ابزار توکار هدایت کنید وقتی که موجود باشد.
    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'، هر آیکون 404 برمی‌گرداند: هیچ نماد نوار ابزار و هیچ چرخ‌دندهٔ بارگذاری وجود ندارد، در حالی که خود سند همچنان رندر می‌شود. یک اسلش ابتدایی آن را به همان شیوهٔ 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 toolbarضروری برای یک صفحهٔ کاملنشانه‌گذاری میزبان؛ دکمه‌ها همان 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 و تنظیمات retry رندر ناهمزمان متعلق به لایهٔ انتقال هستند؛ آن‌ها نحوهٔ ترکیب 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 حاشیه‌نویسی را برای حفظ حداقل‌سازی راه‌اندازی حذف کرده است. به جستجو و حاشیه‌نویسی برای تنظیم کامل ویژگی‑محور مراجعه کنید، یا به تم‌های سفارشی برای استایل‌دهی یا جایگزینی نوار ابزار Viewer متعلق به میزبان مراجعه کنید.

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

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

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // توکن نامشخص است — آن را به ویجت بدهید، هرگز log یا persist نکنید.
    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) بلافاصله جلسهٔ ذخیره‌شده را حذف می‌کند، موتور رندرینگ را از بین می‌برد، نشانگر امنیتی آن را پاک می‌سازد و توکن را باطل می‌کند. انقضای Sliding در نهایت همان پاک‌سازی را انجام می‌دهد، اما بستن صریح برای اسناد بزرگ توصیه می‌شود.

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

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

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

اجرای آن

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

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

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

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