Nhảy đến nội dung

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ế:

Without FileUploading (manual):
- Set up AWS S3 bucket ❌
- Configure CDN ❌
- Write image optimization code ❌
- Manage file permissions ❌
- Generate signed URLs ❌

With FileUploading (automatic):
- Upload file → Get download URL ✅
- Images auto-optimized ✅
- CDN delivery built-in ✅
- Easy file management ✅

✨ 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 tự động nén và thay đổi kích thước
  • 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ụcCác loại tệpTối ưu hóa tự động
Hình ảnhJPG, PNG, GIF, WebP, SVGCó (thay đổi kích thước, nén)
Tài liệuPDF, DOC, DOCX, XLS, XLSXKhông (lưu trữ nguyên trạng)
VideoMP4, MOV, AVI, WebMKhông (lưu trữ nguyên trạng)
Tệp nénZIP, RAR, TAR, GZKhông (lưu trữ nguyên trạng)
KhácBất kỳ loại tệp nàoKhô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ụ:

Original: 5MB, 4000x3000px
↓ (auto-optimize)
Optimized: 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',     // Entity type (required)
  id: 123,               // Entity ID (optional)
  type: 'image',         // File type hint (optional)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true         // Compress images (optional)
});

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 nhận được:

{
  filename: "abc123-photo.jpg",              // Unique filename
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size (bytes)
}

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
  • 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ọnChức năngVí dụ
widthChiều rộng tối đa (giữ tỷ lệ khung hình)width: 1920
heightChiều cao tối đa (giữ tỷ lệ khung hình)height: 1080
compressGiảm kích thước tệpcompress: true

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

Original: 4000x3000 (4:3 ratio)
With width: 800
Result: 800x600 (still 4:3 ratio)

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ứcChức năngKhi nào sử dụng
upload()Tải tệp lên lưu trữ đám mâyNgười dùng tải lên hình ảnh, tài liệu
getFile()Lấy 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ỉ có 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ể lấy 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:

  1. Theo dõi tên tệp khi tải lên (lưu vào cơ sở dữ liệu)
  2. 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à:

  1. Xác thực tệp
  2. Tối ưu hóa hình ảnh (nếu được bật)
  3. Lưu trữ trong đám mây
  4. 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 ở 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ụ:

Original: 1000x500 (2:1 ratio)
With width: 800, height: 600
Result: 800x400 (still 2:1 ratio, fits within 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 hero, 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ữ hero: 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
  • 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​