Giới thiệu

Tải lên và quản lý tệp trong lưu trữ đám mây với tối ưu hóa tự động.

🎯 Mô-đun này làm gì?

Mô-đun FileUploading cho phép bạn tải lên, truy xuất và xóa tệp trong lưu trữ đám mây OneEntry - hình ảnh, PDF, video, tài liệu và bất kỳ loại tệp nào với tối ưu hóa tự động và phân phối CDN.

Hãy coi nó như là trình quản lý lưu trữ đám mây của bạn - bạn chỉ cần tải lên tệp một lần, và OneEntry sẽ lưu trữ, tự động tối ưu hóa hình ảnh và phục vụ chúng nhanh chóng qua CDN.

📖 Giải thích đơn giản

Hãy tưởng tượng bạn đang xây dựng một ứng dụng nơi người dùng có thể:

📸 Tải lên ảnh đại diện - tự động thay đổi kích thước và tối ưu hóa
📄 Tải lên tài liệu - lưu trữ PDF, DOC một cách an toàn
🖼️ Tải lên hình ảnh sản phẩm - nhiều hình ảnh cho mỗi sản phẩm
🎥 Tải lên video - lưu trữ và phát trực tuyến nội dung video
📎 Tải lên tệp đính kèm - bất kỳ loại tệp nào

Thay vì quản lý lưu trữ của riêng bạn:

✅ Tải tệp lên đám mây OneEntry
✅ Tối ưu hóa hình ảnh tự động (thay đổi kích thước, nén)
✅ Phân phối CDN nhanh chóng trên toàn cầu
✅ Tổ chức theo loại thực thể (sản phẩm, người dùng, trang)
✅ Nhận URL tải xuống ngay lập tức
✅ Xóa tệp khi không còn cần thiết

Ví dụ thực tế:

Không có FileUploading (thủ công):
- Thiết lập bucket AWS S3 ❌
- Cấu hình CDN ❌
- Viết mã tối ưu hóa hình ảnh ❌
- Quản lý quyền tệp ❌
- Tạo URL ký ❌

Với FileUploading (tự động):
- Tải lên tệp → Nhận URL tải xuống ✅
- Hình ảnh được tối ưu hóa tự động ✅
- Phân phối CDN tích hợp ✅
- Quản lý tệp dễ dàng ✅

✨ Khái niệm chính

Tải lên tệp là gì?

Tải lên tệp là lưu trữ tệp trong lưu trữ đám mây:

Tải lên - Gửi tệp đến đám mây OneEntry
Lưu trữ - Tệp được lưu trữ an toàn trong đám mây
CDN - Phân phối nhanh từ các máy chủ gần người dùng
Tối ưu hóa - Hình ảnh được nén và thay đổi kích thước tự động
URL - Nhận liên kết tải xuống vĩnh viễn

Các loại tệp được hỗ trợ

Tải lên bất kỳ loại tệp nào:

Danh mục	Các loại tệp	Tối ưu hóa tự động
Hình ảnh	JPG, PNG, GIF, WebP, SVG	Có (thay đổi kích thước, nén)
Tài liệu	PDF, DOC, DOCX, XLS, XLSX	Không (lưu trữ nguyên trạng)
Video	MP4, MOV, AVI, WebM	Không (lưu trữ nguyên trạng)
Tệp nén	ZIP, RAR, TAR, GZ	Không (lưu trữ nguyên trạng)
Khác	Bất kỳ loại tệp nào	Không (lưu trữ nguyên trạng)

Tối ưu hóa hình ảnh

Khi tải lên hình ảnh, OneEntry có thể:

📐 Thay đổi kích thước - Giảm kích thước (ví dụ: tối đa 1920px chiều rộng)
🗜️ Nén - Giảm kích thước tệp (nhỏ hơn, nhanh hơn)
🖼️ Định dạng - Chuyển đổi sang định dạng tối ưu (WebP)
📱 Phản hồi - Tạo nhiều kích thước

Ví dụ:

Gốc: 5MB, 4000x3000px
↓ (tối ưu hóa tự động)
Tối ưu hóa: 200KB, 1920x1440px

📋 Những điều bạn cần biết

Tham số tải lên

Khi tải lên tệp, bạn có thể chỉ định:

await FileUploading.upload(file, {
  entity: 'product',     // Loại thực thể (bắt buộc)
  id: 123,               // ID thực thể (tùy chọn)
  type: 'image',         // Gợi ý loại tệp (tùy chọn)
  width: 1920,           // Chiều rộng tối đa cho hình ảnh (tùy chọn)
  height: 1080,          // Chiều cao tối đa cho hình ảnh (tùy chọn)
  compress: true         // Nén hình ảnh (tùy chọn)
});

Giải thích các tham số:

