شروع سریع

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

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

برنامهٔ میزبان باید به زمان‌اجرایی که netstandard2.1 را پشتیبانی می‌کند هدف‌گذاری شود — .NET Core 3.0 یا بالاتر.

Server setup

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());

این تنظیمات شکل تاریخی درخواست DocImage.axd را حفظ می‌کند و میانه‌افزار سند را بر روی شاخهٔ متناسب نصب می‌کند. این ترتیب برای کپی کردن زمانی که برنامهٔ .NET Standard موجود را پیش می‌برید، مناسب است، زیرا کلاینت همان URL را که همیشه استفاده می‌کرد، فراخوانی می‌کند:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // بررسی جلسه Doconut فعال بماند
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // حالت جلسه به یک حافظهٔ نهان نیاز دارد (MVC/Razor Pages در حال حاضر یکی را اضافه می‌کند)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// برای کدگذاری‌های چند بایتی در برخی فرمت‌های سند لازم است.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // قبل از شاخهٔ سند
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() در این نسخه گزینه‌ای نمی‌گیرد — همه چیز به AddDoconut() منتقل شده است.

MiddlewarePath یک مقدار هماهنگی است؛ به تنهایی شاخهٔ ASP.NET Core را نقشه‌برداری نمی‌کند. با شاخهٔ DocImage.axd بالا، کلاینت از BasePath: '/' استفاده می‌کند؛ با app.Map("/doconut", ...) از تنظیمات حداقل، از BasePath: 'doconut' استفاده می‌کند.

ResourcesPath بستهٔ جاسازی‌شده را در /doconut-res سرو می‌کند، و مسیر منبع تصویر ویجت به همین دلیل ResPath: 'doconut-res/images' است.

Add the viewer to a page

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>

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

در یک 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 پرچم‌های اصلی اجباری هستند. هرگز یک مثال Search یا Annotation Ribbon بدون آنها، نصب Viewer، و یک docViewer نمونه. ReferenceCss و ReferenceScripts منابع یک ماژول اختیاری را حذف می‌کنند وقتی مجوز فعلی آن قابلیت را نمی‌دهد؛ Viewer اصلی همچنان شروع می‌شود.

این فراخوانی‌ها جایگزین فایل‌های اسکریپت کپی‑دستی می‌شوند. اگر برنامه هنوز docViewer.js، documentLinks.js یا docViewer.UI.js خود را بارگذاری می‌کند، پس از اینکه صفحه با منابع تولید شده کار کرد، آن تگ‌ها را حذف کنید — برای جزئیات به راهنمای مهاجرت مراجعه کنید.

راه‌اندازی نمایشگر

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

javascript
let searchBar = null;
let annBar = null;

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

چهار جزئیات تعیین می‌کنند که آیا این صفحه به‌طور کلی کار می‌کند یا نه:

  • Callbackها گزینه هستند. onViewerReady، onViewerBusy، onCopy، و onAutoLoadStatus در شیء گزینه‌ها پاس داده می‌شوند. نمایشگر قبلی نام‌های تابع سراسری را از شناسهٔ کانتینر استخراج می‌کرد و آنها را فراخوانی می‌کرد؛ این یکی این کار را نمی‌کند. یک هندلر که فقط به‌عنوان تابع سراسری اعلام شده باشد هرگز اجرا نمی‌شود و هیچ‌چیزی گزارش نمی‌شود.
  • ResPath به پیشوند منابع اشاره می‌کند, نه ریشهٔ برنامه. با پیش‌فرض ResourcesPath، آن مقدار برابر است با doconut-res/images. اگر ResourcesPath را تغییر داده‌اید، به‌جای آن پیشوند خودتان را استفاده کنید. آیکون‌ها یک پوشه زیر ریشهٔ منابع قرار دارند: با 'doconut-res'، هر آیکون 404 برمی‌گرداند در حالی که خود سند هنوز رندر می‌شود.
  • BasePath پیش‌نشان اسلش ندارد جز مقدار ریشهٔ سایت '/'. 'doconut' درخواست می‌کند /doconut/DocImage.axd؛ '/doconut' تولید می‌کند //doconut/DocImage.axd، که مرورگر آن را به‌عنوان درخواست به میزبان دیگری می‌خواند.
  • نمایشگر را نگه دارید، سپس View را جداگانه فراخوانی کنید. docViewer(...) شیء را با Zoom، Next و FitType؛ View(...) چیز دیگری برمی‌گرداند. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) سند را رندر می‌کند، سپس با objViewer.Zoom is not a function در اولین کلیک نوار ابزار شکست می‌خورد.

همهٔ این‌ها به‌صورت ساکت شکست می‌خورند — برای راهنمایی به عیب‌یابی و راهنمای مهاجرت مراجعه کنید.

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

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

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

بخش بستهنیازمندینحوه اتصال
منابع Viewer، سوار شدن، و 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>

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

  1. CSS مربوط به Viewer و ماژول‌های دارای مجوز را تولید کنید.
  2. نوار ابزار Viewer، سوارهای جستجو/حاشیه‌نویسی و سوار Viewer را به‌صورت همزمان رندر کنید.
  3. اسکریپت‌های مربوط به Viewer و ماژول‌های دارای مجوز را تولید کنید.
  4. اسکریپت کمکی نوار ابزار برنامهٔ میزبان را بارگذاری کنید.
  5. docViewer را مقداردهی اولیه کنید و objViewer حاصل را نگه دارید.
  6. هر نوار جستجو یا حاشیه‌نویسی دارای مجوز را مقداردهی اولیه کنید.
  7. برای هر نوار، attach(objViewer) را فراخوانی کنید.
  8. سند را باز کنید و توکن آن را برای درخواست‌های 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 است. حاشیه‌نویسی ابزارهای نوشتاری، کنترل‌های سبک، عملیات ذخیره و عملیات اختیاری صادرات/تصویر را در بر دارد. این نوارها open()، close()، reset() و isOpen() را در دسترس می‌گذارند؛ همیشه پس از ایجاد آن‌ها، یک‌بار attach(objViewer) را فراخوانی کنید.

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

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

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

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // توکن نامشخص است — آن را به ویجت بدهید، هرگز لاگ نکنید یا ذخیره نکنید.
    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);
    });

قبل از اولین باز کردن چیزی برای گرم‌کردن وجود ندارد. اگر برنامه‌ای را به‌سوی جلو می‌برید، هر فراخوانی InitCache() و پرچمی که آن را محافظت می‌کند حذف کنید — این متد دیگر وجود ندارد.

بستن سند

زمانی که کاربر ویور را ترک می‌کند یا سند جایگزینی باز می‌کند، 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 و تغییراتی که پس از یافتن آن رخ می‌دهد، به بخش راه‌اندازی لایسنس مراجعه کنید.

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