Aspect Ratiov1.0.0
محتوا را در نسبت ابعاد ثابتی نگه می‌دارد؛ جای تصویر یا ویدیو پیش از بارگذاری رزرو می‌شود و چیدمان صفحه وسط کار نمی‌پرد.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/aspect-ratio.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/aspect-ratio.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/aspect-ratio.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/aspect-ratio.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { AspectRatio } from "@/components/ui/aspect-ratio"
<div className="w-full max-w-md">
<AspectRatio ratio={16 / 9}>
<img src="/cover.jpg" alt="جلد" className="size-full rounded-md object-cover" />
</AspectRatio>
</div>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
عرض را والدِ AspectRatio تعیین می‌کند و ارتفاع از روی ratio حساب می‌شود؛ پس همیشه یک ظرف با عرض مشخص دورش بگذارید، وگرنه چیزی برای محاسبه نمی‌ماند.
فرزند به‌طور مطلق کل ناحیه را پر می‌کند، برای همین روی تصویر object-cover یا object-contain بدهید تا کشیدگی نداشته باشد.
این کامپوننت خودش هیچ استایلی (گوشهٔ گرد، پس‌زمینه) اضافه نمی‌کند.
دسترس‌پذیری
- این یک ظرف چیدمانی است و نقش ARIA ندارد؛ معنا از محتوای داخلش می‌آید.
- برای تصویر همیشه alt معنادار بنویسید و برای تصویر تزئینی alt خالی بگذارید.
- چون جای محتوا از قبل رزرو می‌شود، امتیاز CLS صفحه بهتر می‌ماند و کاربر هنگام بارگذاری پرش نمی‌بیند.
- برای ویدیوی جاسازی‌شده، iframe را با title توصیفی همراه کنید.
مرجع API
AspectRatio
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| ratio | number | 1 | نسبت عرض به ارتفاع؛ به‌صورت تقسیم بنویسید مثل 16 / 9. |
| children | React.ReactNode | — | محتوا به‌طور مطلق کل ناحیه را پر می‌کند؛ روی تصویر object-cover بدهید. |
| className | string | — | روی ظرف داخلی می‌نشیند؛ برای گوشهٔ گرد و پس‌زمینه از همین استفاده کنید. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Common Ratios
نسبت را به‌صورت تقسیم بنویسید تا خواناتر بماند: ۱۶/۹، ۴/۳، ۱/۱.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Inside a Card
کاربرد رایج: تصویر جلد کارت محصول که پیش از بارگذاری هم جایش را گرفته است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Video Embed
برای ویدیوی جاسازی‌شده، iframe را با کلاس size-full داخل نسبت ۱۶/۹ بگذارید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
بدون تصویر (Fallback)
نسبت ابعاد باید بدون توجه به محتوا ثابت بماند؛ وگرنه با رسیدن تصویر، ارتفاع کارت می‌پرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Common Ratios | نسبت را به‌صورت تقسیم بنویسید تا خواناتر بماند: ۱۶/۹، ۴/۳، ۱/۱. |
| Inside a Card | کاربرد رایج: تصویر جلد کارت محصول که پیش از بارگذاری هم جایش را گرفته است. |
| Video Embed | برای ویدیوی جاسازی‌شده، iframe را با کلاس size-full داخل نسبت ۱۶/۹ بگذارید. |
| بدون تصویر (Fallback) | کارتی که تصویرش هنوز بارگذاری نشده یا اصلاً ندارد |
دستورالعمل استفاده
عرض را والد تعیین کند
انجام بده
AspectRatio ارتفاع را از روی عرضِ ظرفش حساب می‌کند؛ پس همیشه داخل یک ظرف با عرض مشخص بگذاریدش تا نسبت درست ساخته شود.
انجام نده
بدون عرض مشخص روی والد، ناحیه تا کل فضای موجود کش می‌آید و نسبتی که انتظار داشتید در چیدمان دیده نمی‌شود.
تصویر با object-cover
انجام بده
فرزند کل ناحیه را پر می‌کند؛ روی تصویر object-cover بگذارید تا برش بخورد ولی کشیده و بدشکل نشود.
انجام نده
بدون کلاس اندازه‌گیری، تصویر با ابعاد ذاتی خودش رندر می‌شود و ناحیهٔ رزروشده را پر نمی‌کند؛ نتیجه فضای خالی یا سرریز است.