file - Đối tượng tệp (từ input hoặc kéo-thả)
entity - Danh mục: product, page, block, user, form, general
id - ID thực thể để liên kết tệp (ví dụ: ID sản phẩm)
type - Gợi ý loại tệp (thường được phát hiện tự động)
width - Chiều rộng tối đa tính bằng pixel (chỉ hình ảnh)
height - Chiều cao tối đa tính bằng pixel (chỉ hình ảnh)
compress - Bật nén (chỉ hình ảnh)

Phản hồi tải lên

Sau khi tải lên, bạn sẽ nhận được:

{
  filename: "abc123-photo.jpg",              // Tên tệp duy nhất
  downloadLink: "https://cdn.../photo.jpg",  // URL CDN
  size: 204800,                              // Kích thước tệp (byte)
}

Các trường quan trọng:

downloadLink - Sử dụng URL này trong các thẻ <img>, <a>, <video>
filename - Lưu lại để xóa tệp sau này
size - Kích thước tệp tính bằng byte (204800 byte = 200KB)

Thực hành tốt nhất về tổ chức tệp

Tổ chức tệp theo loại thực thể

Tùy chọn tối ưu hóa hình ảnh

Kiểm soát cách hình ảnh được tối ưu hóa:

Tùy chọn	Chức năng	Ví dụ
width	Chiều rộng tối đa (giữ tỷ lệ khung hình)	`width: 1920`
height	Chiều cao tối đa (giữ tỷ lệ khung hình)	`height: 1080`
compress	Giảm kích thước tệp	`compress: true`

Tỷ lệ khung hình được bảo toàn:

Gốc: 4000x3000 (tỷ lệ 4:3)
Với chiều rộng: 800
Kết quả: 800x600 (vẫn tỷ lệ 4:3)

Xóa tệp

Luôn cung cấp thực thể, id và tên tệp để xóa:

await FileUploading.delete({
  entity: 'product',
  id: productId,
  filename: 'abc123-photo.jpg'
});

Tại sao cần cả ba? Tệp được tổ chức theo thực thể → id → tên tệp.

📊 Bảng tham khảo nhanh - Phương thức

Phương thức	Chức năng	Khi nào sử dụng
upload()	Tải tệp lên lưu trữ đám mây	Người dùng tải lên hình ảnh, tài liệu
getFile()	Nhận thông tin tệp (kích thước, loại, URL)	Kiểm tra xem tệp có tồn tại không
delete()	Xóa tệp khỏi lưu trữ	Xóa các tệp cũ

❓ Câu hỏi thường gặp (FAQ)

Tôi có thể tải lên loại tệp nào?

Bất kỳ loại tệp nào đều được hỗ trợ:

Hình ảnh: JPG, PNG, GIF, WebP, SVG, BMP, TIFF
Tài liệu: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT
Video: MP4, MOV, AVI, WebM, MKV
Tệp nén: ZIP, RAR, TAR, GZ
Khác: Bất kỳ loại tệp nào

Chỉ hình ảnh là được tối ưu hóa tự động. Các tệp khác được lưu trữ nguyên trạng.

Kích thước tệp tối đa là bao nhiêu?

Kiểm tra giới hạn kế hoạch OneEntry của bạn. Thông thường:

Kế hoạch miễn phí: 5MB mỗi tệp
Kế hoạch trả phí: 50MB - 100MB mỗi tệp

Thực hành tốt nhất: Tối ưu hóa hình ảnh trước khi tải lên để giảm kích thước.

Các tệp có được lưu trữ vĩnh viễn không?

Có, các tệp được lưu trữ cho đến khi bạn xóa chúng thủ công bằng FileUploading.delete().

Quan trọng: Dọn dẹp các tệp không sử dụng để tiết kiệm không gian lưu trữ.

Tôi có thể tải lên tệp từ frontend (trình duyệt) không?

Có! Sử dụng input tệp hoặc kéo & thả.

Làm thế nào để tôi xác thực tệp trước khi tải lên?

Kiểm tra loại tệp và kích thước.

Tôi có thể nhận danh sách tất cả các tệp đã tải lên cho một thực thể không?

Không trực tiếp với SDK này. Bạn cần:

Theo dõi tên tệp khi tải lên (lưu vào cơ sở dữ liệu)
Sử dụng OneEntry Admin API để liệt kê các tệp

Thực hành tốt nhất: Lưu tên tệp đã tải lên trong cơ sở dữ liệu của bạn.

Làm thế nào để tôi xử lý lỗi tải lên?

Luôn sử dụng try/catch.

Tôi có thể tải lên tệp trực tiếp đến CDN không?

Không, các tệp tải lên phải qua API OneEntry, mà:

Xác thực tệp
Tối ưu hóa hình ảnh (nếu được bật)
Lưu trữ trong đám mây
Trả về URL CDN

