تثبيت الأيقونات في React أو shadcn/ui
تم رسم المجموعة على نفس شبكة 24×24 وبنفس سمك الخط (2px) الذي تفترضه إعدادات shadcn/ui الافتراضية، لذا يمكنك إضافتها مباشرة دون الحاجة لتعديل مكوناتك.
نسخ أيقونة واحدة
أسرع طريقة، ولا تحتاج إلى تثبيت. انقر على أي أيقونة في المتصفح وسيتم نسخ الـ SVG الخاص بها إلى الحافظة، بالحجم وسمك الخط الذي حددته. قم بلصقها مباشرة في المكون الخاص بك.
تأخذ كل رسمة لونها من currentColor، لذا فهي ترث أي text-* في النطاق ولا تحتاج إلى إضافة خصائص التعبئة أو الحدود بنفسك.
تثبيت حزمة React
كل أيقونة هي أيضاً مكون React، تم إنشاؤها من نفس ملفات الـ SVG.
npm i @keyline-icons/reactimport { Check, Plus, Settings } from "@keyline-icons/react"
<Check className="size-4" />
<Plus size={16} />
<Settings strokeWidth={1.5} />التثبيت باستخدام shadcn CLI
تم إدراج المجموعة في سجل shadcn، لذا يتعرف CLI على @keyline مسبقاً. أضف الأيقونات بالاسم:
npx shadcn add @keyline/bell
npx shadcn add @keyline/fill/bell # أي نمط غير الخطي يتم إضافة بادئة له
npx shadcn add @keyline/sharp/fill/bell # الزوايا الحادة تسبق المسار
npx shadcn search @keyline # تصفح المجموعة بأكملهاأي مشروع shadcn يحتوي بالفعل على components.json، وهذا التثبيت يحتاجه: يتم إضافة كل أيقونة إلى @components/icons/<name>.tsx، واسم المستعار هو ما يضعها في المكان الذي تحتفظ فيه بمكوناتك عادة. في حال عدم وجود الملف، سيقترح CLI تشغيل init أولاً.
في إصدارات CLI الأقدم التي لا تقرأ السجل، أضف الرابط إلى ملف components.json الخاص بك بنفسك:
"registries": {
"@keyline": "https://keylineicons.com/r/{name}.json"
}هذا المسار يمنحك الكود المصدري بدلاً من الاعتماد على حزمة خارجية. يتم إضافة كل أيقونة كمكون مستقل لا يستورد أي شيء من @keyline-icons/react، لذا يمكنك إعادة تسميته أو تعديل الرسمة أو دمجه مع أي إعدادات خاصة بمشروعك.
أي الطريقتين تختار يعتمد على الملكية بدلاً من الحجم. استخدم الحزمة إذا كنت تريد المجموعة بأكملها تحت استيراد واحد وترغب في استلام التحديثات مع كل إصدار جديد. واستخدم السجل إذا كنت تريد عدداً قليلاً من الأيقونات وتفضل امتلاك الملفات بدلاً من تتبع تحديثات خارجية.
Vue و Svelte وكل شيء آخر
المجموعة بأكملها منشورة على Iconify (يفتح في نافذة جديدة) باسم keyline-icons، وعددها ٨٬٠٠٠ رسمة، وهي الطريقة التي تستخدمها بقية الأطر للحصول عليها. تقوم Iconify باستيراد الأيقونات من المستودع مباشرة، لذا فهي تحتوي دائماً على أحدث التعديلات.
npm i @iconify/vue # Vue 3
npm i @iconify/svelte # Svelte 5import { Icon } from "@iconify/vue" // تصدير مُسمى
import Icon from "@iconify/svelte" // تصدير افتراضي
<Icon icon="keyline-icons:bell" />
<Icon icon="keyline-icons:bell-fill" width="16" />
<Icon icon="keyline-icons:bell-sharp-two-tone" />في Iconify، الأسماء تحمل النمط بدلاً من المسار: النمط الخطي هو الاسم المجرد، وأي نمط آخر يتم إضافته كلاحقة. -two-tone، -duotone، -fill، -sharp، -sharp-two-tone، -sharp-duotone، -sharp-fill.
في أي بيئة لا تدعم حزم الأطر مثل Angular، Solid، و HTML العادي، يتوفر مكون ويب. أما بالنسبة للمشاريع التي لا تحتاج إلى أي خطوة بناء، فإن إضافة Tailwind تقوم بتحويل كل أيقونة إلى قناع (mask) مما يسمح لها بأخذ لون text-* مثل أي أيقونة هنا:
npm i iconify-icon
<iconify-icon icon="keyline-icons:bell"></iconify-icon>
npm i -D @iconify/tailwind4
@plugin "@iconify/tailwind4";
<span class="icon-[keyline-icons--bell] size-4"></span>لاحظ وجود الشرطة المزدوجة في فئة Tailwind. لا يسمح Tailwind باستخدام النقطتين داخل الأقواس، لذا تستخدم Iconify الفاصل -- هناك و : في كل مكان آخر.
تقوم هذه الطرق بجلب بيانات الأيقونات من واجهة Iconify عند الحاجة بدلاً من حزمها مع المشروع، وهذا هو الفرق بينها وبين حزمة React: لا يتم شحن شيء مع حزمة مشروعك، بل تصل الرسمة عبر الشبكة عند عرضها لأول مرة. كل طريقة منها تمتلك إصداراً للاستخدام دون اتصال إذا لم يكن هذا مناسباً لك.
تغيير الحجم داخل مكونات shadcn
تقوم مكونات shadcn/ui الأساسية بضبط حجم أيقوناتها بنفسها، ويقوم مكون الزر (Button) بذلك بناءً على شرط. الفئة الأساسية للزر هي [&_svg:not([class*='size-'])]:size-4، والتي تعني: اجعل أي SVG متداخل بحجم 16px ما لم يكن يحتوي بالفعل على فئة size-* خاصة به.
لذا توجد إجابتان، والتي ستحصل عليها تعتمد على كيفية تحديد الحجم:
<Button>
<Plus /> {/* 16px. المتغير ضبط الحجم. */}
<Plus size={32} /> {/* لا تزال 16px: الخاصية تحدد العرض كسمة (attribute) والفئة (class) تتغلب عليها. */}
<Plus className="size-6" /> {/* 24px. شرط :not() يُستبعد. */}
</Button>تختلف متغيرات الحجم على الرقم، وهو ما يستحق التحقق منه مع أزرارك الخاصة بدلاً من الافتراض: xs تعادل 12px، sm تعادل 14px، والافتراضي هو 16px. الأزرار أدناه من نوع sm لذا حجم الأيقونات بداخلها 14.
لا تتفق كل المكونات الأساسية، وهو أمر مهم يجب معرفته قبل محاولة إصلاحه. يحمل مكون DropdownMenu نفس شرط :not() الموجود في Button، لذا فئتك size-* تفوز هناك أيضاً. أما مكون Sidebar فلا يفعل ذلك: بل يستخدم [&>svg]:size-4 دون أي استثناء وعلى العنصر الابن المباشر فقط، لذا يتم تجاهل الفئة الخاصة بك هناك.
سمك الخط في الأحجام الصغيرة
تم رسم المجموعة بسمك وحدتين على شبكة 24، وهذا هو الحجم الذي تم اختبارها عليه ويجب أن تبقى عليه. وعند حجم 16px، تم التحقق من سمك الخط في جميع الرسومات، بما في ذلك تلك التي تطلب الأمر توسعتها للحفاظ على وضوحها.
الأوزان الأخف تعمل بشكل جيد للاستخدامات الزخرفية الكبيرة. لكن تحت حجم 16px تبدأ بتشويه الرسومات بدلاً من تحسينها، لأن الفراغات بين العناصر تم قياسها بناءً على خط رئيسي بسمك وحدتين.
الانتقال من lucide
تأتي مكتبة shadcn/ui مع أيقونات lucide بشكل افتراضي، وكلا المجموعتين تستخدمان مقاس 24×24 بخط رئيسي بسمك 2px وحدود currentColor، لذا فإن عملية الاستبدال تقتصر على تغيير الاستيراد (import) فقط دون الحاجة لتعديل الكود (markup). تم رسم هذا الموقع بالكامل باستخدام أيقوناته الخاصة، وهو ما يعكس عملية الانتقال بشكل كامل.
- import { Check, Menu } from "lucide-react"
+ import { Check, Menu } from "@keyline-icons/react"تتطابق الأسماء في الغالب، لأن كلتا المجموعتين تتبعان نفس النظام. في حال وجود اختلاف، فعادةً ما يكون في قراءة المركب ابتداءً من الكلمة الأساسية: مثل mail-check بدلاً من check-mail. ابحث في المتصفح عن الكلمة الأساسية للعثور على المجموعة المتعلقة بها.
فرق واحد في الخصائص (props) يستحق المعرفة: لا يوجد مكافئ لخاصية absoluteStrokeWidth الموجودة في lucide هنا. حيث يزداد سمك الخط (stroke) بتناسب مع حجم الأيقونة، وهذا ما يحافظ على مظهر الخط الأساسي المكبر كأنه مرسوم وليس مجرد خط رفيع (hairline).
أربعة أنماط، اسم واحد
تتوفر كل أيقونة بالأنماط الأربعة كلها. النمط الخطي (Stroke) هو الرسمة الأساسية. يحافظ النمط ثنائي الدرجات (Two-tone) على هذا الإطار فوق تعبئة بنسبة 40%، وهو ما كان يعنيه مصطلح duotone حتى الإصدار 0.9.0. أما نمط duotone الحديث فيلغي الإطار: يحتوي على جسم رمادي وتفاصيل باللون الأسود. ونمط التعبئة (Fill) يكون مصمتاً.
كل نمط له نقطة دخول منفصلة في الحزمة، لذا فإن التطبيق يضم فقط الأنماط التي يقوم باستيرادها. الأكواد التي استوردت نمط duotone قبل الإصدار 1.0.0 وترغب في المظهر ذو الإطار يجب أن تغير مسارها إلى two-tone. أما النمط ذو الزوايا الحادة فهو عبارة عن خطوة إضافية، ويسمى التصدير بنفس الاسم في كلا المسارين:
import { Bell } from "@keyline-icons/react" // stroke, 1,000
import { Bell } from "@keyline-icons/react/two-tone" // two-tone, 1,000
import { Bell } from "@keyline-icons/react/duotone" // duotone, 1,000
import { Bell } from "@keyline-icons/react/fill" // fill, 1,000
import { Bell } from "@keyline-icons/react/sharp" // sharp stroke, 1,000
import { Bell } from "@keyline-icons/react/sharp/two-tone" // sharp two-tone, 1,000
import { Bell } from "@keyline-icons/react/sharp/duotone" // sharp duotone, 1,000
import { Bell } from "@keyline-icons/react/sharp/fill" // sharp fill, 1,000إن استخدام اسم غير موجود يؤدي إلى خطأ أثناء عملية البناء (build error) بدلاً من عرض أيقونة فارغة، وهو الوقت الأفضل لاكتشاف المشكلة. تتوفر كافة الأنماط كملفات SVG عادية في المستودع (يفتح في نافذة جديدة).
الأسئلة الشائعة
إجابات مختصرة للمراجعة السريعة. تم تناول كل نقطة بالتفصيل في أقسام منفصلة أعلاه.
- هل أحتاج إلى تثبيت أي شيء لاستخدام أيقونة واحدة؟
- لا. متصفح الأيقونات ينسخ أي رسمة كـ SVG أو JSX بالحجم وسمك الخط الذي حددته، ولصقه في المكون الخاص بك يعتبر عملية التثبيت بالكامل. تأخذ كل رسمة لونها من currentColor، لذا لا تحتاج لخصائص التعبئة أو الحدود بنفسك.
- أي حزمة أقوم بتثبيتها لـ React؟
- حزمة @keyline-icons/react، والتي تنشئ مكوناً واحداً لكل أيقونة من ملفات SVG، لضمان تطابق الأيقونات تماماً. يمثل كل نمط مسار استيراد (import) منفصلاً، والرسومات موجودة أيضاً في icons/ في المستودع على github.com/keyline-icons/keyline-icons إذا كنت تفضل نسخها بدلاً من تثبيت الحزمة.
- لماذا يمتلك كل نمط مسار استيراد منفصل؟
- حتى يقوم التطبيق بحزم الأنماط التي يستوردها فقط. جميع الأيقونات تتوفر بكافة الأنماط الأربعة، ويحدد مسار الاستيراد المظهر: مسار @keyline-icons/react/two-tone يعطي الإطار فوق التعبئة، ومسار @keyline-icons/react/duotone يعطي الجسم الرمادي مع التفاصيل السوداء. الأكواد التي كانت تستورد /duotone قبل الإصدار 1.0.0 وترغب في المظهر القديم عليها تغيير المسار إلى /two-tone.
- كيف أقوم بتغيير حجم الأيقونة داخل زر shadcn/ui؟
- يحدد الزر حجم أيقونات SVG المتداخلة بداخله باستخدام القاعدة [&_svg:not([class*='size-'])]:size-4 والتي تعني: اجعل أي أيقونة متداخلة بحجم 16px إلا إذا كانت تحتوي على فئة size-. لذا فإن الأيقونة المجردة ستكون 16px، وسيتم تجاوز خاصية الحجم (size prop) من خلال هذه الفئة، وفئة className="size-6" هي التي تغير حجمها فعلياً. تستخدم مكونات Sidebar و DropdownMenu نفس القاعدة دون استثناء فئة الحجم، لذا فإن استخدام فئتك الخاصة لن يطبق هناك.
- ما هو سمك الخط (stroke width) الذي يجب عليّ استخدامه؟
- وحدتان (2)، وهو السمك الذي رُسمت واختُبرت به المجموعة على شبكة 24، بما في ذلك الحجم 16px حيث اضطررنا لتوسيع بعض الرسومات الدقيقة للحفاظ على جودتها. تستخدم الأوزان الأخف للأغراض الزخرفية الكبيرة؛ وما دون 16px فإنها تُشوه الرسومات بدلاً من تحسينها لأن الفراغات تم حسابها لتناسب خطاً أساسياً بسمكه وحدتان.
- كيف أقوم بالانتقال من أيقونات lucide؟
- قم بتغيير الاستيراد فقط. كلتا المجموعتين تأتيان بمقاس 24×24 مع خط بسمك 2px وحدود بلون currentColor، لذا فإن بنية الكود تبقى كما هي. خاصية واحدة ليس لها بديل هنا وهي: absoluteStrokeWidth. حيث يتم تكبير حجم الخط تلقائياً بالتناسب مع الأيقونة للحفاظ على تناسق التصميم.
- هل يمكنني استخدام المجموعة بدون React؟
- نعم، بطريقتين. تتوفر المجموعة على Iconify باسم keyline-icons، وبذلك تغطي حزم @iconify/vue و @iconify/svelte ومكون الويب iconify-icon كلاً من Vue و Svelte و Angular و Solid و HTML العادي، دون أن تكون تابعة لحزمنا. أو استخدم الملفات المباشرة: ملفات SVG الموجودة في icons/<style>/<name>.svg ضمن المستودع نظيفة وليس لها تغليفات أو معرّفات (ids) أو فئات برمجية للتعامل معها. تعامل معها كمخرجات للبناء: لتعديل أي رسمة قم بتغييرها في مجلد raw/ وأعد البناء.
- هل المجموعة مجانية للاستخدام التجاري؟
- نعم. تم إصدارها بموجب ترخيص MIT License، والذي يغطي الأعمال التجارية ومشاريع العملاء. يتطلب الترخيص إرفاق إشعار حقوق النشر مع نُسخ المجموعة ذاتها، وليس مع المنتجات التي تستخدم الأيقونات. ملف LICENSE الموجود في المستودع هو الاتفاقية الرسمية بهذا الشأن.
