Cài đặt và sử dụng — File Previewer Office

Tổng quan

Plugin plugin-file-previewer-office cho phép xem trước file Office (Word, Excel, PowerPoint) trực tiếp trong trình duyệt mà không cần tải về hay cài phần mềm Office. Plugin sử dụng dịch vụ Microsoft Office Online Viewer (view.officeapps.live.com) để render file.

Yêu cầu

Thành phần	Yêu cầu
Server Digiforce	Phiên bản >= 1.0
Plugin phụ thuộc	`plugin-file-manager` (quản lý file đính kèm)
Mạng	File phải truy cập được từ internet (Microsoft cần đọc file qua URL)

Điều kiện quan trọng

Plugin sử dụng Microsoft Office Online Viewer để render. Điều này yêu cầu:

File phải có URL public (truy cập được từ internet, không cần xác thực)
Server không nằm sau firewall chặn outbound (cần gọi đến view.officeapps.live.com)

Bước 1: Kích hoạt plugin

Truy cập Settings → Plugin Manager
Tìm plugin-file-previewer-office
Bật công tắc Enable

Plugin chủ yếu hoạt động phía client — đăng ký thêm file type handler vào hệ thống preview. Server-side là plugin rỗng (không thêm API hay collection).

Bước 2: Sử dụng

Sau khi kích hoạt, khi user nhấn vào file Office trong trường attachment, hệ thống sẽ:

Phát hiện loại file dựa trên MIME type hoặc extension
Mở modal preview với iframe trỏ đến Microsoft Office Online Viewer
Hiển thị nội dung file với các nút hành động

Nút	Mô tả
Open in new window	Mở preview trong tab mới
Download	Tải file gốc về máy
Close	Đóng modal preview

Định dạng file được hỗ trợ

Theo MIME Type

MIME Type	Loại file
`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	Word (.docx)
`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	Excel (.xlsx)
`application/vnd.openxmlformats-officedocument.presentationml.presentation`	PowerPoint (.pptx)
`application/msword`	Word cũ (.doc)
`application/vnd.ms-excel`	Excel cũ (.xls)
`application/vnd.ms-powerpoint`	PowerPoint cũ (.ppt)
`application/vnd.oasis.opendocument.text`	OpenDocument Text (.odt)

Theo Extension

Extension	Loại file
`.docx`, `.doc`	Microsoft Word
`.xlsx`, `.xls`	Microsoft Excel
`.pptx`, `.ppt`	Microsoft PowerPoint
`.odt`	OpenDocument Text

Cơ chế hoạt động chi tiết

Xây dựng Preview URL

Plugin tạo URL preview theo format:

https://view.officeapps.live.com/op/embed.aspx?src=<encoded-file-url>

Trong đó <encoded-file-url> là URL đầy đủ của file đã được encode.

Xác định URL file

Plugin xử lý URL file theo logic:

Nếu URL bắt đầu bằng http:// hoặc https:// → sử dụng trực tiếp
Nếu URL là đường dẫn tương đối → thêm location.origin phía trước

Phát hiện loại file

Plugin kiểm tra theo thứ tự:

MIME type: Nếu file có mimetype thuộc danh sách Office MIME types → là file Office
Extension: Lấy extension từ extname, name, filename hoặc url → kiểm tra trong danh sách Office extensions

Hai chế độ Preview

Khi user nhấn vào file attachment trong danh sách:

Mở modal kích thước 85% viewport (85vw × 85vh)
Iframe load Microsoft Office Online Viewer
Hỗ trợ chuyển đổi giữa nhiều file (navigation)

Inline Previewer

Khi file được hiển thị trong chế độ inline preview:

Render trực tiếp iframe trong container
Kích thước 100% × 100% của container cha
Không có modal wrapper

Cấu hình Storage cho Preview

Để preview hoạt động, file phải có URL truy cập được từ internet:

Storage Type	Preview hoạt động?	Ghi chú
S3 (public bucket)	Có	URL trực tiếp từ S3
Ali OSS (public)	Có	URL trực tiếp từ OSS
Tencent COS (public)	Có	URL trực tiếp từ COS
MinIO (public)	Có	URL từ MinIO với public access
Local storage	Chỉ nếu public	Server phải expose URL ra internet
Private storage	Không	Microsoft không thể đọc file cần xác thực

Giải pháp cho storage private

Nếu dùng private storage, có thể:

Tạo pre-signed URL (S3, OSS hỗ trợ) trước khi gửi cho viewer
Hoặc sử dụng self-hosted viewer (LibreOffice Online, OnlyOffice) thay vì Microsoft

Lưu ý

Plugin không convert file trên server — chỉ redirect đến Microsoft Office Online Viewer
File .doc, .xls, .ppt (định dạng cũ) có thể hiển thị không hoàn hảo — khuyến nghị dùng .docx, .xlsx, .pptx
File lớn có thể tải chậm vì Microsoft cần download và render
Microsoft Office Online Viewer miễn phí nhưng có giới hạn kích thước file
Dữ liệu file được gửi qua Microsoft servers — cân nhắc bảo mật cho file nhạy cảm