image_url

Chuyển UUID ảnh trong Files thành URL public. Có thể resize, crop và tái sử dụng các phiên bản ảnh đã tạo (variants).

Cú pháp

{{ item.images | first | image_url }}
{{ item.images | first | image_url: width: 450 }}
{{ item.images | first | image_url: width: 450, height: 300, crop: 'bottom' }}

Đầu vào: UUID của file ảnh public thuộc đúng website và workspace hiện tại; không truyền URL, đường dẫn hoặc object ảnh. Đầu ra: chuỗi URL ảnh gốc hoặc variant. Không truyền kích thước thì trả URL ảnh gốc.

width — Chiều rộng

Số nguyên từ 1–4096, đơn vị pixel, không bắt buộc. Chỉ truyền width: tự tính chiều cao theo tỷ lệ ảnh gốc.

{{ item.images | first | image_url: width: 450 }}

height — Chiều cao

Số nguyên từ 1–4096, đơn vị pixel, không bắt buộc. Chỉ truyền height: tự tính chiều rộng. Truyền cả width và height nhưng không crop: thu ảnh vừa trong khung, giữ tỷ lệ, không cắt.

{{ item.images | first | image_url: height: 300 }}
{{ item.images | first | image_url: width: 450, height: 300 }}

crop — Vị trí cắt ảnh

Chuỗi tùy chọn. Khi sử dụng phải có cả width và height. Ảnh được cắt theo tỷ lệ khung đích rồi resize, không kéo méo.

Chiều không được chỉ định vị trí sẽ căn giữa. Nếu tỷ lệ ảnh chỉ gây dư theo chiều ngang, top/bottom không làm thay đổi vị trí cắt theo chiều dọc.

{{ item.images | first | image_url: width: 450, height: 300, crop: 'bottom' }}

Ví dụ dùng với thẻ img

{% if item.images %}
  <img
    src="{{ item.images | first | image_url: width: 450, height: 300, crop: 'bottom' }}"
    alt="{{ item.title }}"
    loading="lazy"
  >
{% endif %}

Tạo và tái sử dụng variants

1. Kiểm tra file public, đúng quyền website/workspace và chưa bị xóa.
2. Tìm variant theo file, width, height, crop và phiên bản thuật toán. Cùng kích thước nhưng khác crop là các variant khác nhau.
3. Nếu đã có: trả URL đã lưu, không resize lại.
4. Nếu chưa có: đọc ảnh gốc, resize/crop, upload vào {owner_uuid}/variants/{file_id}/ và lưu bảng media_variants.

DB lưu quan hệ với file gốc, kích thước yêu cầu/thực tế, crop, định dạng, storage key, dung lượng và thời điểm tạo. Request đầu tiên tạo ảnh đồng bộ nên có thể chậm hơn; các request sau tái sử dụng. Khóa xử lý ngăn nhiều request tạo trùng một variant.

Khi xóa file gốc

owner_uuid là UUID application nếu file thuộc application, hoặc UUID workspace nếu upload trực tiếp vào workspace. Upload mới có key {owner_uuid}/{YYYY}/{MM}/{file_uuid}.{ext} trong bucket public hoặc private tương ứng. File và variants cũ giữ nguyên URL; image_url vẫn chỉ xử lý ảnh public.

Thao tác xóa Files hiện tại xóa vĩnh viễn dữ liệu trên storage, dù DB giữ dấu đã xóa. Hệ thống dọn ảnh gốc, mọi variant và bản ghi variants tương ứng. Nếu storage lỗi, giữ thông tin để thử xóa lại. Đây không phải thùng rác có thể khôi phục.

Định dạng, giới hạn và lỗi

• Resize JPEG, PNG, GIF, WebP. JPEG xuất JPEG chất lượng 85; các định dạng còn lại xuất PNG. GIF chỉ lấy frame đầu, không giữ animation.
• SVG và định dạng chưa hỗ trợ resize có thể lấy URL gốc, không dùng tham số kích thước.
• Tối đa 32 variants/file; ảnh nguồn tối đa 32 MiB và 40 triệu pixel khi tạo variant.
• Đầu vào rỗng trả chuỗi rỗng. UUID sai, file private, ngoài phạm vi, đã xóa hoặc không phải ảnh sẽ báo lỗi; không tự cấp quyền public.
• Kích thước sai kiểu, bằng 0, vượt giới hạn, crop không hợp lệ, thiếu chiều khi crop hoặc key không hỗ trợ đều báo lỗi.
• Lỗi storage hoặc giải mã ảnh có thể làm render trang thất bại. Filter không tải URL ngoài do người dùng truyền vào.

Runtime Skai: image_url filter, media variants và migration 000149. Helper media_image() cũ vẫn được giữ để tương thích theme hiện có.