เริ่มต้นอย่างรวดเร็ว

แสดงเอกสารแรกของคุณในไม่กี่นาที

คำแนะนำนี้นำแอป ASP.NET Core จาก Program.cs ที่ว่างเปล่าไปสู่เอกสารที่แสดงในเบราว์เซอร์: การลงทะเบียนเซิร์ฟเวอร์, แพ็คเกจ Viewer ครบชุด (แถบเครื่องมือ Viewer, การเมานท์ Viewer, และริบบิ้น Search/Annotation ทางเลือก), การอ้างอิงทรัพยากร, การเริ่มต้นไคลเอนต์, การเปิดเอกสาร, และการดำเนินการ.

การตั้งค่าเซิร์ฟเวอร์

AddDoconut() ลงทะเบียนบริการ; UseDoconutResources() และ UseDoconut() เชื่อมต่อ middleware. การเรียกใช้ resources ต้องมาก่อน. UseDoconut() ตอบสนองทุกคำขอที่มาถึง, ดังนั้นให้เมานท์มันบนสาขาแยกของมันด้วย app.Map. การเรียกใช้ session จำเป็นเช่นกัน — ความปลอดภัยเอกสารเริ่มต้นของ Doconut ตรวจสอบทุกคำขอหน้าโดยอ้างอิงกับสถานะ session ของ ASP.NET. สถานะ session ต้องการแคช: 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 พึ่งพา session state ของ ASP.NET

app.UseSession();          // เรียก UseSession() ก่อน UseDoconut()
app.UseDoconutResources(); // ต้องลงทะเบียนก่อน UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());

สำหรับการจัดวางเส้นทางแบบ production, ให้แมป middleware ของเอกสารไปยังสาขาแบบชัดเจนและรักษาการตั้งค่าเส้นทางสี่ค่าให้สอดคล้องกัน:

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 ให้บริการ bundle ที่ฝังอยู่ที่ /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 เป็นการประกอบหน้าเดียว. Search และ Annotation จะฉีดริบบิ้นที่ฝังไว้ลงในการเมานท์ทางเลือก, แต่โมดูลเหล่านั้นไม่มีการทำงานแยกเดี่ยว: พวกมันจะผูกติดกับ 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 เป็นแฟล็กแกนบังคับ. อย่าเผยแพร่ตัวอย่าง Search หรือ Annotation Ribbon โดยไม่มีพวกมัน, การเมานท์ Viewer, และอินสแตนซ์ docViewer. ReferenceCss และ ReferenceScripts จะละเว้นทรัพยากรของโมดูลทางเลือกเมื่อใบอนุญาตปัจจุบันไม่ได้ให้สิทธิ์นั้น; Viewer แกนยังคงเริ่มทำงาน.

เริ่มต้น 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.
  • Callbacks เป็นตัวเลือก. 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, การเมานท์, และ 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, การเมานท์ Search/Annotation, และการเมานท์ Viewer พร้อมกัน.
  3. ส่งออกสคริปต์สำหรับ Viewer และโมดูลที่มีลิขสิทธิ์.
  4. โหลดสคริปต์ตัวช่วยแถบเครื่องมือของแอปพลิเคชันโฮสต์เอง.
  5. เริ่มต้น docViewer และเก็บ objViewer ที่ได้.
  6. เริ่มต้นริบบอน Search หรือ Annotation แต่ละโมดูลที่มีลิขสิทธิ์.
  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 ของริบบอนของตนเอง. Search มีกลุ่ม Find, Options, และ Results. Annotation มีเครื่องมือสร้าง, ควบคุมสไตล์, การบันทึก, และการส่งออก/รูปภาพที่เป็นตัวเลือก. แถบเหล่านี้เปิดเผย open(), close(), reset(), และ isOpen(); ควรเรียก attach(objViewer) หนึ่งครั้งหลังจากสร้างมัน.

ตัวอย่างข้างต้นละเว้นการเรียกกลับของโฮสต์ที่เป็นตัวเลือกและจุดสิ้นสุดการส่งออก/รูปภาพของ Annotation เพื่อให้การเริ่มต้นเป็นอย่างน้อยที่สุด. ดู การค้นหา และ คำอธิบาย สำหรับการตั้งค่าฟีเจอร์ที่สมบูรณ์, หรือ ธีมที่กำหนดเอง เพื่อสไตล์หรือแทนที่แถบเครื่องมือ 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) จะลบเซสชันที่แคชไว้ทันที, ปิดการทำงานของเอนจินการเรนเดอร์, ลบเครื่องหมายความปลอดภัยของมัน, และเพิกถอนโทเค็น. การหมดอายุแบบเลื่อนจะทำความสะอาดเดียวกันในที่สุด, แต่การปิดอย่างชัดเจนแนะนำสำหรับเอกสารขนาดใหญ่.

ขั้นตอนการร้องขอที่สมบูรณ์คือ:

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 ค้นหาใบอนุญาตอย่างไรและจะมีการเปลี่ยนแปลงอะไรบ้างเมื่อพบแล้ว.

หน้านี้เป็นประโยชน์หรือไม่?