إنشاء مكون ويب باستخدام SvelteKit: دليل شامل خطوة بخطوة

إنشاء مشروع SvelteKit لمكون ويب

لإنشاء مكون ويب باستخدام SvelteKit، ابدأ بتهيئة مشروع جديد:

npx sv create example-webcomponent
cd example-webcomponent
npm run dev

تهيئة المشروع

عند التثبيت، اختر الخيارات التالية:

• SvelteKit الحد الأدنى
• TypeScript
• Prettier و ESLint (موصى به)
• npm

تشغيل المشروع محليًا

بمجرد الانتهاء من التثبيت، افتح متصفحك على العنوان التالي:

http://localhost:5173/

إذا ظهرت الصفحة بشكل صحيح، فإن مشروع SvelteKit الخاص بك جاهز للاستخدام لإنشاء مكون ويب.

تثبيت SCSS في SvelteKit

لاستخدام SCSS في مشروع SvelteKit الخاص بك، يجب عليك تثبيت مترجم Sass كاعتماد للتطوير:

npm install -D sass-embedded

بعد التثبيت، سيتعرف SvelteKit تلقائيًا على SCSS في ملفاتك .svelte عبر العلامات <style lang="scss">.

إنشاء مكون ويب باستخدام SvelteKit

سنقوم الآن بإنشاء أول مكون ويب لدينا باستخدام SvelteKit. للقيام بذلك، أنشئ ملفًا في المجلد src/lib :

touch src/lib/my-web-component.svelte

ثم أضف الشيفرة التالية :

<svelte:options customElement="my-web-component" />

<script lang="ts">
</script>

<p>مرحبا بالعالم</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

👉 السمة customElement="my-web-component" تحدد اسم مكون الويب الخاص بك. يجب أن يحتوي هذا الاسم على شرطة (مثل: my-component) ليكون صالحًا في HTML.

تكوين SvelteKit لمكونات الويب

لتفعيل إنشاء مكونات الويب باستخدام SvelteKit، يجب عليك تعديل ملف svelte.config.js وتفعيل خيار customElement.

قم بإضافة التكوين التالي :

compilerOptions: {
  customElement: true
}

إليك مثال كامل للتكوين :

import adapter from '@sveltejs/adapter-static';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter()
  },
  vitePlugin: {
    dynamicCompileOptions: ({ filename }) =>
      filename.includes('node_modules') ? undefined : { runes: true }
  },
  compilerOptions: {
    customElement: true
  }
};

export default config;

👉 يسمح خيار customElement: true لـ SvelteKit بترجمة مكوناتك إلى مكونات ويب أصلية يمكن استخدامها في أي بيئة.

تكوين بناء مكون الويب باستخدام Vite

لتوليد مكون ويب قابل لإعادة الاستخدام، يجب عليك تكوين بناء محدد باستخدام Vite. هذا يسمح بتصدير مكونك على شكل ملف JavaScript يمكن استخدامه في أي مشروع.

قم بإنشاء ملف تكوين مخصص :

touch vite.config.webcomponent.js

أضف التكوين التالي :

import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { name, version } from './package.json';

export default defineConfig({
  plugins: [svelte()],
  publicDir: 'playground',
  build: {
    lib: {
      entry: './src/lib/my-web-component.svelte',
      fileName: `${name}-${version}`,
      name,
      formats: ['es']
    },
    outDir: 'static/webcomponent',
    minify: 'esbuild'
  }
});

إضافة سيناريو البناء

قم بإضافة السيناريو التالي في ملفك package.json :

"build:wc": "vite build -c vite.config.webcomponent.js"

بعد ذلك، يمكنك توليد مكون الويب الخاص بك باستخدام الأمر :

npm run build:wc

اختبار مكون الويب في SvelteKit

بمجرد إنشاء بناء المشروع، يمكنك اختبار مكون الويب مباشرة في مشروع SvelteKit الخاص بك.

