شیمر

نصب#

اگر پروژه را با npx farsiui@latest init راه‌اندازی کرده باشید، shimmer از قبل در پروژه شما وجود دارد. این Utility همراه پکیج farsiui ارائه می‌شود و CLI آن را در فایل CSS سراسری پروژه وارد می‌کند.

در غیر این صورت، پکیج farsiui را نصب کنید:

npmpnpmyarnbun
npm install farsiui
Copy

سپس Utilityهای مشترک را در فایل CSS سراسری پروژه وارد کنید:

Copy@import "tailwindcss";
@import "farsiui/tailwind.css";

استفاده#

کلاس shimmer را روی عنصر متنی قرار دهید:

Copy<p className="shimmer text-muted-foreground">
  در حال ایجاد پاسخ&hellip;
</p>

شیمر بر پایهٔ currentColor ساخته شده و به‌صورت خودکار با رنگ عنصر هماهنگ می‌شود:

• Highlight از رنگ متن گرفته می‌شود و به تنظیمات اضافی نیاز ندارد.
• با هر رنگی، از text-muted-foreground گرفته تا رنگ‌های برند، کار می‌کند.
• در Dark Mode، Highlight به‌صورت خودکار روشن‌تر می‌شود تا همچنان قابل مشاهده باشد.

این افکت کاملاً با CSS پیاده‌سازی شده است. متن با background-clip: text نمایش داده می‌شود و Highlight به‌صورت پیوسته روی آن حرکت می‌کند.

همراه با Marker#

شیمر را می‌توان با هر کامپوننتی که متن نمایش می‌دهد ترکیب کرد. یک کاربرد رایج، استفاده از Marker برای نمایش وضعیت زنده هنگام پردازش پاسخ توسط Assistant است:

Copy<Marker role="status">
  <MarkerIcon>
    <Spinner />
  </MarkerIcon>
  <MarkerContent className="shimmer">
    در حال فکر کردن&hellip;
  </MarkerContent>
</Marker>

رنگ#

برای تعیین رنگ Highlight به‌صورت صریح، از shimmer-color-<color> استفاده کنید. این کلاس رنگ‌های Theme را همراه با Modifier مربوط به Opacity و همچنین هر مقدار رنگ دلخواهی می‌پذیرد.

Copy<p className="shimmer shimmer-color-blue-500/60">
  در حال ایجاد پاسخ&hellip;
</p>
<p className="shimmer shimmer-color-[#378ADD]">
  در حال ایجاد پاسخ&hellip;
</p>

مدت زمان#

با shimmer-duration-<number> مدت زمان یک حرکت کامل را بر حسب میلی‌ثانیه تعیین کنید. مقدار پیش‌فرض 2000 میلی‌ثانیه، یعنی 2s است.

Copy<p className="shimmer shimmer-duration-1000">
  در حال ایجاد پاسخ&hellip;
</p>

عرض Highlight#

با shimmer-spread-<number> عرض نوار Highlight را بر اساس مقیاس Spacing تعیین کنید.

مقدار پیش‌فرض calc(3ch + 40px) است؛ یعنی یک مقدار پایهٔ ثابت به‌علاوهٔ 3ch که با اندازهٔ فونت تغییر می‌کند.

Copy<p className="shimmer shimmer-spread-24">
  در حال ایجاد پاسخ&hellip;
</p>

برای مقدارهای دلخواه می‌توانید از طول یا درصد Arbitrary استفاده کنید:

Copy<p className="shimmer shimmer-spread-[5rem]">
  در حال ایجاد پاسخ&hellip;
</p>

زاویه#

با shimmer-angle-<number> زاویهٔ نوار Highlight را بر حسب درجه تعیین کنید. مقدار پیش‌فرض 20 درجه است.

Copy<p className="shimmer shimmer-angle-45">
  در حال ایجاد پاسخ&hellip;
</p>

معکوس کردن جهت#

با shimmer-reverse حرکت Highlight را در جهت مخالف اجرا کنید.

در Layoutهای RTL، حرکت شیمر به‌صورت خودکار با جهت خواندن هماهنگ می‌شود.

Copy<p className="shimmer shimmer-reverse">
  در حال ایجاد پاسخ&hellip;
</p>

اجرای یک‌باره#

با shimmer-once می‌توانید شیمر را فقط یک بار اجرا کنید و از Loop شدن آن جلوگیری کنید. این حالت برای نمایش یک افکت Reveal هنگام کامل شدن Stream مناسب است.

برای کنترل مدت زمان اجرا، آن را با shimmer-duration-<number> ترکیب کنید.

Copy<p className="shimmer shimmer-duration-1100 shimmer-once">
  پاسخ ایجاد شد.
</p>

غیرفعال کردن شیمر#

برای غیرفعال کردن افکت و نمایش عادی متن، از shimmer-none استفاده کنید.

این کلاس مستقل از ترتیب کلاس‌ها عمل می‌کند و برای حالت‌های Responsive یا Stateful مناسب است:

Copy<p className="shimmer md:shimmer-none">
  در حال ایجاد پاسخ&hellip;
</p>

Fallback#

شیمر بر پایهٔ قابلیت‌های مدرن رنگ در CSS، از جمله Relative Color Syntax و color-mix() ساخته شده است که در مرورگرهای امروزی پشتیبانی می‌شوند.

در مرورگرهای قدیمی‌تر که از این قابلیت‌ها پشتیبانی نمی‌کنند، Gradient مربوط به Highlight حذف می‌شود و ممکن است متن شفاف نمایش داده شود.

اگر از مرورگرهای قدیمی پشتیبانی می‌کنید، shimmer را با یک Variant از نوع supports-* به‌صورت شرطی فعال کنید:

Copy<p className="supports-[color:oklch(from_white_l_c_h)]:shimmer">
  در حال ایجاد پاسخ&hellip;
</p>

کاهش حرکت#

اگر کاربر گزینهٔ Reduced Motion را فعال کرده باشد، انیمیشن به‌صورت خودکار غیرفعال می‌شود و متن به حالت عادی نمایش داده خواهد شد. نیازی به تنظیمات اضافی نیست.

RTL#

حرکت شیمر به‌صورت خودکار از جهت خواندن پیروی می‌کند؛ در LTR از چپ به راست و در RTL از راست به چپ.

برای معکوس کردن دستی جهت حرکت از shimmer-reverse استفاده کنید.