Chuyển đến nội dung chính

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.

Thêm thông tin về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/attributes/types/#File

🎯 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, bất kỳ loại tệp nào - với tối ưu hóa hình ảnh tự động và phân phối qua 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.

🚀 Bắt đầu nhanh​

Khởi tạo mô-đun từ defineOneEntry:


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

Tải lên một tệp và đọc liên kết tải xuống được trả về:

// upload() returns an ARRAY of uploaded files (IUploadingReturn[]).
const uploaded = await FileUploading.upload(file, {
  entity: "product",
  id: 123,
  type: "image",
  compress: true,
});

const { filename, downloadLink, size } = uploaded[0];
console.log(downloadLink); // use in <img>, <a>, <video>

Sau đó, xóa nó bằng tên tệp (thực thể/id xác định thư mục lưu trữ):

await FileUploading.delete(filename, { entity: "product", id: 123 });

✨ 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 và nhận lại một liên kết CDN vĩnh viễn:

  • Tải lên - gửi một File hoặc Blob đến đám mây OneEntry
  • Lưu trữ - các tệp được lưu trữ, tổ chức theo entity → id → filename
  • 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ó thể được nén và thay đổi kích thước tự động
  • URL - downloadLink trong phản hồi là liên kết vĩnh viễn

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

Bất kỳ loại tệp nào cũng được chấp nhận. Chỉ có hình ảnh là được tối ưu hóa tự động; mọi thứ khác được lưu trữ nguyên trạng.

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)

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

Tham số tải lên​

upload(file, fileQuery?) nhận tệp cùng với một đối tượng truy vấn tùy chọn:

await FileUploading.upload(file, {
  entity: 'product',     // Storage folder name (optional, any string)
  id: 123,               // Entity ID (optional)
  type: 'image',         // Folder/type hint (optional, any string)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true,        // Compress images (optional)
});
  • file — File hoặc Blob để tải lên (từ một đầu vào hoặc kéo-thả)
  • entity — tên thư mục tự do trong lưu trữ (ví dụ: product, page, user, editor — ví dụ, không phải là enum cố định)
  • id — ID thực thể để liên kết tệp
  • type — chuỗi gợi ý thư mục/loại tự do
  • width / height — kích thước tối đa cho hình ảnh (tỷ lệ khung hình được bảo toàn)
  • compress — kích hoạt nén hình ảnh

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

upload() trả về một mảng của IUploadingReturn. Mỗi mục có:

{
  filename: "uploads/abc123-photo.jpg",      // Filename with relative path
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size in bytes
  contentType: "image/png",                  // MIME type
}
  • downloadLink — sử dụng URL này trong các thẻ <img>, <a>, <video>
  • filename — lưu nó để xóa tệp sau này
  • size — kích thước tệp tính bằng byte

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

Đối với hình ảnh, bạn có thể truyền width, height, và compress. Tỷ lệ khung hình luôn được bảo toàn — hình ảnh được thay đổi kích thước để phù hợp trong các giới hạn đã cho, không bao giờ bị kéo giãn.

Xóa tệp​

Truyền tên tệp trước tiên; thực thể/id/type nằm trong đối tượng truy vấn tùy chọn xác định thư mục lưu trữ:

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

Truy xuất một tệp​

getFile(id, type, entity, filename, template?) trả về một đối tượng Response thô (không phải JSON đã phân tích) — gọi .blob(), .arrayBuffer(), v.v. trên nó khi cần.

Tạo một tệp từ URL​

createFileFromUrl(url, filename, mimeType?) lấy một tài nguyên từ xa và trả về một File của trình duyệt, tiện lợi cho việc tải lại một hình ảnh từ xa đã tồn tại.

📊 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 lên tệp vào lưu trữ đám mâyNgười dùng tải lên hình ảnh, tài liệu
getFile()Lấy tệp (đối tượng Response thô)Tải xuống một tệp đã lưu
delete()Xóa tệp khỏi lưu trữXóa các tệp cũ
createFileFromUrl()Tạo một File từ một URL từ xaNhập một hình ảnh từ xa trước khi tải lên

Tất cả các phương thức đều công khai — không yêu cầu xác thực người dùng.

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

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

Bất kỳ loại tệp nào. Chỉ có hình ảnh là được tối ưu hóa tự động (thay đổi kích thước/nén); 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?​

Nó phụ thuộc vào giới hạn kế hoạch OneEntry của bạn. Tối ưu hóa hình ảnh trước khi tải lên để giữ kích thước nhỏ.

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

Có — các tệp sẽ ở lại cho đến khi bạn xóa chúng bằng FileUploading.delete(). Các tệp vẫn ở trong lưu trữ ngay cả khi thực thể liên quan bị xóa, vì vậy hãy dọn dẹp chúng một cách rõ ràng.

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 qua SDK này. Theo dõi các giá trị filename mà bạn nhận được từ upload() (ví dụ: lưu chúng trong cơ sở dữ liệu của bạn) để quản lý các tệp sau này.

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. width/height xác định một hộp giới hạn mà hình ảnh được phù hợp bên trong, ngăn ngừa biến dạng.

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

  • Xác thực loại tệp và kích thước trước khi gọi upload().
  • Truyền entity / id để các tệp được tổ chức theo thực thể trong lưu trữ.
  • Kích hoạt compress cho hình ảnh web.
  • Lưu filename được trả về để bạn có thể delete() tệp sau này.
  • Dọn dẹp các tệp không sử dụng một cách rõ ràng — chúng vẫn tồn tại sau khi xóa thực thể.
  • Xử lý lỗi tải lên bằng try/catch và kiểm tra hình dạng trả về của IError.

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