@x-app/nuxt-inputs

مكوّنات إدخال قابلة لإعادة الاستخدام في مشاريع Nuxt 3 وNuxt 4.

التثبيت

npm install @x-app/nuxt-inputs @x-app/easy-css @nuxt/icon

الحزمة تعتمد على @x-app/easy-css، لذلك تُثبت تلقائياً كاعتماد مطلوب. يجب على المشروع المستهلك تحميل stylesheet الخاص بـ@x-app/easy-css حسب مسار الاستيراد الذي توفره تلك الحزمة.

إعداد Nuxt

أضف الموديول و@nuxt/icon إلى nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["@nuxt/icon", "@x-app/nuxt-inputs"],
});

المكوّنات تسجل تلقائياً ويمكن استخدامها مباشرة في القوالب. تستخدم InputText وInputPassword وInputCheckBox وInputSelect مكوّن <Icon>، لذلك يجب تهيئة @nuxt/icon في المشروع المستهلك.

استيراد يدوي

يمكن استيراد المكوّنات من مساراتها الفرعية عند عدم استخدام التسجيل التلقائي:

<script setup>
import InputText from "@x-app/nuxt-inputs/components/InputText";
import InputPassword from "@x-app/nuxt-inputs/components/InputPassword";
import InputSelect from "@x-app/nuxt-inputs/components/InputSelect";

const name = ref("");
const password = ref("");
const choice = ref(null);
const choices = [{ id: 1, name: "الخيار الأول" }];
</script>

<template>
  <InputText v-model="name" label="الاسم" />
  <InputPassword v-model="password" label="كلمة المرور" />
  <InputSelect v-model="choice" :items="choices" />
</template>

المسارات المتاحة هي InputText, InputPassword, InputTextarea, InputNumber, InputCheckBox, InputOnOff, InputSelect, InputDate, وInputTime.

المكوّنات وواجهاتها

| المكوّن | قيمة v-model | خصائص مميزة | | --- | --- | --- | | InputText | String \| Number | type, placeholder, icon, focus, required, error, size | | InputPassword | String \| Number | placeholder, icon, focus, required, error, size | | InputTextarea | String | rows, maxLength, focus, required, error, size | | InputNumber | Number \| null | min, max, step, decimal, placeholder, size | | InputCheckBox | Boolean | label, disabled, error, size | | InputOnOff | Boolean | label, disabled, size | | InputSelect | قيمة عنصر أو Array عند الاختيار المتعدد | items, keyName, keyId, multiple, type, iconOnly, required, error, size | | InputDate | YYYY-MM-DD أو سلسلة فارغة | minYear, maxYear, placeholderDay, placeholderMonth, placeholderYear, error, size | | InputTime | HH:mm أو سلسلة فارغة | mode (12 أو 24), placeholderTime, error, size |

جميع المكوّنات تدعم disabled، والمكوّنات ذات الأحجام تدعم sm وmd وlg. ترسل المكوّنات تغييرات النموذج عبر update:modelValue؛ ويرسل InputNumber أيضاً حدث blur.

الخصائص المشتركة

• v-model: القيمة الحالية؛ حدّثها من المكوّن الأب لتبقى الواجهة متزامنة.
• label: عنوان الحقل، حيثما كان مدعوماً.
• disabled: تعطيل الإدخال.
• error: نص الخطأ، ويظهر التنسيق المرتبط به في المكوّنات التي تدعمه.
• size: الحجم sm أو md أو lg، والقيمة الافتراضية md.

أمثلة الاستخدام

<script setup>
import { ref } from "vue";

const form = ref({
  name: "",
  notes: "",
  age: null,
  accepted: false,
  notifications: true,
  countryId: null,
  date: "",
  time: "",
});

const countries = [
  { id: 1, name: "السودان" },
  { id: 2, name: "مصر" },
];
</script>

<template>
  <InputText v-model="form.name" label="الاسم" placeholder="اكتب اسمك" />
  <InputTextarea v-model="form.notes" label="ملاحظات" :rows="4" :max-length="300" />
  <InputNumber v-model="form.age" label="العمر" :min="0" :max="120" />
  <InputCheckBox v-model="form.accepted" label="أوافق على الشروط" />
  <InputOnOff v-model="form.notifications" label="تفعيل التنبيهات" />
  <InputSelect v-model="form.countryId" :items="countries" label="الدولة" />
  <InputDate v-model="form.date" label="تاريخ الميلاد" />
  <InputTime v-model="form.time" label="وقت التذكير" mode="12" />