Điều này đảm bảo an ninh và tối ưu hóa.

Điều gì xảy ra với các tệp nếu tôi xóa một thực thể (sản phẩm, người dùng)?

Các tệp vẫn ở lại trong lưu trữ ngay cả khi thực thể bị xóa.

Thực hành tốt nhất: Xóa các tệp trước khi xóa thực thể.

Tôi có thể thay đổi kích thước hình ảnh đến kích thước chính xác không?

Không, tỷ lệ khung hình luôn được bảo toàn để tránh biến dạng.

Cách hoạt động:

Bạn đặt width: 800, height: 600
Hình ảnh được thay đổi kích thước để vừa trong 800x600
Tỷ lệ khung hình được bảo toàn

Ví dụ:

Gốc: 1000x500 (tỷ lệ 2:1)
Với chiều rộng: 800, chiều cao: 600
Kết quả: 800x400 (vẫn tỷ lệ 2:1, vừa trong 800x600)

💡 Ghi chú quan trọng

Bảo mật tệp

Các tệp đã tải lên có thể truy cập công khai qua CDN:

✅ Tuyệt vời cho hình ảnh, tài liệu công khai
⚠️ Không tải lên các tệp nhạy cảm (mật khẩu, dữ liệu riêng tư)

Đối với các tệp riêng tư:

Sử dụng OneEntry Admin API với xác thực
Hoặc triển khai kiểm soát truy cập của riêng bạn

Giới hạn lưu trữ

Theo dõi việc sử dụng lưu trữ của bạn:

Mỗi kế hoạch có giới hạn lưu trữ
Dọn dẹp các tệp không sử dụng thường xuyên
Nén hình ảnh trước khi tải lên

Mẹo tối ưu hóa hình ảnh

Để có kết quả tốt nhất:

✅ Tải lên các bản gốc chất lượng cao (để OneEntry tối ưu hóa)
✅ Sử dụng compress: true cho hình ảnh web
✅ Đặt kích thước phù hợp (ví dụ: 1920px cho hình ảnh chính, 500px cho hình thu nhỏ)
❌ Không tải lên các hình ảnh đã nén (mất chất lượng)

Kích thước được khuyến nghị:

Ảnh đại diện: 500x500
Hình ảnh sản phẩm: 1920x1920
Biểu ngữ chính: 1920x1080
Hình thu nhỏ: 300x300

🎓 Thực hành tốt nhất

Xác thực loại tệp và kích thước trước khi tải lên
Liên kết các tệp với ID thực thể để tổ chức
Bật nén cho hình ảnh web
Xử lý lỗi tải lên một cách nhẹ nhàng
Lưu tên tệp để xóa tệp sau này
Dọn dẹp các tệp không sử dụng thường xuyên
Hiển thị tiến trình tải lên cho người dùng

Định nghĩa của mô-đun FileUploading


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Tài liệu liên quan

Mô-đun Sản phẩm - Tải lên hình ảnh sản phẩm
Mô-đun Người dùng - Tải lên ảnh đại diện người dùng
Mô-đun Trang - Tải lên tệp nội dung trang
Mô-đun Khối - Tải lên tệp nội dung khối

Giới thiệu

🎯 Mô-đun này làm gì?​

📖 Giải thích đơn giản​

✨ Khái niệm chính​

Tải lên tệp là gì?​

Các loại tệp được hỗ trợ​

Tối ưu hóa hình ảnh​

📋 Những điều bạn cần biết​

Tham số tải lên​

Phản hồi tải lên​

Thực hành tốt nhất về tổ chức tệp​

Tùy chọn tối ưu hóa hình ảnh​

Xóa tệp​

📊 Bảng tham khảo nhanh - Phương thức​

❓ Câu hỏi thường gặp (FAQ)​

Tôi có thể tải lên loại tệp nào?​

Kích thước tệp tối đa là bao nhiêu?​

Các tệp có được lưu trữ vĩnh viễn không?​

Tôi có thể tải lên tệp từ frontend (trình duyệt) không?​

Làm thế nào để tôi xác thực tệp trước khi tải lên?​

Tôi có thể nhận danh sách tất cả các tệp đã tải lên cho một thực thể không?​

Làm thế nào để tôi xử lý lỗi tải lên?​

Tôi có thể tải lên tệp trực tiếp đến CDN không?​

Điều gì xảy ra với các tệp nếu tôi xóa một thực thể (sản phẩm, người dùng)?​

Tôi có thể thay đổi kích thước hình ảnh đến kích thước chính xác không?​

💡 Ghi chú quan trọng​

Bảo mật tệp​

Giới hạn lưu trữ​

Mẹo tối ưu hóa hình ảnh​

🎓 Thực hành tốt nhất​

Định nghĩa của mô-đun FileUploading​

🔗 Tài liệu liên quan​