Chuyển tới nội dung

Pro đang mở bán trước. Cài đặt mở từ tháng 1/2027. Xem Pro

werewolf-ui
Component

Image

Ảnh không bao giờ hiện một hộp trống hoặc xuất hiện đột ngột. Khung giữ kích thước từ ratio, một bản làm mờ nhỏ của ảnh hiện ngay, và ảnh đầy đủ fade đè lên sau khi tải xong.

  • npm: 0 trực tiếp, 1 tổng
  • registry: 2 trực tiếp, 2 tổng

Xem trước

Những ngọn đồi lúc chạng vạng dưới bầu trời hồng

Props

  • loaded
  • blurred
  • ratio
import { Image } from "@/components/ui/image"

const photo = {
  src: "/preview/image.webp",
  placeholder: "data:image/webp;base64,UklGRkIAAABXRUJQVlA4IDYAAADQAQCdASoQAAkAA4BaJQBOgCIfphDw8AD+vHG0aMGwi8/yX2fQS0b/tpRtPIXVO/hCeZK3qAA=",
  alt: "Những ngọn đồi lúc chạng vạng dưới bầu trời hồng"
}

<Image src={photo.src} placeholderSrc={photo.placeholder} alt={photo.alt} ratio="16 / 9" className="w-80 min-w-0 max-w-full" />

Cách dùng

Khi nào dùng

  • Hiện một ảnh chụp, ảnh bìa hoặc hình minh họa mà chỗ phải được giữ trong lúc tải.
  • Hiện bản làm mờ của ảnh trước, rồi fade sang ảnh đầy đủ khi tải xong.

Khi nào không dùng

  • Ảnh của một người, một nhóm hoặc một workspace. Dùng Avatar.
  • Nội dung đã biết bố cục nhưng dữ liệu vẫn đang tải. Dùng Skeleton.

Ví dụ

Một ảnh bìa

Bản làm mờ hiện ngay, và ảnh đầy đủ fade đè lên.

Những ngọn đồi lúc chạng vạng dưới bầu trời hồng
import { Image } from "@/components/ui/image"

const photo = {
  src: "/preview/image.webp",
  placeholder: "data:image/webp;base64,UklGRkIAAABXRUJQVlA4IDYAAADQAQCdASoQAAkAA4BaJQBOgCIfphDw8AD+vHG0aMGwi8/yX2fQS0b/tpRtPIXVO/hCeZK3qAA=",
  alt: "Những ngọn đồi lúc chạng vạng dưới bầu trời hồng"
}

<Image src={photo.src} placeholderSrc={photo.placeholder} alt={photo.alt} ratio="16 / 9" className="w-80 min-w-0 max-w-full" />

Vẫn đang tải

Chưa có src, bản làm mờ giữ khung.

import { Image } from "@/components/ui/image"

const photo = {
  src: "/preview/image.webp",
  placeholder: "data:image/webp;base64,UklGRkIAAABXRUJQVlA4IDYAAADQAQCdASoQAAkAA4BaJQBOgCIfphDw8AD+vHG0aMGwi8/yX2fQS0b/tpRtPIXVO/hCeZK3qAA=",
  alt: "Những ngọn đồi lúc chạng vạng dưới bầu trời hồng"
}

<Image placeholderSrc={photo.placeholder} alt={photo.alt} ratio="16 / 9" className="w-80 min-w-0 max-w-full" />

Nên và không nên

Nên

  • Luôn giữ chỗ: ratio, một class aspect hoặc một chiều cao cố định.
  • Tạo placeholderSrc khi thêm ảnh, lúc build hoặc khi upload, và nhúng nội tuyến dưới dạng data URL.
  • Phục vụ ảnh đầy đủ đúng kích thước đang hiện (srcSet và sizes truyền thẳng tới ảnh).

Không nên

  • Đừng tải placeholderSrc từ một URL riêng: nó cũng sẽ cần một placeholder.
  • Đừng dùng cho avatar. Dùng Avatar, hiện chữ cái đầu cho đến khi ảnh tải xong.
  • Đừng đặt chữ đè lên ảnh; độ tương phản không được kiểm tra.

Props

TênKiểuGiá trịMặc địnhMô tả
srcstring--Ảnh đầy đủ. Cho đến khi được gán và tải xong, bản làm mờ (hoặc khung xám) hiện. Một src mới hiện lại bản làm mờ cho đến khi ảnh mới tải xong.
alt bắt buộcstring--Ảnh đang hiện gì, cho trình đọc màn hình. "" cho ảnh trang trí.
placeholderSrcstring--Một bản làm mờ nhỏ của cùng ảnh, tốt nhất là data URL nội tuyến vài trăm byte (16 nhân 9 pixel là đủ), tạo khi thêm ảnh (lúc build hoặc khi upload), để hiện cùng trang và không cần request. Không có thì khung hiện nền xám nhạt.
ratiostring--Tỷ lệ rộng trên cao của khung, chẳng hạn 16 / 9 hoặc "4 / 3". Giữ chỗ trước khi có gì tải, nên không có gì dịch chuyển. Hoặc đặt một class aspect (aspect-video) hoặc một chiều cao bằng className.

Cấu tạo

PhầnMô tả
rootKhung: bo góc element, nền xám nhạt, cắt những gì bên trong. ratio đặt tỷ lệ khung, nên chỗ được giữ trước khi có gì tải.
blurredplaceholderSrc: vài pixel của cùng bức ảnh, phóng tới khung và làm mờ, hiện ngay.
imageẢnh đầy đủ ở trên. Trong suốt cho đến khi tải xong, rồi fade vào với duration-medium.

Khả năng truy cập

Role: img

  • alt là bắt buộc theo type. Mô tả ảnh đang hiện gì; chỉ truyền alt="" cho ảnh trang trí.
  • Bản làm mờ bị ẩn khỏi trình đọc màn hình (alt="" và aria-hidden), nên ảnh chỉ được đọc một lần.
  • Không fade khi prefers-reduced-motion: ảnh đầy đủ hiện trong một bước.
  • Ảnh lỗi hiện hộp ảnh hỏng của trình duyệt cùng văn bản alt, không phải một placeholder kéo dài mãi.

Cài đặt

npx werewolf-ui add image

Chạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.