</template>

InputText

حقل نصي مفرد. الخاصية type تقبل نوع حقل HTML مثل text أو email أو password، وicon تقبل اسم أيقونة @nuxt/icon. الخاصية focus تركّز الحقل عند تفعيلها.

<InputText v-model="email" type="email" label="البريد الإلكتروني" placeholder="[email protected]" required />

InputPassword

حقل كلمة مرور مع زر عين للتبديل بين إظهار القيمة وإخفائها. يدعم الخصائص المشتركة مع InputText باستثناء type، لأن نوع الحقل يتغير من زر العين.

<InputPassword v-model="password" label="كلمة المرور" placeholder="أدخل كلمة المرور" required />

InputTextarea

حقل متعدد الأسطر يتكيّف ارتفاعه مع النص. استخدم rows للارتفاع الابتدائي وmax-length لتحديد عدد الأحرف وإظهار المتبقي. يدعم focus وrequired.

InputNumber

حقل رقمي مع زري زيادة ونقصان. يبدأ v-model عادةً بـnull. تحدد step مقدار التغيير، وتضبط min وmax الحدود. الأعداد الصحيحة هي الوضع الافتراضي؛ مرّر decimal للسماح بالكسور.

<InputNumber v-model="price" :min="0" :max="9999" :step="0.5" decimal label="السعر" />

InputCheckBox وInputOnOff

كلاهما يستخدم قيمة منطقية (true أو false). الأول مربع اختيار مع خاصية error، والثاني مفتاح تشغيل وإيقاف. كلاهما يقبل label وdisabled وsize.

InputSelect

تعرض القائمة عناصر من مصفوفة كائنات. افتراضياً تقرأ اسم العرض من name ومعرّف القيمة من id؛ غيّر ذلك عبر key-name وkey-id. قيمة v-model هي المعرّف المختار، أو مصفوفة معرّفات عند تفعيل multiple.

<InputSelect
  v-model="countryId"
  :items="countries"
  key-name="name"
  key-id="id"
  placeholder="اختر دولة"
  label="الدولة"
/>

<InputSelect v-model="tagIds" :items="tags" multiple label="الوسوم" />

تقبل أيضاً icon وicon-only لعرض زر أيقونة، وdropdown-width لتحديد عرض القائمة. الخاصية type تقبل single أو multi، لكن الاختيار المتعدد يُفعّل بواسطة multiple.

InputDate

يعرض قوائم اليوم والشهر والسنة، ويعيد سلسلة بالتنسيق YYYY-MM-DD. القيمة الفارغة تعني عدم اكتمال التاريخ. افتراضياً يبدأ نطاق السنوات من 1920 وينتهي بعد عشر سنوات من السنة الحالية؛ يمكن ضبطه عبر min-year وmax-year.

InputTime

يعرض عجلات عمودية للساعة والدقيقة، ويمكن تغيير القيم بالنقر على القيم المجاورة أو بالسحب للأعلى والأسفل. يعيد الوقت دائماً بصيغة 24 ساعة HH:mm حتى عند استخدام mode="12". الوضع 12 يعرض اختيار ص/م، أما 24 فيعرض ساعات اليوم كاملة. عند بدء القيمة فارغة، تعرض العجلات الوقت المحلي الحالي بعد تحميل المكوّن دون تحديث v-model حتى يغيّر المستخدم الاختيار.

عرض أخطاء التحقق

مرّر نص الخطأ إلى خاصية error في المكوّنات التي تدعمها، واربط required بالحقول المطلوبة عند الحاجة:

<InputText v-model="email" label="البريد الإلكتروني" required :error="emailError" />
<InputSelect v-model="countryId" :items="countries" required :error="countryError" />

<InputDate v-model="date" :min-year="2000" :max-year="2035" />
<InputTime v-model="time" mode="12" />
<InputNumber v-model="quantity" :min="0" :step="1" />
<InputCheckBox v-model="accepted" label="موافق" />

التطوير والبناء

لتشغيل صفحة التجربة التي تعرض جميع المكوّنات وتحدّث قيم v-model مباشرة:

npm run dev:playground

تعمل الصفحة على مكوّنات المصدر مباشرة، وتتيح تبديل حالة التعطيل والأخطاء. لبناء تطبيق التجربة استخدم npm run build:playground.

npm install
npm run build

يبني الأمر ملفات dist التي تُضمّن عند تجهيز الحزمة للنشر إلى npm.