เริ่มต้นอย่างเร็ว
แสดงเอกสารแรกของคุณในไม่กี่นาที
บทนำนี้จะพาแอป 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 ไว้แล้วในระหว่าง การติดตั้ง? ข้ามไปยังส่วนถัดไป.
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(); // เรียก UseSession() ก่อน UseDoconut()
app.UseDoconutResources(); // ต้องลงทะเบียนก่อน UseDoconut()
app.Map("/doconut", branch => branch.UseDoconut());สำหรับการจัดวางเส้นทางแบบ production, ให้แมป middleware ของเอกสารไปยังสาขาเฉพาะและรักษาการตั้งค่าเส้นทางสี่ค่าให้สอดคล้องกัน:
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 จะล้มเหลวด้วยข้อความ "ตัวจัดการ viewer ไม่สามารถเข้าถึงได้".
เพิ่ม viewer ไปยังหน้า
Viewer เป็นแกนหลักที่จำเป็นของหน้า. พื้นผิวการเรนเดอร์ของมันใช้ div สองชั้นซ้อนกัน:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>พิจารณาแถบเครื่องมือ, การเมานท์โมดูล, และพื้นผิว Viewer เป็นส่วนประกอบของหน้าเดียวกัน. Search และ Annotation จะฉีดริบบิ้นที่ฝังไว้ของพวกเขาเข้าสู่การเมานท์ทางเลือก, แต่โมดูลเหล่านั้นไม่มีการทำงานแยก: พวกมันจะผูกติดกับ Viewer บนหน้าเดียวกันเสมอ. ใช้ลำดับนี้:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- ปุ่มการนำทาง, ซูม, Search, และ Annotation ของ 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:
@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.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 ตัวนี้เป็นชุดตัวเลือกการเริ่มต้นที่แท้จริงขั้นต่ำ (ไม่ใช่โค้ดจำลอง):
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(...). ฟังก์ชันระดับโลกที่ตั้งชื่อตาม viewer เช่นctlDoc_ViewerReadyจะไม่มีการเรียกใช้. - คงไว้ Viewer แล้วเรียก
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 ตัวเดียวกัน:
<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"> ของมัน.
รักษาลำดับการเริ่มต้นนี้:
- สร้าง CSS สำหรับ Viewer และโมดูลที่มีลิขสิทธิ์.
- เรนเดอร์แถบเครื่องมือ Viewer, การเมานท์ Search/Annotation, และการเมานท์ Viewer พร้อมกัน.
- สร้างสคริปต์สำหรับ Viewer และโมดูลที่มีลิขสิทธิ์.
- โหลดสคริปต์ช่วยเหลือแถบเครื่องมือของแอปพลิเคชันโฮสต์.
- เริ่มต้น
docViewerและเก็บobjViewerที่ได้. - เริ่มต้นริบบิ้น Search หรือ Annotation ที่มีลิขสิทธิ์แต่ละอัน.
- เรียก
attach(objViewer)บนทุกริบบิ้น. - เปิดเอกสารและเก็บโทเคนของมันสำหรับการร้องขอของ Viewer และโมดูล.
ในการปรับใช้แบบกระจาย, ค่า access ที่เพิ่มเข้ามาและการตั้งค่าการลองใหม่แบบเรนเดอร์แบบอะซิงโครนัสเป็นของการส่งข้อมูล; พวกมันไม่เปลี่ยนแปลงวิธีการประกอบ Viewer, แถบเครื่องมือ, หรือริบบิ้น.
การป้องกันฝั่งเซิร์ฟเวอร์เป็นสิ่งสำคัญ: เมื่อความสามารถตัวเลือกไม่พร้อมใช้งาน, สคริปต์ของมันจะไม่ถูกสร้าง, ดังนั้นฟังก์ชันปลั๊กอิน jQuery ของมันจะไม่มีอยู่.
<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 ที่ฉีดเข้ามาเปิดเอกสารและคืนค่าโทเคนเซสชัน.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// โทเคนเป็นแบบไม่เปิดเผย — ส่งให้ widget, อย่า log หรือ persist มัน.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});ไคลเอนต์ดึงโทเคนนั้นและส่งให้วิดเจ็ตด้วย objViewer.View(token):
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) จะลบเซสชันที่แคชไว้ทันที, ทำลายเอนจินการเรนเดอร์, ลบเครื่องหมายความปลอดภัยของมัน, และเพิกถอนโทเคน. การหมดอายุแบบเลื่อนจะทำความสะอาดเช่นเดียวกันในที่สุด, แต่การปิดอย่างชัดเจนแนะนำสำหรับเอกสารขนาดใหญ่.
ขั้นตอนการร้องขอที่สมบูรณ์คือ:
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 ค้นหาใบอนุญาตอย่างไรและจะมีการเปลี่ยนแปลงอะไรเมื่อพบ.
หน้านี้เป็นประโยชน์หรือไม่?