استيراد البرنامج النصي

في ملف +page.svelte، أضف البرنامج النصي الذي تم إنشاؤه في وسم <svelte:head> :

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

استخدام مكون الويب

ثم أضف مكونك في القالب :

<my-web-component></my-web-component>

مثال كامل

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<h1>مرحبًا بك في SvelteKit</h1>
<p>
  زور <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> لقراءة الوثائق
</p>

<my-web-component></my-web-component>

تشغيل المشروع

نفذ الأوامر التالية :

npm run build:wc
npm run dev

إذا كانت كل الأمور مهيأة بشكل صحيح، يجب أن يظهر مكون الويب الخاص بك في الصفحة.

إضافة خصائص (props) إلى مكون الويب SvelteKit

يمكنك جعل مكون الويب الخاص بك ديناميكيًا من خلال تمرير خصائص (props) له.

تعريف خاصية في المكون

في ملفك my-web-component.svelte :

let { name = 'World' } = $props();

استخدام الخاصية في القالب

<p>مرحبًا {name}</p>

المكون الكامل

<svelte:options customElement="my-web-component" />

<script lang="ts">
  let { name = 'World' } = $props();
</script>

<p>مرحبًا {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

استخدام الخاصية في HTML

يمكنك الآن تمرير قيمة مباشرة من HTML :

<my-web-component name="Bryan"></my-web-component>

👉 النص المعروض سيكون : مرحبًا Bryan

عرض طرق JavaScript (API) في مكون ويب

يمكنك عرض طرق JavaScript للتفاعل مع مكون الويب الخاص بك من الخارج (JavaScript، إطار العمل، أو HTML).

في هذا المثال، سنقوم بإنشاء getter و setter لمعالجة خاصية name.

إنشاء الطرق

const getName = (): string => {
  return name;
};

const setName = (newName: string) => {
  name = newName;
};

عرض الطرق عبر مكون الويب

استخدم $host() لإرفاق الطرق بعنصر DOM:

$effect(() => {
  const host = $host();

  Object.assign(host, {
    getName,
    setName
  });
});

مكون كامل

<svelte:options customElement="my-web-component" />

<script lang="ts">
  let { name = 'World' } = $props();

  const getName = (): string => {
    return name;
  };

  const setName = (newName: string) => {
    name = newName;
  };

  $effect(() => {
    const host = $host();

    Object.assign(host, {
      getName,
      setName
    });
  });
</script>

<p>مرحبًا {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

استخدام الطرق من JavaScript

يمكنك الآن التفاعل مع مكون الويب الخاص بك من خلال نص خارجي:

const el = document.querySelector('my-web-component');

// تعديل القيمة
el.setName('Bryan');

// استرجاع القيمة
console.log(el.getName());

👉 هذه الطريقة تتيح إنشاء API JavaScript حقيقية لمكون الويب الخاص بك.

التفاعل مع عنصر ويب من SvelteKit

يمكنك التفاعل مباشرة مع عنصر الويب الخاص بك من SvelteKit عن طريق الوصول إلى أساليبه عبر مرجع JavaScript.

الإعلان عن مرجع إلى المكون

let wc: HTMLElement;

ربط عنصر الويب

استخدم bind:this لاسترجاع مرجع إلى المكون:

<my-web-component bind:this={wc} name="User"></my-web-component>

إضافة نوع TypeScript (موصى به)

لتجنب الأخطاء في IDE الخاص بك، يمكنك تحديد أنواع الأساليب المعرضة:

let wc: HTMLElement & {
  getName: () => string;
  setName: (newName: string) => void;
};

التفاعل مع المكون

يمكنك بعد ذلك استدعاء الأساليب في دورة الحياة onMount:

import { onMount } from 'svelte';

onMount(() => {
  console.log('الاسم الحالي:', wc.getName());

  setTimeout(() => {
    console.log('== تغيير الاسم ==');
    wc.setName('Admin');
    console.log('الاسم الحالي:', wc.getName());
  }, 1000);
});

مثال كامل

<script lang="ts">
  import { onMount } from 'svelte';

  let wc: HTMLElement & {
    getName: () => string;
    setName: (newName: string) => void;
  };

  onMount(() => {
    console.log('الاسم الحالي:', wc.getName());

    setTimeout(() => {
      console.log('== تغيير الاسم ==');
      wc.setName('Admin');
      console.log('الاسم الحالي:', wc.getName());
    }, 1000);
  });
</script>

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<h1>مرحبًا بكم في SvelteKit</h1>
<p>
  زر <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> لقراءة الوثائق
</p>

<my-web-component bind:this={wc} name="User"></my-web-component>

النتيجة في وحدة التحكم

الاسم الحالي: User
== تغيير الاسم ==
الاسم الحالي: Admin

👉 يتم تحديث عنصر الويب ديناميكيًا، والتغييرات مرئية في كل من DOM وفي وحدة التحكم.

استخدام السلاots في مكون ويب SvelteKit

تسمح السلاots بإدخال محتوى HTML من الخارج داخل مكون الويب الخاص بك. هذا ضروري لجعل المكون الخاص بك مرنًا وقابلًا لإعادة الاستخدام.

إضافة سلاot في المكون

في ملفك my-web-component.svelte، ببساطة أضف:

<slot />

تعديل القالب

على سبيل المثال، استبدل:

<p>Hello {name}</p>

ب:

<p>Before Hello {name}</p>
<slot />
<p>After Hello {name}</p>

المكون الكامل

<svelte:options customElement="my-web-component" />

<script lang="ts">
  let { name = 'World' } = $props();

  const getName = (): string => {
    return name;
  };

  const setName = (newName: string) => {
    name = newName;
  };

  $effect(() => {
    const host = $host();

    Object.assign(host, {
      getName,
      setName
    });
  });
</script>

<p>Before Hello {name}</p>
<slot />
<p>After Hello {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

تمرير المحتوى من صفحة SvelteKit

يمكنك الآن إدخال محتوى مباشرة في مكون الويب الخاص بك:

<my-web-component bind:this={wc} name="User">
  <p>محتوى جديد</p>
</my-web-component>

مثال كامل في SvelteKit

<script lang="ts">
  import { onMount } from 'svelte';

  let wc: HTMLElement & {
    getName: () => string;
    setName: (newName: string) => void;
  };

  onMount(() => {
    console.log('Current Name:', wc.getName());

    setTimeout(() => {
      console.log('== تغيير الاسم ==');
      wc.setName('Admin');
      console.log('Current Name:', wc.getName());
    }, 1000);
  });
</script>

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<h1>مرحبًا بك في SvelteKit</h1>
<p>
  زيارة <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> لقراءة الوثائق
</p>

<my-web-component bind:this={wc} name="User">
  <p>محتوى جديد</p>
</my-web-component>

👉 سيتم إدخال المحتوى المار بين علامات مكون الويب في موضع <slot />.

إضافة صورة في مكون ويب SvelteKit

لإدراج صورة في مكون ويب باستخدام SvelteKit، لا يمكنك استخدام مجلد static مباشرة. يجب عليك استيراد الصورة كوحدة حتى يتم تضمينها بشكل صحيح في البناء.

استيراد صورة

في مكونك my-web-component.svelte :

import logo from './assets/favicon.svg';

استخدام الصورة في القالب

<img src={logo} alt="شعار SvelteKit" />

مكون كامل

<svelte:options customElement="my-web-component" />

<script lang="ts">
  import logo from './assets/favicon.svg';

  let { name = 'العالم' } = $props();

  const getName = (): string => {
    return name;
  };

  const setName = (newName: string) => {
    name = newName;
  };

  $effect(() => {
    const host = $host();

    Object.assign(host, {
      getName,
      setName
    });
  });
</script>

<img src={logo} alt="شعار SvelteKit" />

<p>قبل مرحبا {name}</p>
<slot />
<p>بعد مرحبا {name}</p>

<style lang="scss">
  p {
    color: red;
  }
</style>

👉 سيتم تحسين الصورة تلقائيًا وتضمينها في حزمة مكون الويب النهائية.

الاستماع إلى أحداث عنصر الويب في SvelteKit

لتواصل من عنصر ويب إلى تطبيقك، يمكنك إصدار أحداث مخصصة (CustomEvent) والاستماع إليها من جانب العميل.

إنشاء حدث في المكون

أضف زرًا ووظيفة في مكونك:

<button on:click={handleClick}>اختبار</button>

const handleClick = () => {
  const event = new CustomEvent('test', {
    detail: {
      name
    }
  });

  $host().dispatchEvent(event);
};

إنشاء واجهة برمجة التطبيقات للاستماع إلى الأحداث

لتبسيط الاستماع إلى الأحداث، يمكنك الكشف عن طريقة on:

const on = (event: string, callback: Function) => {
  $host().addEventListener(event, (e: any) => callback(e.detail));
};

الكشف عن الطريقة

$effect(() => {
  const host = $host();

  Object.assign(host, {
    getName,
    setName,
    on
  });
});

تحديث التهيئة في جانب SvelteKit

let wc: HTMLElement & {
  getName: () => string;
  setName: (newName: string) => void;
  on: (event: string, callback: Function) => void;
};

الاستماع إلى الحدث في الصفحة

wc.on('test', (detail: { name: string }) => {
  console.log(detail);
});

مثال كامل على جانب SvelteKit

<script lang="ts">
  import { onMount } from 'svelte';

  let wc: HTMLElement & {
    getName: () => string;
    setName: (newName: string) => void;
    on: (event: string, callback: Function) => void;
  };

  onMount(() => {
    wc.on('test', (detail: { name: string }) => {
      console.log(detail);
    });
  });
</script>

<svelte:head>
  <script type="module" src="/webcomponent/example-webcomponent-0.0.1.js"></script>
</svelte:head>

<my-web-component bind:this={wc} name="Admin"></my-web-component>

النتيجة

{ name: 'Admin' }

👉 هذه الطريقة تتيح لك التواصل بين عنصر الويب الخاص بك وأي تطبيق عبر واجهة برمجة أحداث بسيطة وفعالة.

الخاتمة

أنت الآن تعرف كيفية إنشاء مكون ويب باستخدام SvelteKit، بناءه باستخدام Vite ودمجه في أي مشروع.

• إنشاء مكون ويب باستخدام SvelteKit
• تكوين وبناء باستخدام Vite
• دمجه في أي بيئة (HTML، React، WordPress…)
• إدارة الخصائص، والأساليب، والمنافذ، والأحداث

👉 مكونات الويب هي حل قوي لإنشاء أدوات قابلة للاستخدام المتكرر، سواءً كان ذلك لبرمجيات كخدمة، أو نصوص مضمّنة، أو ملحقات متعددة المنصات.

بفضل SvelteKit، يمكنك إنشاء مكونات عالية الأداء، خفيفة الوزن، ومستقلة تمامًا عن الإطار المستخدم على جانب العميل.

🚀 يمكنك الآن إنشاء أدواتك الخاصة ودمجها في كل مكان: صفحات الهبوط، أنظمة إدارة المحتوى، تطبيقات الويب أو مشاريع العملاء.

الذهاب إلى أبعد من ذلك

هل ترغب في إنشاء مكون ويب مخصص لمشروعك أو لشركتك؟

أقدم حلولاً مخصصة لتطوير وحدات أداء، قابلة للتكامل مع أي منصة (ووردبريس، شوبفاي، SaaS…).