Trình xem Doconut là một thư viện .NET để xem tài liệu, được thiết kế để nhúng PDF, Office, CAD, hình ảnh và các loại tài liệu hỗ trợ khác vào trong một ứng dụng. Một tích hợp Doconut hiệu quả không chỉ là tìm đoạn mã ngắn nhất mà còn là việc chọn một ranh giới rõ ràng giữa ứng dụng của bạn, trình xem và trình duyệt.
Trung tâm tài liệu Doconut cung cấp các đường dẫn thiết lập được duy trì cho các loại dự án .NET được hỗ trợ. Hãy sử dụng hướng dẫn phù hợp với phiên bản đã cài đặt trong ứng dụng của bạn, sau đó coi trang bao quanh, các kiểm tra danh tính và quy trình truy cập như mã ứng dụng mà đội ngũ của bạn sở hữu.
Bắt đầu với Ranh giới Tích hợp
Có ba cách phổ biến để đặt bản xem trước tài liệu trong một sản phẩm. Lựa chọn phù hợp phụ thuộc vào người chịu trách nhiệm điều hướng, xác thực và vòng đời của trình xem.
| Mẫu | Phù hợp nhất | Thương vụ chính |
|---|---|---|
| Giao diện ứng dụng | Một trang .NET hiển thị trình xem bên cạnh các điều khiển của sản phẩm | Tích hợp chặt chẽ, nhưng trang và vòng đời trình xem bị gắn kết |
| Iframe do ứng dụng sở hữu | Một cổng cần cách ly giữa giao diện người dùng chủ và đường dẫn xem trước | Ranh giới rõ ràng, nhưng giao tiếp phải được thiết kế một cách rõ ràng |
| Thành phần khung quanh một route máy chủ | Một shell React, Angular hoặc Vue được hỗ trợ bởi một ứng dụng .NET | Cấu trúc front-end quen thuộc, với nhiều trạng thái vòng đời hơn để quản lý |
Mẫu iframe không nhất thiết phải trỏ tới một URL tài liệu công cộng. Nó có thể trỏ tới một route đã xác thực trong ứng dụng của bạn. Route đó có thể kiểm tra quyền truy cập và hiển thị trang trình xem mà không tiết lộ đường dẫn lưu trữ cho trang chủ.
Xây dựng Bề mặt Xem trước Ổn định và Đáp ứng
Không tái tạo lại markup hoặc khởi tạo của trình xem từ một đoạn mã mẫu trong blog. Doconut cung cấp các tệp, bước middleware, không gian tên và thiết lập trình xem phù hợp cho mỗi dòng .NET được hỗ trợ. Ví dụ, hướng dẫn thiết lập chính thức cho .NET 6 hoặc cao hơn giải thích middleware máy chủ, đối tượng trình xem, tùy chọn tài liệu, cấu hình render và các tài sản client cần thiết.
Sử dụng các tài liệu có phiên bản đó để tạo trình xem, sau đó cung cấp cho vùng chứa một chiều rộng và chiều cao ổn định trong bố cục của bạn. Dành đủ không gian trước khi tải để trang bao quanh không bị nhảy, và kiểm tra thanh công cụ cùng trang đầu tiên ở các điểm ngắt thực tế mà sản phẩm của bạn hỗ trợ.
Trước khi quyết định cấu trúc, hãy so sánh nó với các bản demo trực tiếp của Doconut chính thức. Các bản demo bao gồm nhiều kiểu tích hợp .NET và front-end, bao gồm một ví dụ iframe riêng, và giúp phân biệt đường dẫn được hỗ trợ chính thức với một đoạn mã trông hợp lý.
Giữ Quyết định Truy cập trên Máy chủ
Trang host không bao giờ nên quyết định người dùng có thể xem tài liệu hay không. Trước khi render route xem trước, ứng dụng nên:
- Xác thực yêu cầu.
- Ủy quyền người dùng cho tài liệu và tenant được yêu cầu.
- Xác định tài liệu thông qua một định danh do máy chủ kiểm soát.
- Mở tài liệu qua trình xem chỉ sau khi các kiểm tra trên thành công.
- Trả về trạng thái không tìm thấy hoặc bị cấm chung mà không lộ chi tiết lưu trữ.
Một định danh mờ giúp cải thiện tính sạch sẽ của URL, nhưng nó không phải là ủy quyền. Áp dụng các kiểm tra tương tự cho các yêu cầu trang, hình thu nhỏ, tìm kiếm, chú thích, xuất và in mà bạn cung cấp.
Quyết định Cách Host và Trình xem Giao tiếp
Giao diện ứng dụng có thể gọi các thành phần của mình trực tiếp. Iframe cần một hợp đồng hẹp hơn. Định nghĩa chỉ những sự kiện mà host thực sự cần, chẳng hạn:
- Xem trước sẵn sàng
- Tài liệu không mở được
- Trang hiện tại đã thay đổi
- Phiên đã hết hạn
- Người dùng yêu cầu đóng xem trước
Nếu bạn sử dụng postMessage, hãy xác thực cả event.origin và cấu trúc tin nhắn. Không chấp nhận nguồn gốc wildcard trong môi trường sản xuất, và không bao giờ truyền thông tin đăng nhập, vị trí lưu trữ hoặc nội dung tài liệu thô qua tin nhắn.
Xem Các Hạn chế Trình duyệt như Một Lớp Bảo vệ Sâu
Iframe không tự động được cô lập. Thuộc tính sandbox có thể giảm khả năng, nhưng giá trị quá nghiêm ngặt cũng có thể làm hỏng script của trình xem, tải xuống hoặc hành vi cùng nguồn. Bắt đầu từ bộ khả năng nhỏ nhất được tài liệu cho tích hợp của bạn và kiểm tra nó với Chính sách Bảo mật Nội dung (CSP) của bạn.
Cũng hãy xem xét:
frame-ancestorshoặcX-Frame-Optionscho route xem trướcframe-srccho trang host- Hành vi cookie cùng site nếu iframe yêu cầu một phiên
- Chính sách Referrer cho các URL chứa định danh định tuyến
- Tiêu đề cache cho các trang hiển thị nội dung nhạy cảm
Các kiểm soát này thuộc về ứng dụng và hạ tầng bao quanh. Thành phần trình xem không thể tự chọn chính sách phù hợp cho tenancy và mô hình đe dọa của bạn.
Thiết kế Trạng thái Tải, Lỗi và Hết hạn
Một hình chữ nhật trống không phải là thông báo lỗi hữu ích. Cung cấp cho trang host các trạng thái rõ ràng cho lỗi ủy quyền, đầu vào không hỗ trợ, tệp hỏng, thời gian chờ và phiên hết hạn. Giữ ngôn ngữ có tính hành động mà không lộ đường dẫn nội bộ hoặc chi tiết ngoại lệ.
Đối với tài liệu dài, giữ nguyên container của trình xem trong khi trang đầu tiên đang được chuẩn bị. Nếu người dùng có thể chuyển đổi tài liệu mà không rời trang, hãy hủy các yêu cầu cũ và đặt lại tiêu đề hiển thị, số trang và tiêu điểm trước khi tải mục tiếp theo.
Khả năng Truy cập và Hành vi Bàn phím
Cung cấp cho mỗi iframe một title hữu ích. Đảm bảo bản xem trước có thể truy cập bằng bàn phím, cung cấp cách hiển thị để trả lại tiêu điểm cho trang host, và không kẹt tiêu điểm trong các lớp phủ tùy chỉnh. Nếu trình xem có các phím tắt riêng, hãy ghi lại các xung đột với phím tắt được sử dụng bởi shell sản phẩm của bạn.
Một phương án dự phòng khả năng truy cập có thể cung cấp tải xuống có kiểm soát hoặc một biểu diễn thay thế khi quy tắc kinh doanh của bạn cho phép. Không thêm liên kết tệp công cộng chỉ để làm dự phòng.
Danh sách Kiểm tra Xác minh Thực tế
Trước khi phát hành, hãy xác minh toàn bộ đường dẫn yêu cầu thay vì chỉ tải trang ban đầu:
- Người dùng được ủy quyền có thể mở tài liệu được cho phép.
- Người dùng từ tenant khác không thể tái sử dụng URL xem trước.
- Các yêu cầu trực tiếp tới các endpoint liên quan đến trình xem nhận được cùng các kiểm tra ủy quyền.
- Làm mới, điều hướng quay lại và hết hạn phiên tạo ra các trạng thái dễ hiểu.
- Bản xem trước vẫn sử dụng được ở các kích thước viewport và mức thu phóng được hỗ trợ.
- Lỗi console trình duyệt và các yêu cầu mạng thất bại được hiển thị trong giám sát.
- Log lưu trữ và ứng dụng không ghi lại bí mật hoặc URL tài liệu đầy đủ.
Kết luận
Cách nhúng Doconut dễ bảo trì nhất là cách có hợp đồng nhỏ, rõ ràng. Hãy để Doconut xử lý vai trò xem tài liệu như mô tả trong tài liệu có phiên bản của nó, trong khi ứng dụng của bạn sở hữu danh tính, ủy quyền, định tuyến, lưu trữ, chính sách trình duyệt và phản hồi người dùng. Khi bạn sẵn sàng đánh giá các ví dụ đã đóng gói cục bộ, hãy sử dụng tài nguyên tải xuống của Doconut chính thức thay vì sao chép mã nguồn từ một bài viết không liên quan.