@x-app/nuxt-toast

@x-app/nuxt-toast

نظام إشعارات Toast لمشاريع Nuxt 3 وNuxt 4.

التثبيت والإعداد

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

أضف CSS والموديولين إلى nuxt.config.ts:

export default defineNuxtConfig({
  css: ["@x-app/easy-css/dist/easy-css.css"],
  modules: ["@nuxt/icon", "@x-app/nuxt-toast"],
});

يُسجل الموديول المكوّن <ToastHost /> والـcomposable useToast() تلقائيًا. أضف المضيف مرة واحدة إلى app.vue أو التخطيط العام:

<template>
  <NuxtPage />
  <ToastHost />
</template>

الاستخدام

<script setup lang="ts">
const toast = useToast();

async function save() {
  const id = await toast.success("تم الحفظ بنجاح", { title: "اكتمل" });
  if (!id) return; // أُلغي الإشعار بواسطة toast:before
}
</script>

<template>
  <button @click="toast.info('لديك تحديث جديد')">عرض إشعار</button>
</template>

الدوال المتاحة هي show, success, error, warning, info, dismiss, وclear. تقبل دوال الإظهار رسالة وخيارات اختيارية: type, position, title, icon, duration, وdismissible. القيمة duration: 0 تبقي الإشعار حتى إغلاقه يدويًا.

موضع الإشعار

الموضع الافتراضي هو top-center. يمكن تغييره لكل التطبيق من إعداد Nuxt، أو تجاوزه لإشعار بعينه:

export default defineNuxtConfig({
  xAppToast: { position: "bottom-right" },
});

await useToast().success("تم الحفظ", { position: "top-left" });

المواضع المدعومة: top-left, top-center, top-right, bottom-left, bottom-center, وbottom-right. تشير left وright إلى جانبي الشاشة الفعليين حتى عند استخدام RTL.

Hook ما قبل الإضافة

يُطلق الموديول hook باسم toast:before قبل إضافة الإشعار إلى الطابور. ألغِ الإضافة باستدعاء cancel():

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook("toast:before", ({ toast, cancel }) => {
    if (toast.message.includes("محتوى محظور")) cancel();
  });
});

يمكن للمستمع أن يكون غير متزامن. تعيد دوال الإظهار معرّف الإشعار عند إضافته، أو سلسلة فارغة إذا كانت الرسالة فارغة أو ألغي الإشعار.

يُطلق hook باسم toast:shown عندما يصبح الإشعار نشطًا في المضيف. استخدمه لربط سلوك التطبيق مثل الاهتزاز أو التحليلات:

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook("toast:shown", ({ toast }) => {
    console.info("ظهر إشعار من النوع:", toast.type);
  });
});

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

npm install
npm run build

يبني الأمر ملفات dist التي تُضمّن عند النشر. لتجربة الموديول محليًا:

cd playground
npm install
npm run dev