شروع به راهاندازی
پیشنیازها
تمامی کامپوننتهای Tailwind UI برای آخرین نسخه Tailwind CSS یعنی نسخه 4.0 طراحی شدهاند. برای اطمینان از اینکه از جدیدترین نسخه استفاده میکنید، از طریق npm آن را بهروزرسانی کنید:
npm install tailwindcss@latest
اگر تازه با Tailwind CSS آشنا شدهاید، بهتر است مستندات رسمی آن را مطالعه کنید تا بتوانید بیشترین بهره را از Tailwind UI ببرید.
اختیاری: افزودن فونت Inter
در تمام مثالهای Tailwind UI از فونت Inter استفاده شده است، زیرا این فونت برای طراحی UI بسیار زیبا و کاملاً رایگان و متنباز است.
شما میتوانید از هر فونتی که میخواهید استفاده کنید، اما اگر قصد دارید Inter را به پروژه خود اضافه کنید، راحتترین روش، بارگیری آن از طریق CDN است:
<link rel="stylesheet" href="https://rsms.me/inter/inter.css">
@theme {
--font-sans: InterVariable, sans-serif;
}
اگر هنوز از Tailwind CSS v3.x استفاده میکنید، میتوانید آن را در فایل 'tailwind.config.js' اضافه کنید:
const defaultTheme = require('tailwindcss/defaultTheme')
module.exports = {
theme: {
extend: {
fontFamily: {
sans: ['InterVariable', '...defaultTheme.fontFamily.sans'],
},
},
},
// ...
}
استفاده از HTML و جاوا اسکریپت خودتان
کامپوننتهای Tailwind UI در سه قالب ارائه میشوند: React، Vue و HTML ساده.
نسخههای React و Vue بهطور کامل آمادهی استفاده هستند و از Headless UI پشتیبانی میکنند.
نسخههای HTML هیچ JavaScript داخلی ندارند و برای کسانی طراحی شدهاند که ترجیح میدهند خودشان جاوا اسکریپت موردنیاز را اضافه کنند.
بسیاری از کامپوننتها بدون نیاز به جاوا اسکریپت کار میکنند، اما المانهای تعاملی مانند دراپداونها و دیالوگها نیاز به اسکریپتنویسی دارند.
در این موارد، نظراتی در کد HTML درج شده است که توضیح میدهند: کدام کلاسها برای حالتهای مختلف استفاده میشوند. چگونه افکتهای انتقالی را برای نمایش یا پنهان کردن المانها اعمال کنید.
دسترسیپذیری
ما تلاش کردهایم که تمام مارکاپهای Tailwind UI دسترسپذیر باشند، اما برخی موارد باید با JavaScript پیادهسازی شوند.
برای مثال:
- دسترسی با کیبورد (مثلاً دراپداونها باید با کلیدهای ↑↓ قابل کنترل باشند)
- مدیریت فوکوس (مثلاً هنگام باز شدن یک دیالوگ، نباید بتوانید به عناصر پشت آن Tab بزنید)
- هماهنگی ARIA با وضعیت کامپوننت (مثلاً اضافه کردن aria-expanded="true" به دراپداونهای باز)
در React و Vue، این موارد توسط Headless UI مدیریت میشوند، اما اگر از HTML خالص استفاده میکنید، باید بهصورت دستی آنها را پیادهسازی کنید.
پیشنهاد میشود راهنمای WAI-ARIA منتشر شده توسط W3C را مطالعه کنید.
کلاسهای داینامیک
گاهی لازم است کلاسهای یک المان را براساس وضعیت آن تغییر دهیم (مثلاً روشن یا خاموش بودن یک toggle). برای وضوح بیشتر، کلاسهای هر وضعیت در یک کامنت بالای المان نوشته شدهاند:
<!-- On: "bg-indigo-600", Off: "bg-gray-200" -->
<span aria-checked="false" class="bg-gray-200 relative inline-block shrink-0 h-6 w-11 border-2 border-transparent rounded-full cursor-pointer transition-colors ease-in-out duration-200 focus:outline-none focus:shadow-outline" role="checkbox" tabindex="0">
<!-- On: "translate-x-5", Off: "translate-x-0" -->
<span aria-hidden="true" class="translate-x-0 inline-block size-5 rounded-full bg-white shadow transform transition ease-in-out duration-200"></span>
</span>
HTML که ما ارائه میدهیم همیشه برای یکی از حالتهای تعریفشده پیشتنظیم شده است، و کلاسهایی که باید هنگام تغییر حالتها تغییر دهید، همیشه در ابتدای فهرست کلاسها قرار دارند تا پیدا کردن آنها آسان باشد.
بهعنوان مثال، برای تطبیق این HTML با Alpine.js، میتوانید کلاسهای صحیح را بهطور شرطی با استفاده از دستور :class براساس حالتی که در x-data اعلام کردهاید، اعمال کنید:
<span
x-data="{ isOn: false }"
@click="isOn = !isOn"
:aria-checked="isOn"
:class="{'bg-indigo-600': isOn, 'bg-gray-200': !isOn }"
class="bg-gray-200 relative inline-block shrink-0 h-6 w-11 border-2 border-transparent rounded-full cursor-pointer transition-colors ease-in-out duration-200 focus:outline-none focus:shadow-outline"
role="checkbox"
tabindex="0"
>
<span
aria-hidden="true"
:class="{'translate-x-5': isOn, 'translate-x-0': !isOn }"
class="translate-x-0 inline-block size-5 rounded-full bg-white shadow transform transition ease-in-out duration-200"
></span>
</span>
ما یک هندلر ساده کلیک را برای نمایش ایده کلی در اینجا گنجاندهایم، اما لطفاً هنگام ساخت کامپوننتهایی مانند این، به دستورالعملهای WAI-ARIA Authoring Practices مراجعه کنید تا اطمینان حاصل کنید که تمام تعاملات کیبورد لازم را پیادهسازی کردهاید و تمام ویژگیهای ARIA مورد نیاز را به درستی مدیریت میکنید.
انتقالات (Transitions)
برای عناصری که باید بهطور دینامیک نمایش داده یا مخفی شوند (مانند پنل در یک منوی کشویی)، ما استایلهای انتقال پیشنهادی را در یک نظر بالای عنصر دینامیک درج میکنیم:
<div class="relative ...">
<button type="button" class="...">
Options
</button>
<!--
Show/hide this element based on the dropdown state
Entering: "transition ease-out duration-100 transform"
From: "opacity-0 scale-95"
To: "opacity-100 scale-100"
Closing: "transition ease-in duration-75 transform"
From: "opacity-100 scale-100"
To: "opacity-0 scale-95"
-->
<div class="origin-top-right absolute right-0 mt-2 w-56 rounded-md shadow-lg">
<div class="rounded-md bg-white shadow-xs">
<!-- Snipped -->
</div>
</div>
</div>
به عنوان مثال، برای سازگار کردن این HTML با Alpine.js، شما از دستور x-transition برای اعمال کلاسهای صحیح در هر مرحله از چرخه انتقال استفاده میکنید:
<div x-data="{ isOpen: false }" class="relative ...">
<button type="button" @click="isOpen = !isOpen" class="...">
Options
</button>
<div
x-show="isOpen"
x-transition:enter="transition ease-out duration-100 transform"
x-transition:enter-start="opacity-0 scale-95"
x-transition:enter-end="opacity-100 scale-100"
x-transition:leave="transition ease-in duration-75 transform"
x-transition:leave-start="opacity-100 scale-100"
x-transition:leave-end="opacity-0 scale-95"
class="origin-top-right absolute right-0 mt-2 w-56 rounded-md shadow-lg"
>
<div class="rounded-md bg-white shadow-xs">
<!-- Snipped -->
</div>
</div>
</div>
ما یک هندلر ساده کلیک را برای نمایش ایده کلی در اینجا گنجاندهایم، اما لطفاً هنگام ساخت کامپوننتهایی مانند این، به دستورالعملهای WAI-ARIA Authoring Practices مراجعه کنید تا اطمینان حاصل کنید که تمام تعاملات کیبورد لازم را پیادهسازی کردهاید و تمام ویژگیهای ARIA مورد نیاز را به درستی مدیریت میکنید.
ساخت Partial ها / کامپوننتها
از آنجا که مثالهای HTML ساده در Tailwind UI نمیتوانند از قابلیتهایی مثل حلقهها بهره ببرند، تکرار زیادی در آنها وجود دارد که در یک پروژه واقعی، جایی که HTML از یک منبع داده داینامیک تولید میشود، اصلاً وجود نخواهد داشت. به عنوان مثال، ممکن است یک کامپوننت لیست با 5 آیتم لیست دریافت کنید که تمام استایلها در هر یک تکرار شدهاند، در حالی که در پروژه شما، این آیتمهای لیست در واقع با استفاده از یک حلقه از روی یک آرایه تولید خواهند شد.
زمانی که مثالهای ما را برای پروژههای خود سازگار میکنید، پیشنهاد میکنیم برای مدیریت تکرارها، Partial های قابل استفاده مجدد یا کامپوننتهای جاوااسکریپت ایجاد کنید.
برای اطلاعات بیشتر، میتوانید به مستندات “استخراج کامپوننتها” در وبسایت Tailwind CSS مراجعه کنید.
استفاده از React
نصب وابستگیها
Tailwind UI برای React به Headless UI برای اجرای تمام رفتارهای تعاملی و Heroicons برای آیکونها نیاز دارد، بنابراین باید این دو کتابخانه را به پروژه خود اضافه کنی:
npm install @headlessui/react @heroicons/react
این کتابخانهها و خود Tailwind UI به React >= 16 نیاز دارند.
ساخت کامپوننتها
تمامی مثالهای React به صورت یک کامپوننت ساده و واحد ارائه شدهاند و هیچ فرضی درباره نحوه تقسیمبندی کد، APIهای پروپهایی که میخواهید نمایش دهید، یا منبع دادهها نداشتهاند.
برخی دادهها به متغیرهای محلی ساده استخراج شدهاند تا تکرارها تمیز شوند و کد خواناتر و قابل فهمتر باشد، اما سعی شده است که حداقل تغییرات اعمال شود تا از تحمیل نظرات سختگیرانه غیرضروری جلوگیری شود.
زمانی که کدهای Tailwind UI را برای پروژههای خود سازگار میکنید، باید مثالها را به کامپوننتهای کوچکتر تقسیم کنید تا به هر سطحی از استفاده مجدد که برای پروژهتان نیاز دارید، برسید.
به عنوان مثال، ممکن است با این کامپوننت لیست استک شده شروع کنید:
const people = [
{
name: 'Calvin Hawkins',
email: 'calvin.hawkins@example.com',
image:
'https://images.unsplash.com/photo-1491528323818-fdd1faba62cc?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80',
},
{
name: 'Kristen Ramos',
email: 'kristen.ramos@example.com',
image:
'https://images.unsplash.com/photo-1550525811-e5869dd03032?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80',
},
{
name: 'Ted Fox',
email: 'ted.fox@example.com',
image:
'https://images.unsplash.com/photo-1500648767791-00dcc994a43e?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80',
},
]
export default function Example() {
return (
<ul className="divide-y divide-gray-200">
{people.map((person) => (
<li key={person.email} className="py-4 flex">
<img className="size-10 rounded-full" src={person.image} alt="" />
<div className="ml-3">
<p className="text-sm font-medium text-gray-900">{person.name}</p>
<p className="text-sm text-gray-500">{person.email}</p>
</div>
</li>
))}
</ul>
)
}
پس از سازگار کردن محتوا برای پروژه خودتان، شکستن آن به اجزای جداگانه و اتصال منبع داده، ممکن است به این شکل به نظر برسد:
function HockeyTeamItem({ team }) {
return (
<li className="py-4 flex">
<img className="size-10 rounded-full" src={team.logo} alt="" />
<div className="ml-3">
<p className="text-sm font-medium text-gray-900">{team.name}</p>
<p className="text-sm text-gray-500">{team.city}</p>
</div>
</li>
)
}
export default function HockeyTeamList({ teams }) {
return (
<ul className="divide-y divide-gray-200">
{teams.map((team) => <HockeyTeamItem key={team.id} team={team} />)}
</ul>
)
}
Tailwind UI بیشتر شبیه مجموعهای از نقشهها، الگوها و ایدهها است تا یک کیت UI سختگیرانه. کدی که در نهایت به دست میآورید متعلق به شماست و میتوانید آن را هرطور که میخواهید سازماندهی کنید.
استفاده از Vue
نصب وابستگیها
Tailwind UI برای React به Headless UI برای اجرای تمام رفتارهای تعاملی و Heroicons برای آیکونها نیاز دارد، بنابراین باید این دو کتابخانه را به پروژه خود اضافه کنی: