هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى قدر من الإنتاجية؟
يلبي Apidog جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!
بالنسبة لمطوري الواجهة الأمامية، لم يكن الطلب على واجهات مستخدم جذابة بصريًا، عالية الأداء، وقابلة للتخصيص بعمق أكبر من أي وقت مضى. يبحث المطورون باستمرار عن أدوات يمكنها تسريع سير عملهم دون التضحية بالجودة أو التحكم الإبداعي. بينما خدمت مكتبات مكونات واجهة المستخدم المتجانسة المجتمع جيدًا لسنوات، يظهر نموذج جديد - نموذج يعطي الأولوية لملكية المطور، والوحداتية، والتكامل السلس مع الأطر الحديثة. ضمن هذا النموذج الجديد، ينحت HeroUI مكانه الخاص.
HeroUI ليس مجرد مكتبة مكونات أخرى؛ إنه مجموعة مصممة بدقة من مكونات واجهة المستخدم القابلة لإعادة الاستخدام المصممة ليتم دمجها مباشرة في مشاريعك. إنه يدعم فلسفة تمنح المطورين التحكم المطلق في قاعدة بياناتهم البرمجية. بدلاً من استيراد مكونات مبهمة من وحدة node، تستخدم واجهة سطر الأوامر (CLI) الخاصة بـ HeroUI لإضافة الكود المصدري الفعلي للمكونات التي تحتاجها إلى مشروعك. هذا "النسخ واللصق" المتطور يعني أن كل زر، وبطاقة، ومربع حوار يصبح جزءًا من تطبيقك الخاص، جاهزًا للتعديل، وإعادة التصميم، والتكيف مع احتياجاتك الخاصة.
بني على أكتاف عمالقة مثل React وTailwind CSS وNext.js، يوفر HeroUI اللبنات الأساسية لإنشاء واجهات مستخدم جميلة، ومتاحة، ومتجاوبة. إنه مصمم للمطور الحديث الذي يقدر السرعة والتحديد، ويقدم نقطة انطلاق قوية لا تقيدك بنظام تصميم جامد. سيكون هذا المقال بمثابة دليل شامل لفهم المبادئ الأساسية لـ HeroUI، وتثبيته في مشروعك، وتخصيص مظهره وشعوره، والاستفادة من واجهة سطر الأوامر القوية الخاصة به لبناء الجيل القادم من تطبيقات الويب.
الجزء الأول: تفكيك HeroUI - الفلسفة والميزات الأساسية
قبل الغوص في التفاصيل الفنية للتثبيت والاستخدام، من الضروري فهم "السبب" وراء HeroUI. ما المشكلات التي يحلها، وما الذي يجعله خيارًا مقنعًا في مجال مزدحم بأدوات واجهة المستخدم؟
الفلسفة: الملكية والتخصيص غير المقيد
الفرق الأساسي بين HeroUI ومكتبات واجهة المستخدم التقليدية مثل Material-UI أو Ant Design يكمن في مفهوم الملكية. عندما تقوم بتثبيت مكتبة تقليدية، فإنك تضيف تبعية إلى ملف package.json
الخاص بك. يقوم تطبيقك بعد ذلك باستيراد مكونات مجمعة مسبقًا من هذه الحزمة. بينما هذا مريح، فإنه يأتي مع العديد من العيوب:
- تخصيص محدود: قد تكون تجاوزات الأنماط معقدة، وغالبًا ما تتطلب منك محاربة الأنماط الافتراضية للمكتبة باستخدام علامات
!important
أو تكوينات مزود سمات معقدة. - مكونات الصندوق الأسود: المنطق الداخلي للمكونات مخفي في مجلد
node_modules
. يصبح تصحيح الأخطاء في السلوك غير المتوقع أو فهم العمليات الداخلية أصعب بكثير. - انتفاخ حجم الحزمة: غالبًا ما تقوم باستيراد المكتبة بأكملها، أو على الأقل جزء كبير منها، حتى لو كنت تستخدم عددًا قليلاً فقط من المكونات، مما قد يزيد من حجم الحزمة النهائية لتطبيقك.
- جحيم التبعيات: أنت ملزم بدورة تحديث المكتبة وتبعاتها. قد يتطلب تغيير جذري في المكتبة إعادة بناء كبيرة في تطبيقك.
يتجنب HeroUI هذه المشكلات تمامًا. من خلال جعل واجهة سطر الأوامر تضع الكود المصدري للمكون مباشرة في دليل مشروعك (على سبيل المثال، /components/ui
)، فإنه يمكّنك بعدة طرق رئيسية:
- أنت تملك الكود: المكون الآن ملكك. يمكنك تغيير هيكله، أنماطه، منطقه - أي شيء. لا توجد قيود اصطناعية. إذا كنت بحاجة إلى زر مع حركة فريدة أو هيكل داخلي مختلف قليلاً، يمكنك ببساطة تعديل الملف.
- شفافية تامة: يمكنك قراءة كود كل مكون تستخدمه. هذا لا يقدر بثمن للتعلم، وتصحيح الأخطاء، واكتساب فهم أعمق لكيفية بناء عناصر واجهة مستخدم قوية ومتاحة.
- لا يوجد كود غير مستخدم: لن تتضمن حزمة تطبيقك سوى الكود الخاص بالمكونات التي أضفتها صراحة. لا شيء أكثر.
- مفكوك ومقاوم للمستقبل: بما أن المكونات جزء من قاعدة بياناتك البرمجية، فأنت غير مقيد بإصدار HeroUI بنفس الطريقة. يمكنك تحديث المكونات وفقًا لجدولك الزمني الخاص أو اختيار عدم تحديثها على الإطلاق.
تهدف هذه الفلسفة إلى المطورين والفرق الذين يرغبون في بناء نظام تصميم فريد لمنتجهم دون البدء من الصفر. إنها توفر الأساسيات الأولية، غير المنسقة (أو المنسقة قليلاً)، وأنت توفر هوية العلامة التجارية.
الميزات الرئيسية في لمحة
HeroUI هو أكثر من مجرد طريقة تثبيته. إنه مليء بالميزات المصممة لسير عمل التطوير الحديث.
- مجموعة مكونات غنية: يقدم HeroUI مجموعة شاملة من مكونات واجهة المستخدم الأكثر شيوعًا، بما في ذلك الأزرار، والنماذج، ومربعات الحوار، والقوائم المنسدلة، وجداول البيانات، والمزيد. تم تصميم كل مكون بعناية مع مراعاة إمكانية الوصول (سمات ARIA) وتجربة المستخدم.
- مدعوم من Tailwind CSS: في قلب قدرات تنسيق HeroUI يكمن Tailwind CSS، إطار عمل CSS القائم على الأدوات المساعدة. هذا يعني أن التخصيص لا يتم من خلال تجاوز فئات CSS ولكن من خلال تجميع فئات الأدوات المساعدة. هذا النهج سريع بشكل لا يصدق، وبديهي، ويساعد في الحفاظ على لغة تصميم متناسقة. يستخدم HeroUI قدرات Tailwind على التسمية إلى أقصى حد، مما يسمح بإجراء تغييرات على مستوى المشروع ببضعة أسطر فقط من التكوين.
- تسمية وتخصيص عميق: يمكن التحكم في المظهر والشعور الكامل للمكونات من خلال تكوين سمة مركزي. يشمل ذلك الألوان، والخطوط، ونصف قطر الحدود، والمسافات، والمزيد. كل هذا مدعوم بمتغيرات CSS، مما يجعل التسمية الديناميكية، مثل تطبيق الوضع الداكن، سهلة بشكل لا يصدق.
- واجهة سطر أوامر قوية (CLI):
heroui-cli
هي أداتك الأساسية للتفاعل مع نظام HeroUI البيئي. تتعامل مع تهيئة المشروع، وتضيف مكونات جديدة، وتضمن تكوين مشروعك بشكل صحيح، مما يوفر عليك ساعات من الإعداد اليدوي. - تكامل يعتمد على الإطار أولاً: تم تصميم HeroUI للتكامل بسلاسة مع الأطر الحديثة. يوفر التوثيق دعمًا وإرشادات من الدرجة الأولى لـ Next.js، مما يدل على الالتزام بالعمل بشكل جيد ضمن أدوات نظام React البيئي الأكثر شيوعًا. تم بناؤه باستخدام React ويمكن تكييفه مع أطر عمل أخرى قائمة على React مثل Vite أو Create React App.
- الوضع الداكن افتراضيًا: الوضع الداكن ليس مجرد فكرة لاحقة. تم بناء النظام بأكمله مع مراعاة الوضع الداكن، مع الاستفادة من متغيرات CSS ونسخة
dark:
من Tailwind لجعل التنفيذ بسيطًا. - دعم TypeScript وRSC: HeroUI مكتوب بلغة TypeScript، مما يوفر سلامة ممتازة للأنواع خارج الصندوق. وهو متوافق أيضًا مع مكونات خادم React (RSC)، مما يجعله متوافقًا مع أحدث التطورات في نظامي Next.js وReact البيئيين.
لمن HeroUI؟
HeroUI هو خيار مثالي لنوع معين من المطورين والمشاريع:
- المطورون الذين يتوقون إلى التحكم: إذا شعرت يومًا بالإحباط بسبب جمود مكتبة المكونات، فسوف تشعر HeroUI وكأنها نسمة هواء منعش.
- المشاريع ذات هوية العلامة التجارية القوية والفريدة: إنها توفر الأساس المثالي لبناء نظام تصميم مخصص لا يشبه كل موقع ويب آخر.
- الشركات الناشئة وفرق المنتجات: الفرق التي تحتاج إلى التحرك بسرعة ولكنها ترغب أيضًا في بناء بنية واجهة أمامية قابلة للتوسع والصيانة ستجد HeroUI مسرعًا قويًا.
- التعلم والتطوير: نظرًا لأنك تحصل على الكود المصدري، فهي أداة ممتازة لتعلم كيفية بناء مكونات React عالية الجودة ومتاحة.
قد يكون أقل ملاءمة للمبتدئين تمامًا الذين يفضلون حلًا جاهزًا "خارج الصندوق"، حيث يتطلب الحد الأدنى من التكوين. تكمن قوة HeroUI في قابليته للتكوين، مما يتطلب فهمًا أساسيًا لـ Tailwind CSS وبيئة تطوير الواجهة الأمامية الحديثة.
الجزء الثاني: البدء - جولة مفصلة في التثبيت والإعداد
الآن بعد أن فهمنا الفلسفة، دعنا نبدأ العمل. يوفر هذا القسم دليلًا دقيقًا خطوة بخطوة لدمج HeroUI في مشروع جديد أو موجود. الطريقة الموصى بها والأكثر كفاءة هي استخدام واجهة سطر الأوامر الرسمية لـ HeroUI.
المتطلبات الأساسية
قبل أن نبدأ، تأكد من أن بيئة التطوير الخاصة بك تلبي المتطلبات التالية:
- Node.js: يجب أن يكون لديك إصدار حديث من Node.js مثبتًا (عادةً الإصدار 18 أو أحدث). يمكنك التحقق من إصدارك عن طريق تشغيل
node -v
في الطرفية. - مدير الحزم: ستحتاج إلى مدير حزم مثل
npm
أوyarn
أوpnpm
. سيستخدم هذا الدليلnpx
، وهو مضمن معnpm
. - مشروع إطار عمل React: تم تصميم HeroUI ليتم إضافته إلى مشروع تم إنشاؤه باستخدام إطار عمل React. يركز الدليل الأساسي على Next.js، ولكن يمكن تكييفه مع أطر عمل أخرى مثل Vite أو Create React App. للحصول على أفضل تجربة، سنفترض أنك تبدأ بمشروع Next.js جديد. يمكنك إنشاء واحد باستخدام الأمر: Bash
npx create-next-app@latest my-heroui-app
أثناء إعداد Next.js، يوصى باختيار TypeScript وTailwind CSS، حيث إن هذه أساسيات نظام HeroUI البيئي.
أمر init
في واجهة سطر الأوامر HeroUI: نقطة انطلاقك
أمر init
هو نقطة الدخول السحرية إلى عالم HeroUI. يقوم بفحص مشروعك بذكاء، ويسألك سلسلة من الأسئلة، ثم يقوم تلقائيًا بتكوين كل ما تحتاجه.
انتقل إلى دليل مشروعك:Bash
cd my-heroui-app
الآن، قم بتشغيل أمر التهيئة:Bash
npx heroui-cli@latest init
ستقوم واجهة سطر الأوامر الآن بإرشادك خلال عملية الإعداد. دعنا نحلل كل سؤال تسأله وما تعنيه خياراتك.
1. "ما النمط الذي ترغب في استخدامه؟"
- الخيارات:
Default
،New York
- الشرح: يحدد هذا الاختيار الجمالية الأساسية للمكونات.
Default
هو نمط أكثر حداثة وبساطة، بينما يقدمNew York
مظهرًا تقليديًا وشركاتيًا أكثر قليلاً. يؤثر هذا الاختيار بشكل أساسي على الأنماط الافتراضية، مثل نصف قطر الحدود والمسافات، التي ستقوم واجهة سطر الأوامر بإعدادها. أنت غير مقيد بهذا الاختيار؛ إنها مجرد نقطة انطلاق يمكن تخصيصها بالكامل لاحقًا. للحصول على لوحة نظيفة، غالبًا ما يكونDefault
خيارًا رائعًا.
2. "ما اللون الذي ترغب في استخدامه كلون أساسي؟"
- الخيارات:
Slate
،Gray
،Zinc
،Neutral
،Stone
- الشرح: نظام الألوان الكامل لـ HeroUI يعتمد على درجات لون أساسي محايد. يحدد هذا الاختيار اللوحة الأساسية للخلفيات، والنصوص، والحدود، وحالات المكونات. على سبيل المثال، اختيار
Slate
سيعطي واجهة المستخدم الخاصة بك لونًا رماديًا مائلًا إلى الأزرق، بينما سيوفرStone
شعورًا أكثر دفئًا وترابيًا. ستقوم واجهة سطر الأوامر تلقائيًا بإنشاء طيف كامل من متغيرات CSS بناءً على اختيارك.
3. "أين ملف CSS العام الخاص بك؟"
- الافتراضي:
app/globals.css
(لموجه تطبيق Next.js) أوstyles/globals.css
(لموجه الصفحات). - الشرح: تحتاج واجهة سطر الأوامر إلى معرفة أين يتم حقن متغيرات CSS الأساسية وتوجيهات Tailwind. عادة ما تكون ذكية بما يكفي لاكتشاف المسار الصحيح في مشروع Next.js قياسي. يجب عليك تغيير هذا فقط إذا كان لديك هيكل مشروع غير قياسي.
4. "هل تريد استخدام متغيرات CSS للألوان؟"
- الافتراضي:
Yes
- الشرح: يجب أن تقول نعم دائمًا تقريبًا. استخدام متغيرات CSS هو حجر الزاوية في نظام تسمية HeroUI. يسمح لك بتعريف لوحة الألوان الخاصة بك في مكان واحد (
globals.css
) وتطبيقها تلقائيًا في كل مكان. والأهم من ذلك، هذا ما يجعل الميزات الديناميكية مثل الوضع الداكن ممكنة.
5. "أين ملف tailwind.config.js
الخاص بك؟"
- الافتراضي:
tailwind.config.js
- الشرح: تحتاج واجهة سطر الأوامر إلى تعديل تكوين Tailwind الخاص بك لدمج إعدادات سمة HeroUI المسبقة والإضافات. مرة أخرى، يجب أن تكتشف هذا تلقائيًا.
6. "تكوين اسم مستعار للاستيراد للمكونات:"
- الافتراضي:
@/components
- الشرح: الأسماء المستعارة للمسارات هي أفضل ممارسة لبيانات الاستيراد النظيفة. بدلاً من كتابة
import { Button } from '../../../components/ui/button'
، يمكنك كتابةimport { Button } from '@/components/ui/button'
. تحتاج واجهة سطر الأوامر إلى معرفة الاسم المستعار الذي تريد استخدامه للمكونات حتى تتمكن من تكوينه في ملفtsconfig.json
(أوjsconfig.json
). الافتراضي@/components
هو خيار معقول.
7. "تكوين اسم مستعار للاستيراد للأدوات المساعدة:"
- الافتراضي:
@/lib/utils
- الشرح: يعتمد HeroUI على بعض وظائف الأدوات المساعدة، وأبرزها وظيفة لدمج فئات Tailwind بشكل شرطي (غالبًا ما تسمى
cn
). ستقوم واجهة سطر الأوامر بإنشاء ملف الأداة المساعدة هذا لك وتحتاج إلى معرفة أين تضعه وما هو الاسم المستعار الذي يجب استخدامه. الافتراضي@/lib/utils
هو قياسي.
8. "هل تستخدم مكونات خادم React؟"
- الافتراضي: سيتم الكشف عنه تلقائيًا بناءً على إصدار Next.js والإعداد الخاص بك.
- الشرح: هذا أمر بالغ الأهمية لتطبيقات Next.js الحديثة التي تستخدم موجه التطبيق. الإجابة بـ
Yes
تضمن أن المكونات التي تضيفها واجهة سطر الأوامر تتضمن توجيه"use client"
عند الضرورة. يحدد هذا التوجيه المكونات التي تتطلب تفاعلية من جانب العميل (مثل التعامل مع أحداثonClick
أو استخدام خطافات مثلuseState
)، مما يجعلها متوافقة مع مكونات خادم React.
بمجرد الإجابة على جميع الأسئلة، ستقوم واجهة سطر الأوامر بأداء سحرها. ستقوم بما يلي:
- تثبيت التبعيات اللازمة (
tailwindcss-animate
،class-variance-authority
،lucide-react
، إلخ). - إنشاء ملف
components.json
في جذر مشروعك. - تعديل ملف
tailwind.config.js
الخاص بك بإعدادات السمة الصحيحة. - ملء ملف
globals.css
الخاص بك بالأنماط الأساسية وجميع متغيرات CSS لسمة الألوان التي اخترتها. - تحديث ملف
tsconfig.json
أوjsconfig.json
الخاص بك بالأسماء المستعارة للمسارات التي قمت بتكوينها. - إنشاء ملف
lib/utils.ts
مع وظيفة الأداة المساعدةcn
.
مشروعك الآن تم تكوينه بالكامل وجاهز لـ HeroUI.
تشريح التغييرات
دعنا نلقي نظرة فاحصة على الملفات الرئيسية التي قامت واجهة سطر الأوامر بتعديلها أو إنشائها.
components.json
هذا الملف هو البيان الخاص بـ HeroUI داخل مشروعك. يخزن الخيارات التي اخترتها أثناء عملية init
ويخبر واجهة سطر الأوامر بكيفية تكوين مشروعك.JSON
{
"style": "default",
"rsc": true,
"tsx": true,
"tailwind": {
"config": "tailwind.config.js",
"css": "app/globals.css",
"baseColor": "slate",
"cssVariables": true
},
"aliases": {
"utils": "@/lib/utils",
"components": "@/components"
}
}
نادرًا ما تحتاج إلى تعديل هذا الملف يدويًا، ولكن من المفيد فهم الغرض منه. إنه العقل وراء عمليات واجهة سطر الأوامر.
tailwind.config.js
سيتم توسيع تكوين Tailwind الخاص بك ليبدو شيئًا كهذا. الإضافات الرئيسية هي امتدادات theme
وإضافة tailwindcss-animate
.JavaScript
/** @type {import('tailwindcss').Config} */
module.exports = {
darkMode: ["class"],
content: [
'./pages/**/*.{ts,tsx}',
'./components/**/*.{ts,tsx}',
'./app/**/*.{ts,tsx}',
'./src/**/*.{ts,tsx}',
],
theme: {
container: {
center: true,
padding: "2rem",
screens: {
"2xl": "1400px",
},
},
extend: {
colors: {
border: "hsl(var(--border))",
input: "hsl(var(--input))",
// ... والعديد من تعريفات الألوان الأخرى المرتبطة بمتغيرات CSS
primary: {
DEFAULT: "hsl(var(--primary))",
foreground: "hsl(var(--primary-foreground))",
},
// ...
},
borderRadius: {
lg: "var(--radius)",
md: "calc(var(--radius) - 2px)",
sm: "calc(var(--radius) - 4px)",
},
keyframes: {
// ... keyframes للرسوم المتحركة
},
animation: {
// ... أدوات الرسوم المتحركة المساعدة
},
},
},
plugins: [require("tailwindcss-animate")],
}
لاحظ كيف أن الألوان مثل primary
ليست معرفة برمز سداسي عشري ولكن بـ hsl(var(--primary))
. هذا يخبر Tailwind باستخدام متغير CSS المسمى --primary
، والذي يتم تعريفه في ملف CSS العام الخاص بك.
app/globals.css
هذا الملف الآن هو قلب سمة نظام التصميم الخاص بك. سيحتوي على توجيهات Tailwind الأساسية وكتلة كبيرة من متغيرات CSS.CSS
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--card: 0 0% 100%;
/* ... العديد من المتغيرات الأخرى للسمة الفاتحة */
--radius: 0.5rem;
}
.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
--card: 222.2 84% 4.9%;
/* ... العديد من المتغيرات الأخرى للسمة الداكنة */
}
}
هنا يمكنك رؤية قوة هذا الإعداد. يتم تعريف جميع ألوان السمة الفاتحة في نطاق :root
، ويتم تعريف جميع ألوان السمة الداكنة داخل نطاق فئة .dark
. عندما يتم إضافة فئة .dark
إلى عنصر <html>
، سيستخدم المتصفح تلقائيًا متغيرات السمة الداكنة.
الجزء الثالث: إتقان التخصيص - التسمية، التخطيط، والوضع الداكن
مع تهيئة HeroUI، تبدأ المتعة الحقيقية: جعله خاصًا بك. تم تصميم البنية بشكل صريح للتخصيص العميق والبديهي.
فن التسمية باستخدام متغيرات CSS
التسمية في HeroUI تختلف عن كائنات السمة المعقدة القائمة على JavaScript التي قد تجدها في مكتبات أخرى. إنها أبسط، وأكثر قوة، وتستفيد من ميزات CSS الحديثة. يتم التحكم في السمة بأكملها - الألوان، نصف قطر الحدود، الخطوط - بواسطة متغيرات CSS المعرفة في ملف globals.css
الخاص بك.
تغيير الألوان
لنفترض أنك تريد تغيير لون علامتك التجارية الأساسي. لا تحتاج إلى الدخول إلى تكوين Tailwind. ما عليك سوى العثور على متغيرات CSS ذات الصلة في globals.css
وتغيير قيمها.
يتم تعريف الألوان باستخدام قيم HSL (Hue, Saturation, Lightness)، ولكن بدون غلاف hsl()
. على سبيل المثال:CSS
:root {
/* ... */
--primary: 221.2 83.2% 53.3%;
--primary-foreground: 210 40% 98%;
/* ... */
}
.dark {
/* ... */
--primary: 217.2 91.2% 59.8%;
--primary-foreground: 210 40% 98%;
/* ... */
}
لتغيير لونك الأساسي إلى أخضر نابض بالحياة، يمكنك استخدام أداة اختيار ألوان عبر الإنترنت للعثور على قيم HSL للدرجة التي اخترتها وتحديث المتغيرات:CSS
/* في globals.css */
:root {
/* ... */
--primary: 142.1 76.2% 36.3%; /* لون أساسي أخضر جديد */
--primary-foreground: 355.7 100% 97.3%; /* لون فاتح متباين للنص على اللون الأساسي */
/* ... */
}
.dark {
/* ... */
--primary: 142.1 70.2% 46.3%; /* أخضر مختلف قليلاً للوضع الداكن */
--primary-foreground: 355.7 100% 97.3%;
/* ... */
}
بمجرد حفظ هذا الملف، سيتم تحديث كل مكون يستخدم اللون "primary" (مثل <Button>
) على الفور عبر تطبيقك بأكمله ليعكس هذا اللون الأخضر الجديد. هذا قوي بشكل لا يصدق.
تغيير نصف قطر الحدود
يتم التحكم في استدارة الزوايا على المكونات مثل البطاقات والمدخلات بواسطة متغير CSS واحد: --radius
.CSS
/* في globals.css */
:root {
/* ... */
--radius: 0.5rem; /* القيمة الافتراضية */
}
إذا كنت تفضل مظهرًا أكثر حدة ومربعة، يمكنك تقليل هذه القيمة:CSS
:root {
--radius: 0.25rem; /* أقل استدارة */
}
أو، للحصول على جمالية ناعمة جدًا ومستديرة، يمكنك زيادتها:CSS:root { --radius: 1.5rem; /* مستدير جدا */ }
سيؤدي هذا التغيير في سطر واحد إلى الانتشار عبر جميع مكوناتك، مما يضمن نصف قطر حدود متناسقًا عبر واجهة المستخدم بأكملها.
إضافة ألوان جديدة
أنت لست مقيدًا بالألوان التي يوفرها أمر init
. يمكنك بسهولة إضافة ألوانك الدلالية الخاصة. على سبيل المثال، دعنا نضيف لون علامة تجارية "خاص".
تعريف متغيرات CSS في globals.css
:CSS
/* في globals.css */
:root {
/* ... */
--special: 320 86% 59%;
--special-foreground: 330 100% 98%;
}
.dark {
/* ... */
--special: 320 80% 69%;
--special-foreground: 330 100% 98%;
}
كشفها لـ Tailwind في tailwind.config.js
:JavaScript
// في tailwind.config.js
// ...
extend: {
colors: {
// ...
special: {
DEFAULT: "hsl(var(--special))",
foreground: "hsl(var(--special-foreground))",
},
},
},
// ...
الآن يمكنك استخدام هذه الألوان في مكوناتك مع فئات الأدوات المساعدة لـ Tailwind، مثل bg-special
وtext-special-foreground
.
بناء تخطيطات متجاوبة
تم بناء مكونات HeroUI باستخدام Tailwind CSS، مما يعني أنها متجاوبة بطبيعتها. يمكنك استخدام بادئات الاستجابة لـ Tailwind (sm:
، md:
، lg:
، xl:
) على أي فئة أداة مساعدة لتغيير نمط المكون بأحجام شاشات مختلفة.
دعنا نتخيل بناء تخطيط صفحة بسيط مع شريط جانبي مرئي على سطح المكتب ولكنه ينهار على الهاتف المحمول. بينما يوفر HeroUI المكونات منخفضة المستوى (Card
، Button
)، فأنت مسؤول عن تجميعها في تخطيط أكبر.
إليك مثال لكيفية هيكلة هذا في مكون صفحة Next.js:TypeScript
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
export default function DashboardPage() {
return (
<div className="flex min-h-screen flex-col md:flex-row">
{/* الشريط الجانبي */}
<aside className="w-full border-b bg-muted p-4 md:w-64 md:border-b-0 md:border-r">
<h2 className="text-lg font-semibold">التنقل</h2>
<nav className="mt-4 flex flex-row space-x-2 md:flex-col md:space-x-0 md:space-y-2">
<Button variant="ghost" className="justify-start">لوحة التحكم</Button>
<Button variant="ghost" className="justify-start">الإعدادات</Button>
<Button variant="ghost" className="justify-start">الملف الشخصي</Button>
</nav>
</aside>
{/* المحتوى الرئيسي */}
<main className="flex-1 p-8">
<h1 className="text-4xl font-bold tracking-tight">لوحة التحكم</h1>
<p className="mt-2 text-muted-foreground">
مرحبًا بك في لوحة التحكم الخاصة بك.
</p>
<div className="mt-8 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
<Card>
<CardHeader>
<CardTitle>الإيرادات</CardTitle>
</CardHeader>
<CardContent>
<p className="text-3xl font-bold">$45,231.89</p>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>الاشتراكات</CardTitle>
</CardHeader>
<CardContent>
<p className="text-3xl font-bold">+2350</p>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>المستخدمون النشطون</CardTitle>
</CardHeader>
<CardContent>
<p className="text-3xl font-bold">+573</p>
</CardContent>
</Card>
</div>
</main>
</div>
);
}
في هذا المثال:
- الحاوية الرئيسية هي حاوية
flex
. على الهاتف المحمول (flex-col
)، يكون الشريط الجانبي في الأعلى. على الشاشات المتوسطة وما فوق (md:flex-row
)، يتحول إلى تخطيط جنبًا إلى جنب. - الـ
aside
له عرض كامل على الهاتف المحمول (w-full
) ولكن عرض ثابت على سطح المكتب (md:w-64
). - تستخدم منطقة المحتوى الرئيسية تخطيط
grid
يقوم بضبط عدد الأعمدة بناءً على حجم الشاشة (sm:grid-cols-2
،lg:grid-cols-3
).
هذا يوضح المبدأ الأساسي: يوفر HeroUI البدائيات المنسقة (Card
، Button
)، وأنت تستخدم القوة الكاملة لـ Tailwind CSS لترتيبها في تخطيطات متجاوبة ومعقدة.
تطبيق الوضع الداكن المثالي
إحدى أكثر ميزات HeroUI أناقة هي دعمها المدمج للوضع الداكن. نظرًا لأن أمر init
قد أعد بالفعل متغيرات الألوان لكل من السمة الفاتحة (:root
) والداكنة (.dark
)، فإن تطبيقها بسيط بشكل مدهش.
النهج الأكثر شيوعًا هو استخدام حزمة next-themes
، التي تتعامل مع تبديل السمة وتحفظ اختيار المستخدم في التخزين المحلي.
تثبيت next-themes
:Bash
npm install next-themes
إنشاء موفر سمة:
أنشئ ملفًا جديدًا، على سبيل المثال، في components/theme-provider.tsx.TypeScript
"use client";
import * as React from "react";
import { ThemeProvider as NextThemesProvider } from "next-themes";
import { type ThemeProviderProps } from "next-themes/dist/types";
export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
}
لف تخطيط الجذر الخاص بك بالموفر:
في تخطيط الجذر لـ Next.js (app/layout.tsx)، قم باستيراد واستخدام ThemeProvider.TypeScript
import { ThemeProvider } from "@/components/theme-provider";
import type { Metadata } from "next";
import { Inter } from "next/next/font/google";
import "./globals.css";
const inter = Inter({ subsets: ["latin"] });
export const metadata: Metadata = {
title: "Create Next App",
description: "Generated by create next app",
};
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html lang="en" suppressHydrationWarning>
<body className={inter.className}>
<ThemeProvider
attribute="class"
defaultTheme="system"
enableSystem
disableTransitionOnChange
>
{children}
</ThemeProvider>
</body>
</html>
);
}
الخصائص الرئيسية هنا هي:
attribute="class"
: يخبرnext-themes
بتبديل السمات عن طريق إضافة/إزالة فئة إلى عنصر<html>
.defaultTheme="system"
: يقوم تلقائيًا بتعيين السمة بناءً على تفضيل نظام تشغيل المستخدم.enableSystem
: يتيح خيار السمة "system".
إنشاء زر تبديل السمة:
الآن، تحتاج فقط إلى عنصر واجهة مستخدم للسماح للمستخدم بتبديل السمات.TypeScript
"use client";
import * as React from "react";
import { Moon, Sun } from "lucide-react";
import { useTheme } from "next-themes";
import { Button } from "@/components/ui/button";
export function ModeToggle() {
const { setTheme, theme } = useTheme();
const toggleTheme = () => {
setTheme(theme === "light" ? "dark" : "light");
};
return (
<Button variant="outline" size="icon" onClick={toggleTheme}>
<Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
<Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
<span className="sr-only">تبديل السمة</span>
</Button>
);
}
يستخدم هذا1 المكون خطاف useTheme
من next-themes
للتحقق من السمة الحالية وتعيين سمة جديدة. توفر أيقونات الشمس والقمر الدوارة انتقالًا بصريًا لطيفًا. ما عليك سوى وضع مكون <ModeToggle />
هذا في مكان ما في واجهة المستخدم الخاصة بك (مثل رأس الصفحة)، وسيكون لديك تبديل وضع داكن وظيفي بالكامل ومستمر.
الجزء الرابع: واجهة سطر الأوامر HeroUI وسير عملها المتمحور حول المكونات
heroui-cli
هي أكثر من مجرد مثبت. إنها الأداة الأساسية التي ستستخدمها لإدارة وتنمية مكتبة المكونات الخاصة بك. غرضها الرئيسي بعد التهيئة هو إضافة مكونات جديدة إلى مشروعك.
إضافة المكونات: سير العمل الأساسي
لنفترض أنك بحاجة إلى نافذة حوار منبثقة لتطبيقك. بدلاً من كتابة واحدة من الصفر، يمكنك أن تطلب من واجهة سطر الأوامر إضافة مكون Dialog
المدمج والمتاح من HeroUI.
الأمر بسيط:Bash
npx heroui-cli@latest add dialog
ستقوم واجهة سطر الأوامر بالإجراءات التالية:
- تقرأ ملف
components.json
الخاص بك لفهم هيكل مشروعك (الأسماء المستعارة للمسارات، استخدام TypeScript، إلخ). - تجلب أحدث كود مصدري لمكون
Dialog
وأي من تبعياته (على سبيل المثال، قد يعتمدDialog
علىButton
). - تضع ملفات المكونات مباشرة في دليل المكونات الخاص بك، على سبيل المثال:
components/ui/dialog.tsx
. - ستبلغك بأي تبعيات أخرى قد تحتاج إلى تثبيتها.
الآن، لديك ملف dialog.tsx
في مشروعك. يمكنك فحص الكود الخاص به، والتعلم منه، وحتى تعديله. إذا كان Dialog
الافتراضي يحتوي على انتقال لا يعجبك، يمكنك ببساطة فتح الملف وتغيير فئات Tailwind التي تتحكم في الرسوم المتحركة. هذا المستوى من التحكم هو حجر الزاوية في تجربة HeroUI.
يمكنك إضافة مكونات متعددة في وقت واحد:Bash
npx heroui-cli@latest add card button input label
سيضيف هذا الأمر جميع المكونات الأربعة وتبعاتها إلى مشروعك دفعة واحدة.
فهم واجهة برمجة تطبيقات CLI: components.json
ملف components.json
هو العقد بين مشروعك وواجهة سطر الأوامر HeroUI. دعنا نراجع خصائصه لفهم كيف تؤثر على سلوك واجهة سطر الأوامر.
style
: يذكر واجهة سطر الأوامر بالنمط الأساسي (default
أوnew-york
) الذي يجب استخدامه عند جلب كود المكونات، مما يضمن الاتساق الأسلوبي.rsc
: يحدد ما إذا كان يجب على واجهة سطر الأوامر إضافة توجيه"use client"
إلى المكونات. هذا أمر بالغ الأهمية لتوافق موجه تطبيق Next.js.tsx
: يخبر واجهة سطر الأوامر ما إذا كان يجب جلب إصدارات TypeScript (.tsx
) أو JavaScript (.jsx
) من ملفات المكونات.tailwind
:config
: المسار إلى ملفtailwind.config.js
الخاص بك. قد تحتاج واجهة سطر الأوامر إلى هذا للتحديثات المستقبلية أو التحليل.css
: المسار إلى ملف CSS العام الخاص بك حيث يتم تخزين المتغيرات.baseColor
: لوحة الألوان المحايدة التي اخترتها أثناءinit
.cssVariables
: يؤكد أن مشروعك معد لاستخدام متغيرات CSS للتسمية.aliases
:utils
: يحدد مسار الاستيراد للأدوات المساعدة المشتركة مثل وظيفةcn
. عندما تضيف واجهة سطر الأوامر مكونًا يحتاج إلى هذه الأداة المساعدة، ستستخدم هذا الاسم المستعار في بيان الاستيراد.components
: يحدد مسار الاستيراد لمكونات واجهة المستخدم نفسها. يسمح هذا للمكونات باستيراد مكونات أخرى (على سبيل المثال، قد يستوردDialog
مكونButton
) باستخدام مسار نظيف ومتناسق.
من خلال فهم هذا التكوين، يمكنك حتى ضبط سلوك واجهة سطر الأوامر يدويًا إذا قررت إعادة هيكلة هيكل مشروعك، على سبيل المثال، عن طريق نقل دليل المكونات الخاص بك من @/components
إلى @/ui
.
الخلاصة: ابنِ طريقك مع HeroUI
يمثل HeroUI تحولًا كبيرًا في كيفية تفكير المطورين في مكتبات واجهة المستخدم واستخدامها. إنه يبتعد عن نموذج "مقاس واحد يناسب الجميع"، "الصندوق الأسود" ويتجه نحو تجربة مطور شفافة، تمكينية، وقابلة للتخصيص بعمق. من خلال توفير مكونات غير منسقة، ومتاحة مباشرة ككود مصدري، فإنه يحقق التوازن المثالي بين التطوير السريع والتصميم المخصص.
نقاط القوة الأساسية لـ HeroUI واضحة:
- الملكية المطلقة: المكونات هي الكود الخاص بك. يمكنك تعديلها، توسيعها، وتكييفها دون قيود.
- تخصيص عميق: نظام تسمية قوي يعتمد على متغيرات CSS يجعل من السهل تغيير الألوان، المسافات، ونصف الأقطار عبر تطبيقك بأكمله.
- بنية حديثة: تم بناؤه باستخدام TypeScript، Tailwind CSS، ودعم من الدرجة الأولى لـ Next.js ومكونات خادم React، إنها أداة مصممة لمستقبل تطوير الويب.
- أدوات صديقة للمطور: واجهة سطر الأوامر الذكية تقوم بأتمتة عملية الإعداد المملة وتجعل إضافة مكونات جديدة تجربة سلسة.
HeroUI مخصص للبناة، والحرفيين، والفرق التي تعتقد أن واجهة المستخدم الخاصة بها هي جزء أساسي من هوية منتجها. لا يمنحك منزلًا جاهزًا؛ بل يمنحك أعلى جودة من المواد وورشة عمل منظمة تمامًا لبناء منزل أحلامك. لمشروعك القادم الذي يتطلب واجهة أمامية فريدة، مصقولة، وقابلة للصيانة، لا تبحث أبعد من HeroUI. قد تكون الأداة التي تمكنك من بناء واجهة المستخدم الأكثر بطولية حتى الآن.
هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى قدر من الإنتاجية؟
يلبي Apidog جميع متطلباتك، ويحل محل Postman بسعر أقل بكثير!