Vue Academy · درس

تصريحات TypeScript لمكتبات المكوّنات

‏vite-plugin-dts، وإنشاء ملفات .d.ts، وكتابة أنواع Props للمكوّنات لمستخدمي المكتبة

تصريحات TypeScript لمكتبات المكوّنات درس مجاني في Vue Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Vue Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Vue Academy 4 دروس في المجموع.

لماذا نحتاج إلى تصريحات الأنواع

يتوقع مستهلكو TypeScript ملفات .d.ts للحصول على الإكمال التلقائي والتحقق من الأنواع في مكوّناتك وخصائصها. وينبغي للمكتبة المنشورة أن تتضمن التصريحات المُولَّدة إلى جانب JavaScript الخاص بها.

vite-plugin-dts

ينشئ vite-plugin-dts ملفات .d.ts من المصدر أثناء بناء Vite، بما في ذلك الأنواع الخاصة بمكوّنات .vue أحادية الملف.

npm install -D vite-plugin-dts

إضافة الإضافة

أضف dts() إلى مصفوفة الإضافات. حيث تعمل بعد التجميع لإخراج التصريحات إلى dist.

import dts from "vite-plugin-dts";

export default defineConfig({
  plugins: [vue(), dts()]
});

insertTypesEntry

يُخرج الخيار insertTypesEntry نقطة إدخال واحدة باسم index.d.ts تعيد تصدير جميع أنواعك، بما يطابق نقطة إدخال JavaScript الخاصة بك.

dts({
  insertTypesEntry: true
})

ملفات d.ts المُولَّدة

بعد البناء، يحتوي dist على ملفات .d.ts التي تعكس بنية مصدرك، إضافةً إلى تصريح نقطة الإدخال المجمّع. وتصف هذه الملفات خصائص المكوّنات، والأحداث المُصدرة، والتصديرات.

// dist/index.d.ts
export { MyButton } from "./MyButton.vue";
// dist/MyButton.vue.d.ts describes its props

حقل types في package.json

وجّه المستهلكين إلى تصريح نقطة الإدخال باستخدام الحقل types (أو typings) حتى يتمكن TypeScript من تحديد أنواع مكتبتك.

{
  "types": "./dist/index.d.ts"
}

types في خريطة exports

تتيح الحزم الحديثة أيضًا الأنواع لكل نقطة إدخال ضمن خريطة exports، حتى تُحلّ عمليات الاستيراد من المسارات الفرعية بشكل صحيح.

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/my-ui-lib.es.js"
    }
  }
}

الإكمال التلقائي للمكوّنات العامة

عندما يسجّل المستهلكون مكوّناتك بشكل عام، يحتاج TypeScript إلى التصريح عنها في الواجهة GlobalComponents للحصول على الإكمال التلقائي للقوالب والتحقق من الخصائص.

توسيع GlobalComponents

أدرج توسعة وحدة تضيف مكوّناتك إلى GlobalComponents الخاصة بـ vue. وسيحصل المستهلكون الذين يشيرون إلى أنواعك على IntelliSense في القوالب.

// global.d.ts
import MyButton from "./MyButton.vue";

declare module "vue" {
  export interface GlobalComponents {
    MyButton: typeof MyButton;
  }
}
export {};

تحديد أنواع خصائص المكوّنات

استخدم defineProps مع نوع TypeScript، حتى يحمل التصريح المُولَّد أنواع الخصائص الدقيقة إلى المستهلكين.

// MyButton.vue <script setup lang="ts">
defineProps<{
  label: string;
  disabled?: boolean;
}>();

التحقق من الأنواع

قبل النشر، شغّل tsc --noEmit في تطبيق مستهلك نموذجي (أو استخدم أداة مثل attw/are-the-types-wrong) للتأكد من حل التصريحات والتحقق من الخصائص.

npx tsc --noEmit

تحقق سريع

ماذا تمنح توسعة GlobalComponents لمستهلكي المكتبة؟

مراجعة

استخدم vite-plugin-dts مع insertTypesEntry لإنشاء ملفات .d.ts، ووجّه حقل types في package.json (وخريطة exports) إلى تصريح نقطة الإدخال، وأدرج توسعة GlobalComponents حتى يحصل المستهلكون على الإكمال التلقائي للقوالب. حدّد أنواع الخصائص باستخدام defineProps وتحقق منها باستخدام tsc --noEmit.

الأسئلة الشائعة

هل درس «تصريحات TypeScript لمكتبات المكوّنات» مجاني؟

نعم — نص درس «تصريحات TypeScript لمكتبات المكوّنات» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Vue Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Vue Academy 4 دروس في المجموع.

ماذا ستتعلم في «تصريحات TypeScript لمكتبات المكوّنات»؟

‏vite-plugin-dts، وإنشاء ملفات .d.ts، وكتابة أنواع Props للمكوّنات لمستخدمي المكتبة تتمرن على Vue Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Vue Academy؟

لا تُشترط خبرة سابقة. Vue Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «تصريحات TypeScript لمكتبات المكوّنات»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Vue Academy هذا؟

نعم. كل درس في Vue Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Vue Academy